feat: capture provider cost details (#521)

## Summary

- **fix**: add `upstream_inference_cost` fallback for total cost so BYOK
requests (where `usage.cost=0`) report the real spend
- **refactor**: stop aliasing `upstream_inference_prompt_cost` →
`input_cost`; keep upstream fields separate since
`upstream_inference_prompt_cost = input_cost + cached_input_cost`
(aliasing silently zeroed out `costCached`)
- **feat**: add three-tier cost dispatch in `applyUsageCostDetails` —
superset (per-bucket gateway fields) → normal (upstream
prompt/completions split with cache ratio) → minimal (proportional
fallback)
- **test**: expand coverage with edge cases — zero-cost non-BYOK,
OpenRouter markup (cost >> upstream sum), zero prompt tokens,
heavy-cache-hit ratio split, end-to-end BYOK and non-BYOK flows

## Test plan

- [x] All 1378 backend tests pass (`bun run test:force-all`)
- [x] Biome lint clean (`bunx biome lint .`)
- [x] Each commit independently passes lint + tests (verified via `git
rebase --exec`)

> **Note:** I mixed up the branches in #443, and also mixed up #520.
That PR couldn't be reopened due to a force-push. This replaces that PR.

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Matt Cowger <mcowger@users.noreply.github.com>
Co-authored-by: Matt Cowger <matt@cowger.us>

Author: 3 people

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

@@ -7,6 +7,7 @@ import { calculateCosts } from '../../utils/calculate-costs';
 import { DebugManager } from '../debug-manager';
 import { estimateTokensFromReconstructed, estimateInputTokens } from '../../utils/estimate-tokens';
 import {
+  normalizeAnthropicUsage,
   normalizeGeminiUsage,
   normalizeOpenAIChatUsage,
   normalizeOpenAIResponsesUsage,
@@ -148,6 +149,15 @@ export class UsageInspector extends PassThrough {
       // Some providers emit `: cost {"request_cost_usd": ...}` as SSE comments
       if (reconstructed?.providerReportedCost) {
         applyProviderReportedCost(this.usageRecord, reconstructed.providerReportedCost);
+        if (reconstructed?.usage) {
+          const usageCostDetails = extractUsageCostDetails(reconstructed.usage);
+          if (usageCostDetails) {
+            logger.debug(
+              `[ProviderCost] Both SSE :cost and usage.cost_details present for ${this.usageRecord.requestId}; ` +
+                `SSE value ($${this.usageRecord.providerReportedCost}) takes priority over cost_details total ($${usageCostDetails.total_cost})`
+            );
+          }
+        }
       }
 
       // Override with provider-reported cost from usage.cost_details if available
@@ -318,15 +328,17 @@ export class UsageInspector extends PassThrough {
           };
         }
       case 'messages':
-        return reconstructed.usage
-          ? {
-              inputTokens: reconstructed.usage.input_tokens || 0,
-              outputTokens: reconstructed.usage.output_tokens || 0,
-              cachedTokens: reconstructed.usage.cache_read_input_tokens || 0,
-              cacheWriteTokens: reconstructed.usage.cache_creation_input_tokens || 0,
-              reasoningTokens: 0,
-            }
-          : null;
+        if (!reconstructed.usage) return null;
+        {
+          const usage = normalizeAnthropicUsage(reconstructed.usage);
+          return {
+            inputTokens: usage.input_tokens,
+            outputTokens: usage.output_tokens,
+            cachedTokens: usage.cached_tokens,
+            cacheWriteTokens: usage.cache_creation_tokens,
+            reasoningTokens: usage.reasoning_tokens,
+          };
+        }
       case 'gemini':
         if (!reconstructed.usageMetadata) return null;
         {

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

@@ -502,6 +502,15 @@ async function finalizeUsage(
   const reconstructed = debugManager.getReconstructedRawResponse(usageRecord.requestId!);
   if (reconstructed?.providerReportedCost) {
     applyProviderReportedCost(usageRecord, reconstructed.providerReportedCost);
+    if (reconstructed?.usage) {
+      const usageCostDetails = extractUsageCostDetails(reconstructed.usage);
+      if (usageCostDetails) {
+        logger.debug(
+          `[ProviderCost] Both SSE :cost and usage.cost_details present for ${usageRecord.requestId}; ` +
+            `SSE value ($${usageRecord.providerReportedCost}) takes priority over cost_details total ($${usageCostDetails.total_cost})`
+        );
+      }
+    }
   }
 
   // Also check for cost_details in the usage block (some providers embed costs there)