fix(codec): accept scalar OpenRouter usage cost

crates/core/src/codec/openai_chat.rs

@@ -93,7 +93,14 @@ struct RawChatUsage {
     prompt_tokens_details: Option<RawPromptTokensDetails>,
     #[serde(rename = "cost_usd")]
     provider_cost: Option<f64>,
-    cost: Option<RawUsageCost>,
+    cost: Option<RawChatUsageCost>,
+}
+
+#[derive(Deserialize)]
+#[serde(untagged)]
+enum RawChatUsageCost {
+    Scalar(f64),
+    Detailed(RawUsageCost),
 }
 
 #[derive(Deserialize)]
@@ -1167,13 +1174,21 @@ impl LlmResponseCodec for OpenAIChatCodec {
         let model_for_pricing = raw.model.as_deref();
         let model_provider = infer_model_provider("openai", model_for_pricing);
         let usage = raw.usage.map(|u| {
+            let (scalar_provider_cost, detailed_cost) = match u.cost {
+                Some(RawChatUsageCost::Scalar(cost)) => (Some(cost), None),
+                Some(RawChatUsageCost::Detailed(cost)) => (None, Some(cost)),
+                None => (None, None),
+            };
             let mut usage = Usage {
                 prompt_tokens: u.prompt_tokens,
                 completion_tokens: u.completion_tokens,
                 total_tokens: u.total_tokens,
                 cache_read_tokens: u.prompt_tokens_details.and_then(|d| d.cached_tokens),
                 cache_write_tokens: None,
-                cost: provider_reported_cost(u.provider_cost, u.cost),
+                cost: provider_reported_cost(
+                    u.provider_cost.or(scalar_provider_cost),
+                    detailed_cost,
+                ),
             };
             if usage.cost.is_none() {
                 usage.cost = model_for_pricing.and_then(|model| {

crates/core/tests/unit/codec/openai_chat_tests.rs

@@ -175,6 +175,87 @@ fn test_decode_response_provider_reported_cost() {
     assert_eq!(cost.source, CostSource::ProviderReported);
 }
 
+#[test]
+fn test_decode_response_openrouter_scalar_provider_reported_cost() {
+    let codec = OpenAIChatCodec;
+    let response = json!({
+        "id": "gen-openrouter-cost",
+        "object": "chat.completion",
+        "model": "nvidia/nemotron-3-ultra-550b-a55b:free",
+        "provider": "Nvidia",
+        "choices": [{
+            "message": {"role": "assistant", "content": "ok"},
+            "finish_reason": "stop"
+        }],
+        "usage": {
+            "prompt_tokens": 10,
+            "completion_tokens": 5,
+            "total_tokens": 15,
+            "cost": 0,
+            "cost_details": {"upstream_inference_cost": 0}
+        }
+    });
+
+    let resp = codec.decode_response(&response).unwrap();
+    let cost = resp.usage.unwrap().cost.unwrap();
+
+    assert_eq!(cost.total, Some(0.0));
+    assert_eq!(cost.currency, "USD");
+    assert_eq!(cost.source, CostSource::ProviderReported);
+}
+
+#[test]
+fn test_decode_response_scalar_provider_reported_cost_honors_cost_usd_precedence() {
+    let codec = OpenAIChatCodec;
+    let scalar_response = json!({"usage": {"cost": 0.0123}});
+    let scalar_cost = codec
+        .decode_response(&scalar_response)
+        .unwrap()
+        .usage
+        .unwrap()
+        .cost
+        .unwrap();
+
+    assert_eq!(scalar_cost.total, Some(0.0123));
+    assert_eq!(scalar_cost.source, CostSource::ProviderReported);
+
+    let conflicting_response = json!({"usage": {"cost_usd": 0.0456, "cost": 0.0123}});
+    let conflicting_cost = codec
+        .decode_response(&conflicting_response)
+        .unwrap()
+        .usage
+        .unwrap()
+        .cost
+        .unwrap();
+
+    assert_eq!(conflicting_cost.total, Some(0.0456));
+    assert_eq!(conflicting_cost.source, CostSource::ProviderReported);
+
+    let conflicting_detailed_response = json!({
+        "usage": {
+            "cost_usd": 0.0456,
+            "cost": {
+                "total": 0.0123,
+                "input": 0.004,
+                "output": 0.0083
+            }
+        }
+    });
+    let conflicting_detailed_cost = codec
+        .decode_response(&conflicting_detailed_response)
+        .unwrap()
+        .usage
+        .unwrap()
+        .cost
+        .unwrap();
+
+    assert_eq!(conflicting_detailed_cost.total, Some(0.0456));
+    assert_eq!(
+        conflicting_detailed_cost.source,
+        CostSource::ProviderReported
+    );
+}
+
 #[test]
 fn test_decode_response_finish_reason_stop() {
     let codec = OpenAIChatCodec;

docs/integrate-into-frameworks/provider-response-codecs.mdx

@@ -368,6 +368,7 @@ Built-in codecs normalize provider field names as follows:
 | `total_tokens` | `total_tokens` | `total_tokens` | computed | `totalTokens` | `totalTokenCount` (or computed as prompt + candidates + thinking) |
 | `cache_read_tokens` | `prompt_tokens_details.cached_tokens` | `input_tokens_details.cached_tokens` | `cache_read_input_tokens` | `promptTokensDetails.cachedTokens` | `cachedContentTokenCount` |
 | `cache_write_tokens` | — | — | `cache_creation_input_tokens` | — | — |
+| `cost` | `cost_usd`, structured `cost`, or scalar `cost` (OpenRouter; USD provider-reported total) | `cost_usd` or structured `cost` | `cost_usd` or structured `cost` | — | — |
 
 Gemini `generateContent` thinking tokens (`thoughtsTokenCount`) are stored in `api_specific.thoughts_tokens` rather than `completion_tokens`, because Google bills them as output tokens but reports them separately. The cost estimate folds them into the effective output-token count so that the pricing table reflects the real billing cost.