@x12i/ai-gateway 9.3.0 → 9.3.5

package/README.md

@@ -63,6 +63,7 @@ npm install @x12i/ai-gateway
 **📚 Documentation**: After installation, documentation is available in:
 - `node_modules/@x12i/ai-gateway/CONTENT_RESOLVER_UPSTREAM_GUIDE.md` - **Content resolver (nx-content)**: config, keys, local/git, upstream checklist
 - `node_modules/@x12i/ai-gateway/docs/IDENTITY_OBJECT_CONTRACT.md` - **Identity contract** for Activix (`sessionId` + `instance`)
+- `node_modules/@x12i/ai-gateway/docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md` - **Invoke metadata**, cost/billing (G8), output contract (G6), Activix completion fields
 - `node_modules/@x12i/ai-gateway/docs/LOGGER_INITIALIZATION.md` - **Required reading**: How to properly initialize logger
 - `node_modules/@x12i/ai-gateway/TROUBLESHOOTING.md` - Troubleshooting guide
 - `node_modules/@x12i/ai-gateway/TROUBLESHOOTING_TOOLBOX.md` - Diagnostic tools
@@ -309,7 +310,7 @@ The gateway reads **Mongo connection** settings from the environment, but **coll
 `ActivityManager` drives **`@x12i/activix` v7** with a **two-phase** API:
 
 1. **`startRecord`** — Inserts a new document with **`status: 'started'`**, **`startTime`**, **`runContext`** (same object as **`request.identity`**), root **`request`** / **`config`** snapshots, gateway metadata (e.g. **`activityType`**, **`aiRequestId`**), and the initial **`outer`** fragment (see below). Activix returns **`activityId`** (prefix **`act-`**, configured as the collection **`primaryKey`**); that id is used for all later updates — **not** `jobId`.
-2. **`completeRecord`** or **`failRecord`** — Patches the **same** document by **`activityId`**. Success adds **`response`**, **`endTime`**, **`duration`**, **`cost`**, refreshed **`status`**, and sets **`outer.output`** to the completion payload. Failure adds error details (and may attach **`outer.output`** for certain failure modes such as response parsing).
+2. **`completeRecord`** or **`failRecord`** — Patches the **same** document by **`activityId`**. On success, adds **`response`**, **`endTime`**, **`duration`**, root **`cost`** / **`costUsd`** / **`costStatus`**, sets **`outer.output`** to the completion payload, merges billing into **`outer.metadata`**, and when priced or unpriced with usage, sets Activix **`outer.cost`** (`usd`, `tokens`, `provider`, `model`, optional `details`). Failure adds error details (and may attach **`outer.output`** for certain failure modes such as response parsing).
 
 **How a document is shaped (reading `ai-actions` in Mongo)**
 
@@ -317,7 +318,7 @@ The gateway reads **Mongo connection** settings from the environment, but **coll
 - **Root-level copies** of common identity fields may appear beside **`runContext`** for convenient indexing; treat **`runContext`** as the full envelope when in doubt.
 - **`request`**: Structured snapshot only — **`raw`** / **`parsed`** instructions, context, prompt; **`messages`**; **`workingMemory`** (template/user payload). There is **no** separate legacy **`input`** field on this object; use **`workingMemory`**.
 - **`config`**: `model`, `provider`, `temperature`, `maxTokens`, **`rawConfig`** (exact router config).
-- **`outer`**: Activix v7 **validated I/O** at the document root. At **start**, **`outer.input`** contains **`activityType`** and the same **`request`** snapshot as root **`request`** when a body exists (`{ activityType, request }`). At **success**, **`outer.output`** matches the **`response`** object written on completion. Root **`request`** / **`response`** support querying and older tooling; **`outer`** satisfies Activix’s envelope — so the same logical request snapshot can appear both at **`request`** and under **`outer.input.request`** by design. Large provider blobs (**`response.content.fullResponse`**) and size limits are described in [Activities outer duplication & payload controls](./docs/ACTIVITIES_OUTER_DUPLICATION.md).
+- **`outer`**: Activix v7 **validated I/O** at the document root. At **start**, **`outer.input`** contains **`activityType`** and the same **`request`** snapshot as root **`request`** when a body exists (`{ activityType, request }`). At **success**, **`outer.output`** matches the **`response`** object written on completion; **`outer.metadata`** mirrors routing and billing from **`response.metadata`** (`modelUsed`, `provider`, `cost`, `costUsd`, `costStatus`, optional `costBreakdown`); **`outer.cost`** holds the canonical Activix cost object when usage or price is known (see [Cost reporting](#cost-reporting-invoke-response--activix-run-analysis-g8) below). Root **`request`** / **`response`** support querying and older tooling; **`outer`** satisfies Activix’s envelope — so the same logical request snapshot can appear both at **`request`** and under **`outer.input.request`** by design. Large provider blobs (**`response.content.fullResponse`**) and size limits are described in [Activities outer duplication & payload controls](./docs/ACTIVITIES_OUTER_DUPLICATION.md).
 
 **Environment variable priority (Activix / Mongo — implemented in `@x12i/activix`, not in `activity-tracking-config.ts`):**
 - **Mongo URI**: `MONGO_LOGS_URI` if set, otherwise **`MONGO_URI`**. If neither is set, Activix cannot use the database.
@@ -401,6 +402,24 @@ const gateway = new AIGateway({
 });
 ```
 
+#### Cost reporting (invoke response + Activix, Run Analysis G8)
+
+Billing is resolved once per successful **`invoke()`** / **`invokeChat()`** via **`resolveCostCompletionWithAiTools`** (see [`docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md`](./docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md)):
+
+| Layer | Fields |
+|--------|--------|
+| **Router** (`@x12i/ai-providers-router`) | Preferred source: **`metadata.costStatus`** (`priced` \| `unpriced`), **`metadata.costUsd`** / **`metadata.cost`** when priced |
+| **Gateway response** | Same slice on **`response.metadata`**: **`costStatus`**, **`costUsd`**, **`cost`**, optional **`costBreakdown`** (when **`aiTools.calculateCost`** and catalog pricing apply and the router left cost unpriced) |
+| **Activix activity (on `logSuccess`)** | Root **`cost`**, **`costUsd`**, **`costStatus`**; **`outer.metadata`** mirror; **`outer.cost`** (`usd`, `tokens` with `input`/`output`/`total`, `provider`, `model`, `details.costStatus`, optional `details.costBreakdown`) |
+
+**`costStatus` semantics:**
+
+- **`priced`** — **`costUsd`** / **`cost`** is a finite USD amount for this call (from the router or from **`@x12i/ai-tools`** catalog **`CostCalculator`** when the router did not price).
+- **`unpriced`** — Token usage was recorded but no authoritative USD price was available (explicit router **`unpriced`** is never overridden by catalog).
+- Omitted — No non-zero token usage (no billing signal).
+
+Requires **`enableActivityTracking: true`** (default when Mongo/env is configured) for Activix persistence; invoke metadata is always set on the gateway response regardless.
+
 **Tests before release:**
 
 ```bash
@@ -472,7 +491,7 @@ When the gateway constructs Activix internally, each collection uses **`primaryK
 - **Config data**: Stored in **`config`** (model, provider, temperature, maxTokens, **`rawConfig`**)
 - **Response data**: Stored in **`response`** on completion (content, metadata, optional **`fullResponse`** per diagnostics)
 - **Activix I/O**: Root **`outer`** — **`outer.input`** at start, **`outer.output`** on success (and some failure paths)
-- **Cost**: Calculated and stored per activity on success
+- **Cost / billing**: On success, root **`cost`**, **`costUsd`**, **`costStatus`**, plus **`outer.metadata`** and **`outer.cost`** (same values as **`response.metadata`** from the invoke path — router passthrough or catalog pricing via **`@x12i/ai-tools`**)
 
 **Best Practices for Type IDs:**
 - **`jobTypeId`**: Use MD5 hash of your job type string (e.g., `MD5('data-processing-job')`) for consistent job-level aggregation
@@ -1119,7 +1138,7 @@ The gateway uses **`@x12i/activix` v7** (xronox-activitix) for full lifecycle lo
      - Sends **`runContext`**, **`request`**, **`config`**, **`startTime`**, **`status: 'started'`**, plus Activix **`outer.input`** (wraps **`activityType`** and the same **`request`** snapshot when present — see section 2).
      - Returns **`activityId`** (and record payload) for phase 2.
    - **Phase 2 (complete / fail)**: Updates the SAME document by **`activityId`**
-     - Success: **`response`**, **`cost`**, **`endTime`**, **`duration`**, **`status`**, and **`outer.output`** set to the completion **`response`** payload (request/config are **not** re-sent).
+     - Success: **`response`**, root **`cost`** / **`costUsd`** / **`costStatus`**, **`endTime`**, **`duration`**, **`status`**, **`outer.output`** (completion payload), **`outer.metadata`** (routing + billing mirror), and **`outer.cost`** when usage or price is known (see [Cost reporting](#cost-reporting-invoke-response--activix-run-analysis-g8)).
      - Failure: error payload and timing; optional **`response`** / **`outer.output`** only for specific failure kinds.
 
 4. **Structured fields vs Activix `outer` (v2.6.0+):**
@@ -1264,8 +1283,22 @@ Example shape for a completed row in **`ai-actions`** (`activityType: 'gateway-i
   // completeRecord: outer.output ← same object as root `response` on success
   outer: {
     input: { activityType: 'gateway-invocation', request: { /* same snapshot as root request */ } },
-    output: { /* success: normalized gateway response object */ },
-    metadata: { /* tier metadata / aiRequestId routing — see @x12i/activix */ }
+    output: { /* success: gateway activity response (content, parsed, metadata, usage) */ },
+    metadata: {
+      modelUsed: 'openai/gpt-5-nano-2025-08-07',
+      provider: 'openrouter',
+      cost: 0.0000348,
+      costUsd: 0.0000348,
+      costStatus: 'priced'
+    },
+    cost: {
+      usd: 0.0000348,
+      unit: 'USD',
+      tokens: { input: 16, output: 85, total: 101 },
+      provider: 'openrouter',
+      model: 'openai/gpt-5-nano-2025-08-07',
+      details: { costStatus: 'priced' /* optional costBreakdown when aiTools.costIncludeBreakdown */ }
+    }
   },
   // inner: optional step array for multi-step flows (see @x12i/activix docs)
   
@@ -1306,8 +1339,10 @@ Example shape for a completed row in **`ai-actions`** (`activityType: 'gateway-i
     metadata: {...}
   },
   
-  // Cost (from logSuccess)
-  cost: 0.002,
+  // Billing (from logSuccess — mirrors response.metadata from invoke)
+  cost: 0.0000348,
+  costUsd: 0.0000348,
+  costStatus: 'priced',
   
   // Metadata
   createdAt: Date,
@@ -1319,7 +1354,7 @@ Example shape for a completed row in **`ai-actions`** (`activityType: 'gateway-i
 - ✅ Each activity = separate Mongo document (**`_id`**) with stable **`activityId`** (`act-…`) for Activix APIs
 - ✅ **`aiRequestId`** = per-request correlation (required on invoke)
 - ✅ **`runContext.jobId`** / **`runContext.taskId`** = upstream identity (required on invoke since v9+)
-- ✅ Request/config sent at **start**; response/timing/cost at **complete**
+- ✅ Request/config sent at **start**; response/timing/billing (`cost`, `costUsd`, `costStatus`, `outer.cost`) at **complete**
 - ✅ Updates target **`activityId`** from **`startRecord`**, not **`jobId`**
 
 #### Retry Tracking (@x12i/activix v7)
@@ -1455,8 +1490,16 @@ const response = await gateway.invoke({
       cacheTotalTokens?: number
     },
     model?: string,             // Model ID used (e.g., 'gpt-4o', 'claude-sonnet-4')
+    modelUsed?: string,         // Resolved/served model id (when distinct from request model)
     provider?: string,          // Provider used (e.g., 'openai', 'anthropic')
-    cost?: number,              // Cost in USD (if available)
+    costStatus?: 'priced' | 'unpriced',  // Billing state (Run Analysis G8)
+    costUsd?: number,           // USD when costStatus === 'priced' (preferred field)
+    cost?: number,              // USD mirror of costUsd when priced
+    costBreakdown?: {           // Optional when aiTools catalog pricing runs (calculateCost + breakdown)
+      promptCostUsd?: number;
+      completionCostUsd?: number;
+      // ...other breakdown keys from @x12i/ai-tools
+    },
     
     // ============================================
     // Inference Output Parsing (if inferenceType provided)
@@ -1503,8 +1546,10 @@ const response = await gateway.invoke({
 - `metadata.jobId` - Job ID for correlation
 - `metadata.latencyMs` - Request duration in milliseconds
 - `metadata.tokens` - Token breakdown (prompt, completion, total, cache tokens)
-- `metadata.cost` - Cost in USD
-- `metadata.model` - Model ID used
+- `metadata.costStatus` - `priced` | `unpriced` (see [Cost reporting](#cost-reporting-invoke-response--activix-run-analysis-g8))
+- `metadata.costUsd` / `metadata.cost` - USD when priced
+- `metadata.costBreakdown` - Optional catalog breakdown when `aiTools.calculateCost` applies
+- `metadata.model` / `metadata.modelUsed` - Model id used
 - `metadata.provider` - Provider used
 
 #### Example: Full Response
@@ -1554,8 +1599,10 @@ const response = await gateway.invoke({
       completion: 50,
       total: 150
     },
-    model: 'gpt-5-mini',
+    modelUsed: 'gpt-5-mini',
     provider: 'openai',
+    costStatus: 'priced',
+    costUsd: 0.002,
     cost: 0.002,
     
     // Inference output (parsed)

package/dist/activity-manager.d.ts

@@ -121,6 +121,7 @@ export declare class ActivityManager {
     logSuccess(activity: ActivityMetadata | undefined, details: {
         cost?: number;
         costStatus?: 'priced' | 'unpriced';
+        costBreakdown?: Record<string, unknown>;
         response: any;
         endTime: number;
         duration: number;

package/dist/activity-manager.js

@@ -133,34 +133,120 @@ function logUpstreamIdentityWarnings(logger, incomingIdentity, merged) {
         }));
     }
 }
-/** Routing / generation facts from gateway response metadata for Activix `outer.metadata` on completion. */
-function pickActivixCompletionRoutingMetadata(response) {
+/** Token counts for Activix `outer.cost.tokens` (maps gateway prompt/completion → input/output). */
+function pickActivixUsageTokens(response) {
     if (response == null || typeof response !== 'object')
-        return {};
-    const meta = response.metadata;
-    if (meta == null || typeof meta !== 'object')
-        return {};
-    const m = meta;
+        return undefined;
+    const r = response;
+    const raw = (r.usage != null && typeof r.usage === 'object' ? r.usage : undefined) ??
+        (r.metadata != null && typeof r.metadata === 'object'
+            ? r.metadata.tokens
+            : undefined);
+    if (raw == null || typeof raw !== 'object')
+        return undefined;
+    const t = raw;
+    const input = typeof t.prompt === 'number'
+        ? t.prompt
+        : typeof t.input === 'number'
+            ? t.input
+            : undefined;
+    const output = typeof t.completion === 'number'
+        ? t.completion
+        : typeof t.output === 'number'
+            ? t.output
+            : undefined;
+    const total = typeof t.total === 'number' ? t.total : undefined;
+    if (input === undefined && output === undefined && total === undefined)
+        return undefined;
+    return {
+        ...(input !== undefined ? { input } : {}),
+        ...(output !== undefined ? { output } : {}),
+        ...(total !== undefined ? { total } : {})
+    };
+}
+/**
+ * Activix v6+ `outer.cost` from gateway billing + routing metadata (Run Analysis G8).
+ */
+function buildActivixOuterCost(routingMeta, billing, response) {
+    const usd = typeof billing.cost === 'number' && Number.isFinite(billing.cost)
+        ? billing.cost
+        : typeof routingMeta.costUsd === 'number' && Number.isFinite(routingMeta.costUsd)
+            ? routingMeta.costUsd
+            : typeof routingMeta.cost === 'number' && Number.isFinite(routingMeta.cost)
+                ? routingMeta.cost
+                : undefined;
+    const tokens = pickActivixUsageTokens(response);
+    const provider = typeof routingMeta.provider === 'string' ? routingMeta.provider : undefined;
+    const model = typeof routingMeta.modelUsed === 'string'
+        ? routingMeta.modelUsed
+        : typeof routingMeta.model === 'string'
+            ? routingMeta.model
+            : undefined;
+    const details = {};
+    if (billing.costStatus === 'priced' || billing.costStatus === 'unpriced') {
+        details.costStatus = billing.costStatus;
+    }
+    if (billing.costBreakdown != null && typeof billing.costBreakdown === 'object') {
+        details.costBreakdown = billing.costBreakdown;
+    }
+    const hasDetails = Object.keys(details).length > 0;
+    if (usd === undefined && !tokens && !provider && !model && !hasDetails) {
+        return undefined;
+    }
+    return {
+        ...(usd !== undefined ? { usd, unit: 'USD' } : {}),
+        ...(tokens ? { tokens } : {}),
+        ...(provider ? { provider } : {}),
+        ...(model ? { model } : {}),
+        ...(hasDetails ? { details } : {})
+    };
+}
+/** Routing / generation facts for Activix `outer.metadata` on completion (includes billing mirror). */
+function pickActivixCompletionRoutingMetadata(response, billing) {
     const out = {};
-    if (typeof m.modelUsed === 'string')
-        out.modelUsed = m.modelUsed;
-    if (typeof m.model === 'string')
-        out.model = m.model;
-    if (typeof m.provider === 'string')
-        out.provider = m.provider;
-    if (typeof m.maxTokensRequested === 'number')
-        out.maxTokensRequested = m.maxTokensRequested;
-    if (typeof m.region === 'string')
-        out.region = m.region;
-    if (m.effectiveModelConfig != null && typeof m.effectiveModelConfig === 'object') {
-        out.effectiveModelConfig = m.effectiveModelConfig;
+    if (response != null && typeof response === 'object') {
+        const meta = response.metadata;
+        if (meta != null && typeof meta === 'object') {
+            const m = meta;
+            if (typeof m.modelUsed === 'string')
+                out.modelUsed = m.modelUsed;
+            if (typeof m.model === 'string')
+                out.model = m.model;
+            if (typeof m.provider === 'string')
+                out.provider = m.provider;
+            if (typeof m.maxTokensRequested === 'number')
+                out.maxTokensRequested = m.maxTokensRequested;
+            if (typeof m.region === 'string')
+                out.region = m.region;
+            if (m.effectiveModelConfig != null && typeof m.effectiveModelConfig === 'object') {
+                out.effectiveModelConfig = m.effectiveModelConfig;
+            }
+            if (typeof m.cost === 'number' && Number.isFinite(m.cost))
+                out.cost = m.cost;
+            if (typeof m.costUsd === 'number' && Number.isFinite(m.costUsd))
+                out.costUsd = m.costUsd;
+            if (m.costStatus === 'priced' || m.costStatus === 'unpriced')
+                out.costStatus = m.costStatus;
+            if (m.costBreakdown != null && typeof m.costBreakdown === 'object') {
+                out.costBreakdown = m.costBreakdown;
+            }
+        }
+    }
+    if (billing) {
+        if ((out.costStatus !== 'priced' && out.costStatus !== 'unpriced') &&
+            (billing.costStatus === 'priced' || billing.costStatus === 'unpriced')) {
+            out.costStatus = billing.costStatus;
+        }
+        if (typeof billing.cost === 'number' && Number.isFinite(billing.cost)) {
+            if (out.cost === undefined)
+                out.cost = billing.cost;
+            if (out.costUsd === undefined)
+                out.costUsd = billing.cost;
+        }
+        if (out.costBreakdown === undefined && billing.costBreakdown != null) {
+            out.costBreakdown = billing.costBreakdown;
+        }
     }
-    if (typeof m.cost === 'number' && Number.isFinite(m.cost))
-        out.cost = m.cost;
-    if (typeof m.costUsd === 'number' && Number.isFinite(m.costUsd))
-        out.costUsd = m.costUsd;
-    if (m.costStatus === 'priced' || m.costStatus === 'unpriced')
-        out.costStatus = m.costStatus;
     return out;
 }
 function mergeGatewayActivityIdentity(request, aiRequestId, extras) {
@@ -848,13 +934,24 @@ export class ActivityManager {
                 });
                 return;
             }
+            const billingSlice = {
+                cost: details.cost,
+                costStatus: details.costStatus,
+                costBreakdown: details.costBreakdown
+            };
+            const outerMetadata = pickActivixCompletionRoutingMetadata(details.response, billingSlice);
+            const outerCost = buildActivixOuterCost(outerMetadata, billingSlice, details.response);
             await this.activix.completeRecord(activity.activityId, {
                 cost: details.cost,
+                ...(typeof details.cost === 'number' && Number.isFinite(details.cost)
+                    ? { costUsd: details.cost }
+                    : {}),
                 ...(details.costStatus ? { costStatus: details.costStatus } : {}),
                 response: details.response,
                 outer: {
                     output: details.response,
-                    metadata: pickActivixCompletionRoutingMetadata(details.response)
+                    metadata: outerMetadata,
+                    ...(outerCost ? { cost: outerCost } : {})
                 },
                 endTime: details.endTime,
                 duration: details.duration

package/dist/gateway.js

@@ -142,7 +142,10 @@ export class AIGateway {
                                 : { cost: costCompletionChat.cost })
                         }
                         : {}),
-                    ...(costCompletionChat.costStatus ? { costStatus: costCompletionChat.costStatus } : {})
+                    ...(costCompletionChat.costStatus ? { costStatus: costCompletionChat.costStatus } : {}),
+                    ...(costCompletionChat.costBreakdown
+                        ? { costBreakdown: costCompletionChat.costBreakdown }
+                        : {})
                 }
             };
             // Track activity success if activity was started
@@ -587,6 +590,7 @@ export class AIGateway {
                         }
                         : {}),
                     ...(costCompletion.costStatus ? { costStatus: costCompletion.costStatus } : {}),
+                    ...(costCompletion.costBreakdown ? { costBreakdown: costCompletion.costBreakdown } : {}),
                     ...(traceEnabled
                         ? {
                             requestIds: traceRequestIds,

package/dist-cjs/activity-manager.cjs

@@ -133,34 +133,120 @@ function logUpstreamIdentityWarnings(logger, incomingIdentity, merged) {
         }));
     }
 }
-/** Routing / generation facts from gateway response metadata for Activix `outer.metadata` on completion. */
-function pickActivixCompletionRoutingMetadata(response) {
+/** Token counts for Activix `outer.cost.tokens` (maps gateway prompt/completion → input/output). */
+function pickActivixUsageTokens(response) {
     if (response == null || typeof response !== 'object')
-        return {};
-    const meta = response.metadata;
-    if (meta == null || typeof meta !== 'object')
-        return {};
-    const m = meta;
+        return undefined;
+    const r = response;
+    const raw = (r.usage != null && typeof r.usage === 'object' ? r.usage : undefined) ??
+        (r.metadata != null && typeof r.metadata === 'object'
+            ? r.metadata.tokens
+            : undefined);
+    if (raw == null || typeof raw !== 'object')
+        return undefined;
+    const t = raw;
+    const input = typeof t.prompt === 'number'
+        ? t.prompt
+        : typeof t.input === 'number'
+            ? t.input
+            : undefined;
+    const output = typeof t.completion === 'number'
+        ? t.completion
+        : typeof t.output === 'number'
+            ? t.output
+            : undefined;
+    const total = typeof t.total === 'number' ? t.total : undefined;
+    if (input === undefined && output === undefined && total === undefined)
+        return undefined;
+    return {
+        ...(input !== undefined ? { input } : {}),
+        ...(output !== undefined ? { output } : {}),
+        ...(total !== undefined ? { total } : {})
+    };
+}
+/**
+ * Activix v6+ `outer.cost` from gateway billing + routing metadata (Run Analysis G8).
+ */
+function buildActivixOuterCost(routingMeta, billing, response) {
+    const usd = typeof billing.cost === 'number' && Number.isFinite(billing.cost)
+        ? billing.cost
+        : typeof routingMeta.costUsd === 'number' && Number.isFinite(routingMeta.costUsd)
+            ? routingMeta.costUsd
+            : typeof routingMeta.cost === 'number' && Number.isFinite(routingMeta.cost)
+                ? routingMeta.cost
+                : undefined;
+    const tokens = pickActivixUsageTokens(response);
+    const provider = typeof routingMeta.provider === 'string' ? routingMeta.provider : undefined;
+    const model = typeof routingMeta.modelUsed === 'string'
+        ? routingMeta.modelUsed
+        : typeof routingMeta.model === 'string'
+            ? routingMeta.model
+            : undefined;
+    const details = {};
+    if (billing.costStatus === 'priced' || billing.costStatus === 'unpriced') {
+        details.costStatus = billing.costStatus;
+    }
+    if (billing.costBreakdown != null && typeof billing.costBreakdown === 'object') {
+        details.costBreakdown = billing.costBreakdown;
+    }
+    const hasDetails = Object.keys(details).length > 0;
+    if (usd === undefined && !tokens && !provider && !model && !hasDetails) {
+        return undefined;
+    }
+    return {
+        ...(usd !== undefined ? { usd, unit: 'USD' } : {}),
+        ...(tokens ? { tokens } : {}),
+        ...(provider ? { provider } : {}),
+        ...(model ? { model } : {}),
+        ...(hasDetails ? { details } : {})
+    };
+}
+/** Routing / generation facts for Activix `outer.metadata` on completion (includes billing mirror). */
+function pickActivixCompletionRoutingMetadata(response, billing) {
     const out = {};
-    if (typeof m.modelUsed === 'string')
-        out.modelUsed = m.modelUsed;
-    if (typeof m.model === 'string')
-        out.model = m.model;
-    if (typeof m.provider === 'string')
-        out.provider = m.provider;
-    if (typeof m.maxTokensRequested === 'number')
-        out.maxTokensRequested = m.maxTokensRequested;
-    if (typeof m.region === 'string')
-        out.region = m.region;
-    if (m.effectiveModelConfig != null && typeof m.effectiveModelConfig === 'object') {
-        out.effectiveModelConfig = m.effectiveModelConfig;
+    if (response != null && typeof response === 'object') {
+        const meta = response.metadata;
+        if (meta != null && typeof meta === 'object') {
+            const m = meta;
+            if (typeof m.modelUsed === 'string')
+                out.modelUsed = m.modelUsed;
+            if (typeof m.model === 'string')
+                out.model = m.model;
+            if (typeof m.provider === 'string')
+                out.provider = m.provider;
+            if (typeof m.maxTokensRequested === 'number')
+                out.maxTokensRequested = m.maxTokensRequested;
+            if (typeof m.region === 'string')
+                out.region = m.region;
+            if (m.effectiveModelConfig != null && typeof m.effectiveModelConfig === 'object') {
+                out.effectiveModelConfig = m.effectiveModelConfig;
+            }
+            if (typeof m.cost === 'number' && Number.isFinite(m.cost))
+                out.cost = m.cost;
+            if (typeof m.costUsd === 'number' && Number.isFinite(m.costUsd))
+                out.costUsd = m.costUsd;
+            if (m.costStatus === 'priced' || m.costStatus === 'unpriced')
+                out.costStatus = m.costStatus;
+            if (m.costBreakdown != null && typeof m.costBreakdown === 'object') {
+                out.costBreakdown = m.costBreakdown;
+            }
+        }
+    }
+    if (billing) {
+        if ((out.costStatus !== 'priced' && out.costStatus !== 'unpriced') &&
+            (billing.costStatus === 'priced' || billing.costStatus === 'unpriced')) {
+            out.costStatus = billing.costStatus;
+        }
+        if (typeof billing.cost === 'number' && Number.isFinite(billing.cost)) {
+            if (out.cost === undefined)
+                out.cost = billing.cost;
+            if (out.costUsd === undefined)
+                out.costUsd = billing.cost;
+        }
+        if (out.costBreakdown === undefined && billing.costBreakdown != null) {
+            out.costBreakdown = billing.costBreakdown;
+        }
     }
-    if (typeof m.cost === 'number' && Number.isFinite(m.cost))
-        out.cost = m.cost;
-    if (typeof m.costUsd === 'number' && Number.isFinite(m.costUsd))
-        out.costUsd = m.costUsd;
-    if (m.costStatus === 'priced' || m.costStatus === 'unpriced')
-        out.costStatus = m.costStatus;
     return out;
 }
 function mergeGatewayActivityIdentity(request, aiRequestId, extras) {
@@ -848,13 +934,24 @@ export class ActivityManager {
                 });
                 return;
             }
+            const billingSlice = {
+                cost: details.cost,
+                costStatus: details.costStatus,
+                costBreakdown: details.costBreakdown
+            };
+            const outerMetadata = pickActivixCompletionRoutingMetadata(details.response, billingSlice);
+            const outerCost = buildActivixOuterCost(outerMetadata, billingSlice, details.response);
             await this.activix.completeRecord(activity.activityId, {
                 cost: details.cost,
+                ...(typeof details.cost === 'number' && Number.isFinite(details.cost)
+                    ? { costUsd: details.cost }
+                    : {}),
                 ...(details.costStatus ? { costStatus: details.costStatus } : {}),
                 response: details.response,
                 outer: {
                     output: details.response,
-                    metadata: pickActivixCompletionRoutingMetadata(details.response)
+                    metadata: outerMetadata,
+                    ...(outerCost ? { cost: outerCost } : {})
                 },
                 endTime: details.endTime,
                 duration: details.duration

package/dist-cjs/activity-manager.d.ts

@@ -121,6 +121,7 @@ export declare class ActivityManager {
     logSuccess(activity: ActivityMetadata | undefined, details: {
         cost?: number;
         costStatus?: 'priced' | 'unpriced';
+        costBreakdown?: Record<string, unknown>;
         response: any;
         endTime: number;
         duration: number;

package/dist-cjs/gateway.cjs

@@ -142,7 +142,10 @@ export class AIGateway {
                                 : { cost: costCompletionChat.cost })
                         }
                         : {}),
-                    ...(costCompletionChat.costStatus ? { costStatus: costCompletionChat.costStatus } : {})
+                    ...(costCompletionChat.costStatus ? { costStatus: costCompletionChat.costStatus } : {}),
+                    ...(costCompletionChat.costBreakdown
+                        ? { costBreakdown: costCompletionChat.costBreakdown }
+                        : {})
                 }
             };
             // Track activity success if activity was started
@@ -587,6 +590,7 @@ export class AIGateway {
                         }
                         : {}),
                     ...(costCompletion.costStatus ? { costStatus: costCompletion.costStatus } : {}),
+                    ...(costCompletion.costBreakdown ? { costBreakdown: costCompletion.costBreakdown } : {}),
                     ...(traceEnabled
                         ? {
                             requestIds: traceRequestIds,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "9.3.0",
+  "version": "9.3.5",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {
@@ -65,7 +65,7 @@
   "license": "mit",
   "dependencies": {
     "@aws-sdk/s3-request-presigner": "^3.953.0",
-    "@x12i/activix": "^7.1.0",
+    "@x12i/activix": "^7.1.2",
     "@x12i/ai-providers-router": "^4.8.0",
     "@x12i/ai-tools": "^1.0.3",
     "@x12i/catalox": "^4.2.0",