refactor(providers): define typed usage contract

tests/providers/test_bedrock_provider.py

@@ -229,8 +229,11 @@ def test_parse_response_maps_text_tools_reasoning_usage_and_stop_reason() -> Non
 
     assert result.content == "hello"
     assert result.finish_reason == "tool_calls"
-    assert result.usage["prompt_tokens"] == 10
-    assert result.usage["cached_tokens"] == 2
+    assert result.usage is not None
+    assert result.usage.input_tokens == 12
+    assert result.usage.output_tokens == 5
+    assert result.usage.cache_read_tokens == 2
+    assert result.usage.cache_write_tokens is None
     assert result.reasoning_content == "think"
     assert result.thinking_blocks == [{"type": "thinking", "thinking": "think", "signature": "sig"}]
     assert result.tool_calls[0].id == "t1"
@@ -276,7 +279,10 @@ async def test_chat_stream_aggregates_text_tool_use_and_usage() -> None:
     assert deltas == ["he", "llo"]
     assert result.content == "hello"
     assert result.finish_reason == "tool_calls"
-    assert result.usage == {"prompt_tokens": 3, "completion_tokens": 4, "total_tokens": 7}
+    assert result.usage is not None
+    assert result.usage.input_tokens == 3
+    assert result.usage.output_tokens == 4
+    assert result.usage.total_tokens == 7
     assert result.tool_calls[0].name == "search"
     assert result.tool_calls[0].arguments == {"q": "x"}
 
@@ -285,6 +291,48 @@ async def _append_delta(deltas: list[str], text: str) -> None:
     deltas.append(text)
 
 
+@pytest.mark.parametrize(
+    ("wire_usage", "expected_read", "expected_write", "expected_input"),
+    [
+        ({"inputTokens": 5, "outputTokens": 1}, None, None, 5),
+        (
+            {
+                "inputTokens": 5,
+                "outputTokens": 1,
+                "cacheReadInputTokens": 0,
+                "cacheWriteInputTokens": 0,
+            },
+            0,
+            0,
+            5,
+        ),
+        (
+            {
+                "inputTokens": 5,
+                "outputTokens": 1,
+                "cacheReadInputTokens": 7,
+                "cacheWriteInputTokens": 3,
+            },
+            7,
+            3,
+            15,
+        ),
+    ],
+)
+def test_bedrock_usage_preserves_cache_reporting_and_logical_input(
+    wire_usage: dict[str, int],
+    expected_read: int | None,
+    expected_write: int | None,
+    expected_input: int,
+) -> None:
+    usage = BedrockProvider._usage(wire_usage)
+
+    assert usage is not None
+    assert usage.cache_read_tokens == expected_read
+    assert usage.cache_write_tokens == expected_write
+    assert usage.input_tokens == expected_input
+
+
 @pytest.mark.asyncio
 async def test_chat_error_maps_retry_metadata() -> None:
     provider = BedrockProvider(region="us-east-1", client=FakeClient(error=FakeBedrockError()))