Skip to content

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.md
index 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 rather
than a specialized adapter. DeepSeek intentionally uses its
OpenAI-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 reasoning
history is serialized per assistant turn: non-tool reasoning is omitted from
its first replay, while tool-call reasoning is retained independently of the
next 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 when
providers 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 Provider
diff --git a/pyproject.toml b/pyproject.toml
index 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.py
index 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 None
else 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.py
index 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 Any
from ..usage import estimate_text_tokens
from .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 = None
self._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] = value
if 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 0
usage: 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.py
index 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_tokens
cache_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.py
index 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.asyncio
diff --git a/tests/core/openai_responses/test_provider_stream.py b/tests/core/openai_responses/test_provider_stream.py
index 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.py
index 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.asyncio
async 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.py
index 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_provid
usage = next(
event.data["usage"] for event in parsed if event.event == "message_delta"
)
+ assert "cache_creation_input_tokens" not in usage
assert 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.lock
index 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" },