Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)
Python
Fix cache usage accounting across protocol boundaries (#1372)
Ali Khokhar2df1ea5f39f6
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.mdindex 836bdb5b..060be0ef 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -725,8 +725,8 @@ same OpenAI-compatible Chat Completions provider family;Ollama's standard `reasoning` delta and history field are profile data ratherthan a specialized adapter. DeepSeek intentionally uses itsOpenAI-compatible Chat Completions endpoint because that is the endpoint that-reports prompt-cache hit/miss counters; the provider maps those counters back-into Anthropic usage fields for Claude-compatible clients. DeepSeek reasoning+reports prompt-cache hit/miss counters; the provider translates those native+counters into Anthropic usage semantics. DeepSeek reasoninghistory is serialized per assistant turn: non-tool reasoning is omitted fromits first replay, while tool-call reasoning is retained independently of thenext generation's thinking mode. Append-only conversations therefore keep an@@ -829,7 +829,12 @@ streamed usage handling: it requests`stream_options.include_usage`, consumes provider `prompt_tokens` and`completion_tokens` when present, and falls back to local estimates whenproviders omit or reject optional usage metadata. Provider modules only own true-usage quirks such as DeepSeek prompt-cache counters.+usage quirks: DeepSeek validates a complete hit/miss partition, maps misses to+ordinary input and hits to cache reads, and never reports a miss as an+Anthropic cache creation. The native Responses-to-Anthropic adapter likewise+partitions a valid cached-token detail from the upstream total. At the reverse+protocol boundary, the Anthropic-to-Responses adapter recombines those+disjoint input categories into its single `input_tokens` total.### Adding A Providerdiff --git a/pyproject.toml b/pyproject.tomlindex c7d341b3..5e1b1528 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "free-claude-code"-version = "4.17.6"+version = "4.17.7"description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"readme = "README.md"requires-python = ">=3.14.0"diff --git a/src/free_claude_code/core/openai_responses/provider_stream.py b/src/free_claude_code/core/openai_responses/provider_stream.pyindex ae5cce43..960c5411 100644--- a/src/free_claude_code/core/openai_responses/provider_stream.py+++ b/src/free_claude_code/core/openai_responses/provider_stream.py@@ -208,6 +208,15 @@ class ResponsesProviderStream:details = usage.get("input_tokens_details")details = details if isinstance(details, dict) else {}cached_tokens = _integer(details.get("cached_tokens"))+ usage_fields = None+ if (+ input_tokens is not None+ and input_tokens >= 0+ and cached_tokens is not None+ and 0 <= cached_tokens <= input_tokens+ ):+ input_tokens -= cached_tokens+ usage_fields = {"cache_read_input_tokens": cached_tokens}stop_reason = "max_tokens" if incomplete else "end_turn"events.append(self.ledger.message_delta(@@ -216,11 +225,7 @@ class ResponsesProviderStream:if output_tokens is not Noneelse self.ledger.estimate_output_tokens(),input_tokens=input_tokens,- usage_fields=(- {"cache_read_input_tokens": cached_tokens}- if cached_tokens is not None- else None- ),+ usage_fields=usage_fields,))events.append(self.ledger.message_stop())diff --git a/src/free_claude_code/core/openai_responses/streaming/ledger.py b/src/free_claude_code/core/openai_responses/streaming/ledger.pyindex 8791bd84..b312f172 100644--- a/src/free_claude_code/core/openai_responses/streaming/ledger.py+++ b/src/free_claude_code/core/openai_responses/streaming/ledger.py@@ -6,6 +6,12 @@ from typing import Anyfrom ..usage import estimate_text_tokensfrom .blocks import BlockState+_ANTHROPIC_INPUT_TOKEN_FIELDS = (+ "input_tokens",+ "cache_creation_input_tokens",+ "cache_read_input_tokens",+)+class ResponsesOutputLedger:"""Track active blocks, reserved output slots, and accumulated usage."""@@ -14,7 +20,7 @@ class ResponsesOutputLedger:self._output_slots: list[dict[str, Any] | None] = []self._active_blocks: dict[int, BlockState] = {}self._fallback_text_index = -1- self._input_tokens: int | None = None+ self._input_token_counts: dict[str, int] = {}self._output_tokens: int | None = Noneself._reasoning_tokens_estimate = 0@@ -51,8 +57,10 @@ class ResponsesOutputLedger:usage = data.get("usage")if not isinstance(usage, dict):return- if isinstance(usage.get("input_tokens"), int):- self._input_tokens = usage["input_tokens"]+ for field in _ANTHROPIC_INPUT_TOKEN_FIELDS:+ value = usage.get(field)+ if isinstance(value, int) and not isinstance(value, bool) and value >= 0:+ self._input_token_counts[field] = valueif isinstance(usage.get("output_tokens"), int):self._output_tokens = usage["output_tokens"]@@ -60,9 +68,9 @@ class ResponsesOutputLedger:self._reasoning_tokens_estimate += estimate_text_tokens(text)def usage(self) -> dict[str, Any] | None:- if self._input_tokens is None and self._output_tokens is None:+ if not self._input_token_counts and self._output_tokens is None:return None- input_tokens = self._input_tokens or 0+ input_tokens = sum(self._input_token_counts.values())output_tokens = self._output_tokens or 0usage: dict[str, Any] = {"input_tokens": input_tokens,diff --git a/src/free_claude_code/providers/deepseek/client.py b/src/free_claude_code/providers/deepseek/client.pyindex 2dec3ca9..7f264fa1 100644--- a/src/free_claude_code/providers/deepseek/client.py+++ b/src/free_claude_code/providers/deepseek/client.py@@ -45,11 +45,25 @@ class DeepSeekProvider(OpenAIChatProvider):)def _anthropic_usage_fields(self, usage_info: Any) -> dict[str, int]:- usage_fields: dict[str, int] = {}cache_hit_tokens = usage_int(usage_info, "prompt_cache_hit_tokens")- if cache_hit_tokens is not None:- usage_fields["cache_read_input_tokens"] = cache_hit_tokenscache_miss_tokens = usage_int(usage_info, "prompt_cache_miss_tokens")- if cache_miss_tokens is not None:- usage_fields["cache_creation_input_tokens"] = cache_miss_tokens- return usage_fields+ if (+ cache_hit_tokens is None+ or cache_hit_tokens < 0+ or cache_miss_tokens is None+ or cache_miss_tokens < 0+ ):+ return {}++ prompt_tokens = usage_int(usage_info, "prompt_tokens")+ if (+ prompt_tokens is not None+ and prompt_tokens >= 0+ and prompt_tokens != cache_hit_tokens + cache_miss_tokens+ ):+ return {}++ return {+ "input_tokens": cache_miss_tokens,+ "cache_read_input_tokens": cache_hit_tokens,+ }diff --git a/tests/api/test_api_handlers.py b/tests/api/test_api_handlers.pyindex ee299efc..456eebbc 100644--- a/tests/api/test_api_handlers.py+++ b/tests/api/test_api_handlers.py@@ -195,7 +195,11 @@ async def test_messages_handler_aggregates_provider_stream_when_stream_false() -{"type": "message_delta","delta": {"stop_reason": "end_turn", "stop_sequence": None},- "usage": {"input_tokens": 7, "output_tokens": 2},+ "usage": {+ "input_tokens": 20,+ "output_tokens": 2,+ "cache_read_input_tokens": 10,+ },},),format_sse_event("message_stop", {"type": "message_stop"}),@@ -220,7 +224,11 @@ async def test_messages_handler_aggregates_provider_stream_when_stream_false() -assert body["model"] == "test-model"assert body["content"] == [{"type": "text", "text": "OK"}]assert body["stop_reason"] == "end_turn"- assert body["usage"] == {"input_tokens": 7, "output_tokens": 2}+ assert body["usage"] == {+ "input_tokens": 20,+ "output_tokens": 2,+ "cache_read_input_tokens": 10,+ }@pytest.mark.asynciodiff --git a/tests/core/openai_responses/test_provider_stream.py b/tests/core/openai_responses/test_provider_stream.pyindex 21c5ae05..53a2b12f 100644--- a/tests/core/openai_responses/test_provider_stream.py+++ b/tests/core/openai_responses/test_provider_stream.py@@ -125,12 +125,58 @@ def test_responses_provider_stream_preserves_reasoning_tools_usage_and_ids() ->assert argument_deltas == ['{"q":', '"x"}']message_delta = next(event for event in events if event.event == "message_delta")assert message_delta.data["usage"] == {- "input_tokens": 20,+ "input_tokens": 5,"output_tokens": 8,"cache_read_input_tokens": 15,}+ ("input_tokens", "cached_tokens", "expected_input_tokens"),+ [+ (20, -1, 20),+ (20, 21, 20),+ (20, True, 20),+ (None, 5, 12),+ ],+)+def test_responses_provider_stream_ignores_invalid_cache_partitions(+ input_tokens: int | None,+ cached_tokens: int | bool,+ expected_input_tokens: int,+) -> None:+ stream = ResponsesProviderStream(+ message_id="msg_test",+ model="openai/gpt-test",+ input_tokens=12,+ )+ output = stream.start()+ output.extend(+ stream.feed(+ "response.completed",+ {+ "response": {+ "usage": {+ "input_tokens": input_tokens,+ "output_tokens": 8,+ "input_tokens_details": {"cached_tokens": cached_tokens},+ }+ }+ },+ )+ )++ message_delta = next(+ event+ for event in parse_sse_text("".join(output))+ if event.event == "message_delta"+ )+ assert message_delta.data["usage"] == {+ "input_tokens": expected_input_tokens,+ "output_tokens": 8,+ }++def test_responses_provider_stream_surfaces_failed_event() -> None:stream = ResponsesProviderStream(message_id="msg_test",diff --git a/tests/core/openai_responses/test_sse.py b/tests/core/openai_responses/test_sse.pyindex 8023fcd0..0459f57f 100644--- a/tests/core/openai_responses/test_sse.py+++ b/tests/core/openai_responses/test_sse.py@@ -551,7 +551,7 @@ async def test_anthropic_error_stream_converts_to_response_failed_event() -> Non@pytest.mark.asyncio-async def test_split_usage_deltas_are_accumulated() -> None:+async def test_split_usage_deltas_sum_latest_anthropic_input_categories() -> None:response = await _completed_response_from_sse(_aiter([@@ -561,7 +561,11 @@ async def test_split_usage_deltas_are_accumulated() -> None:{"type": "message_delta","delta": {"stop_reason": "end_turn"},- "usage": {"input_tokens": 11},+ "usage": {+ "input_tokens": 20,+ "cache_creation_input_tokens": 5,+ "cache_read_input_tokens": 10,+ },},),format_sse_event(@@ -569,7 +573,10 @@ async def test_split_usage_deltas_are_accumulated() -> None:{"type": "message_delta","delta": {},- "usage": {"output_tokens": 7},+ "usage": {+ "cache_read_input_tokens": 11,+ "output_tokens": 7,+ },},),format_sse_event("message_stop", {"type": "message_stop"}),@@ -579,13 +586,57 @@ async def test_split_usage_deltas_are_accumulated() -> None:)assert response["usage"] == {- "input_tokens": 11,+ "input_tokens": 36,"output_tokens": 7,- "total_tokens": 18,+ "total_tokens": 43,}assert "stop_reason" not in response+async def test_usage_ignores_invalid_anthropic_input_categories() -> None:+ response = await _completed_response_from_sse(+ _aiter(+ [+ *_anthropic_text_stream("usage")[:-2],+ format_sse_event(+ "message_delta",+ {+ "type": "message_delta",+ "delta": {"stop_reason": "end_turn"},+ "usage": {+ "input_tokens": 20,+ "cache_creation_input_tokens": 5,+ "cache_read_input_tokens": 10,+ },+ },+ ),+ format_sse_event(+ "message_delta",+ {+ "type": "message_delta",+ "delta": {},+ "usage": {+ "input_tokens": -1,+ "cache_creation_input_tokens": -2,+ "cache_read_input_tokens": True,+ "output_tokens": 7,+ },+ },+ ),+ format_sse_event("message_stop", {"type": "message_stop"}),+ ]+ ),+ {"model": "nvidia_nim/test-model", "stream": True},+ )++ assert response["usage"] == {+ "input_tokens": 35,+ "output_tokens": 7,+ "total_tokens": 42,+ }++@pytest.mark.asyncioasync def test_reasoning_stream_reports_reasoning_usage_detail() -> None:response = await _completed_response_from_sse(diff --git a/tests/providers/test_deepseek.py b/tests/providers/test_deepseek.pyindex f818ddb5..68165a72 100644--- a/tests/providers/test_deepseek.py+++ b/tests/providers/test_deepseek.py@@ -56,6 +56,93 @@ def test_init(deepseek_config):assert mock_client.called+ ("usage", "expected"),+ [+ (+ {+ "prompt_tokens": 30,+ "prompt_cache_hit_tokens": 10,+ "prompt_cache_miss_tokens": 20,+ },+ {"input_tokens": 20, "cache_read_input_tokens": 10},+ ),+ (+ {+ "prompt_tokens": 30,+ "prompt_cache_hit_tokens": 0,+ "prompt_cache_miss_tokens": 30,+ },+ {"input_tokens": 30, "cache_read_input_tokens": 0},+ ),+ (+ {+ "prompt_tokens": 30,+ "prompt_cache_hit_tokens": 30,+ "prompt_cache_miss_tokens": 0,+ },+ {"input_tokens": 0, "cache_read_input_tokens": 30},+ ),+ (+ {"prompt_cache_hit_tokens": 10, "prompt_cache_miss_tokens": 20},+ {"input_tokens": 20, "cache_read_input_tokens": 10},+ ),+ (+ {"prompt_tokens": 30, "prompt_cache_miss_tokens": 20},+ {},+ ),+ (+ {"prompt_tokens": 30, "prompt_cache_hit_tokens": 10},+ {},+ ),+ (+ {+ "prompt_tokens": 30,+ "prompt_cache_hit_tokens": True,+ "prompt_cache_miss_tokens": 20,+ },+ {},+ ),+ (+ {+ "prompt_tokens": 30,+ "prompt_cache_hit_tokens": 10,+ "prompt_cache_miss_tokens": 20.0,+ },+ {},+ ),+ (+ {+ "prompt_tokens": 30,+ "prompt_cache_hit_tokens": -1,+ "prompt_cache_miss_tokens": 31,+ },+ {},+ ),+ (+ {+ "prompt_tokens": 30,+ "prompt_cache_hit_tokens": 10,+ "prompt_cache_miss_tokens": -1,+ },+ {},+ ),+ (+ {+ "prompt_tokens": 30,+ "prompt_cache_hit_tokens": 10,+ "prompt_cache_miss_tokens": 19,+ },+ {},+ ),+ ],+)+def test_maps_only_complete_consistent_cache_usage(+ deepseek_provider, usage, expected+) -> None:+ assert deepseek_provider._anthropic_usage_fields(usage) == expected++def test_build_request_body_openai_chat_shape(deepseek_provider):request = MessagesRequest(model="deepseek-v4-pro",@@ -908,11 +995,11 @@ async def test_stream_uses_chat_completions_and_maps_cache_usage(deepseek_providusage = next(event.data["usage"] for event in parsed if event.event == "message_delta")+ assert "cache_creation_input_tokens" not in usageassert usage == {- "input_tokens": 30,+ "input_tokens": 20,"output_tokens": 3,"cache_read_input_tokens": 10,- "cache_creation_input_tokens": 20,}diff --git a/uv.lock b/uv.lockindex a15de6fc..d95402d5 100644--- a/uv.lock+++ b/uv.lock@@ -620,7 +620,7 @@ wheels = [[[package]]name = "free-claude-code"-version = "4.17.6"+version = "4.17.7"source = { editable = "." }dependencies = [{ name = "aiohttp" },