feat: recognize provider cost data from usage.cost_details block (#439)

## Summary

Some providers include detailed cost breakdowns directly in the response
`usage` object rather than via SSE `: cost` comment lines. This PR adds
support for recognizing and using that cost data when available.

### The new format

Providers may return a `usage` block like:

```json
"usage": {
  "prompt_tokens": 23,
  "total_tokens": 66,
  "completion_tokens": 43,
  "cost": 0.00017465,
  "cost_details": {
    "total_cost": 0.00017465,
    "input_cost": 0.00002415,
    "output_cost": 0.0001505,
    "cached_input_cost": 0,
    "cache_write_input_cost": 0,
    "upstream_inference_cost": 0.00017465,
    "request_cost": 0,
    "web_search_cost": 0,
    "data_storage_cost": 0.00000106
  }
}
```

When `cost_details` is present, we use the provider's actual per-bucket
breakdown (`input_cost`, `output_cost`, `cached_input_cost`,
`cache_write_input_cost`) directly instead of proportionally
distributing a total.

## Changes

- **`utils/usage-normalizer.ts`**: Add `extractUsageCostDetails()` —
safely extracts `cost_details` from provider usage blocks; returns
`null` when absent (providers that don't use this format are
unaffected). Also updated `normalizeOpenAIChatUsage()` to extract
`cache_write_tokens` from `prompt_tokens_details`.
- **`utils/provider-cost.ts`**: Add `applyUsageCostDetails()` — applies
per-bucket breakdown when available, falls back to proportional
distribution otherwise.
- **`services/inspectors/usage-logging.ts`**: Wire `cost_details`
extraction into the streaming cost path (only applies if no SSE-reported
cost was found).
- **`services/response-handler.ts`**: Same for the non-streaming (unary)
path.

## Key design decisions

- **Fully optional/defensive**: `extractUsageCostDetails()` returns
`null` when `usage.cost_details` doesn't exist — providers that don't
use this format are completely unaffected
- **SSE `: cost` comments take precedence**: The `!providerReportedCost`
guard ensures `cost_details` only applies when no SSE-reported cost was
found
- **Per-bucket breakdown preferred**: When the provider gives explicit
`input_cost`/`output_cost`/etc., we use those directly instead of
proportional splitting

## Test plan

- [x] `extractUsageCostDetails` — extracts from the new format, falls
back to `usage.cost`/`usage.estimated_cost`, returns null for
missing/invalid data
- [x] `applyUsageCostDetails` — uses per-bucket breakdown, falls back to
proportional, handles zero/null costs
- [x] `normalizeOpenAIChatUsage` — extracts `cache_write_tokens` from
`prompt_tokens_details`
- [x] Precedence: SSE `: cost` comments > `cost_details` > calculated
costs
- [x] All 1367 existing tests pass

Author: mcowger

packages/backend/src/services/inspectors/usage-logging.ts

@@ -10,9 +10,10 @@ import {
   normalizeGeminiUsage,
   normalizeOpenAIChatUsage,
   normalizeOpenAIResponsesUsage,
+  extractUsageCostDetails,
 } from '../../utils/usage-normalizer';
 import { estimateKwhUsed } from '../inference-energy';
-import { applyProviderReportedCost } from '../../utils/provider-cost';
+import { applyProviderReportedCost, applyUsageCostDetails } from '../../utils/provider-cost';
 import { DEFAULT_MODEL, DEFAULT_GPU_PARAMS } from '@plexus/shared';
 import { recordQuotaUsage } from '../quota/quota-middleware';
 
@@ -149,6 +150,15 @@ export class UsageInspector extends PassThrough {
         applyProviderReportedCost(this.usageRecord, reconstructed.providerReportedCost);
       }
 
+      // Override with provider-reported cost from usage.cost_details if available
+      // Some providers include detailed cost breakdowns in the usage block
+      if (!this.usageRecord.providerReportedCost && reconstructed?.usage) {
+        const usageCostDetails = extractUsageCostDetails(reconstructed.usage);
+        if (usageCostDetails) {
+          applyUsageCostDetails(this.usageRecord, usageCostDetails);
+        }
+      }
+
       // Use provider-reported energy if available, otherwise estimate
       // Some providers emit `: energy {"energy_kwh": ...}` as SSE comments
       if (reconstructed?.providerReportedEnergy?.energy_kwh != null) {

packages/backend/src/services/response-handler.ts

@@ -10,7 +10,8 @@ import { DebugLoggingInspector, UsageInspector } from './inspectors';
 import { Readable } from 'stream';
 import { DebugManager } from './debug-manager';
 import { estimateKwhUsed } from './inference-energy';
-import { applyProviderReportedCost } from '../utils/provider-cost';
+import { applyProviderReportedCost, applyUsageCostDetails } from '../utils/provider-cost';
+import { extractUsageCostDetails } from '../utils/usage-normalizer';
 import { StallInspector, type StallConfig } from './inspectors/stall-inspector';
 import { DEFAULT_GPU_PARAMS, DEFAULT_MODEL } from '@plexus/shared';
 import type { GpuParams } from '@plexus/shared';
@@ -502,6 +503,14 @@ async function finalizeUsage(
   if (reconstructed?.providerReportedCost) {
     applyProviderReportedCost(usageRecord, reconstructed.providerReportedCost);
   }
+
+  // Also check for cost_details in the usage block (some providers embed costs there)
+  if (!usageRecord.providerReportedCost && reconstructed?.usage) {
+    const usageCostDetails = extractUsageCostDetails(reconstructed.usage);
+    if (usageCostDetails) {
+      applyUsageCostDetails(usageRecord, usageCostDetails);
+    }
+  }
   usageRecord.responseStatus = 'success';
   usageRecord.durationMs = Date.now() - startTime;