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

Add Responses reasoning usage details (#860)

Ali Khokharb3ac9c2e5e25
diff --git a/core/openai_responses/stream_state.py b/core/openai_responses/stream_state.py
index 10c1c9c0..4a58c3cd 100644
--- a/core/openai_responses/stream_state.py
+++ b/core/openai_responses/stream_state.py
@@ -26,6 +26,7 @@ from .tools import (
custom_tool_input_text_from_arguments,
responses_tool_identity_from_anthropic_name,
)
+from .usage import estimate_text_tokens
@dataclass(slots=True)
@@ -72,6 +73,7 @@ class ResponsesStreamAssembler:
self._fallback_text_index = -1
self._input_tokens: int | None = None
self._output_tokens: int | None = None
+ self._reasoning_tokens_estimate = 0
self._started = False
self.terminal = False
self.final_response: dict[str, Any] | None = None
@@ -434,6 +436,7 @@ class ResponsesStreamAssembler:
chunks: list[str] = []
text = "".join(state.text_parts)
if text:
+ self._reasoning_tokens_estimate += estimate_text_tokens(text)
chunks.append(
format_response_sse_event(
"response.reasoning_text.done",
@@ -595,16 +598,22 @@ class ResponsesStreamAssembler:
def _output(self) -> list[dict[str, Any]]:
return [item for item in self._output_slots if item is not None]
- def _usage(self) -> dict[str, int] | None:
+ def _usage(self) -> dict[str, Any] | None:
if self._input_tokens is None and self._output_tokens is None:
return None
input_tokens = self._input_tokens or 0
output_tokens = self._output_tokens or 0
- return {
+ usage: dict[str, Any] = {
"input_tokens": input_tokens,
"output_tokens": output_tokens,
"total_tokens": input_tokens + output_tokens,
}
+ capped_reasoning_tokens = min(self._reasoning_tokens_estimate, output_tokens)
+ if capped_reasoning_tokens:
+ usage["output_tokens_details"] = {
+ "reasoning_tokens": capped_reasoning_tokens
+ }
+ return usage
def _safe_index(self, index: int | None) -> int:
if index is not None:
diff --git a/core/openai_responses/usage.py b/core/openai_responses/usage.py
new file mode 100644
index 00000000..232bcb34
--- /dev/null
+++ b/core/openai_responses/usage.py
@@ -0,0 +1,37 @@
+"""Usage helpers for OpenAI Responses payloads."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+_DISALLOWED_SPECIAL: tuple[str, ...] = ()
+
+
+class _TokenEncoder(Protocol):
+ def encode(
+ self, text: str, *, disallowed_special: tuple[str, ...]
+ ) -> list[int]: ...
+
+
+def _load_encoder() -> _TokenEncoder | None:
+ try:
+ import tiktoken
+ except ImportError:
+ return None
+
+ try:
+ return tiktoken.get_encoding("cl100k_base")
+ except ValueError:
+ return None
+
+
+_ENCODER = _load_encoder()
+
+
+def estimate_text_tokens(text: str) -> int:
+ """Return a best-effort token estimate for Responses usage details."""
+ if not text:
+ return 0
+ if _ENCODER is not None:
+ return len(_ENCODER.encode(text, disallowed_special=_DISALLOWED_SPECIAL))
+ return max(1, len(text) // 4)
diff --git a/pyproject.toml b/pyproject.toml
index c039880e..0e6e49b5 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "2.3.8"
+version = "2.3.9"
description = "Middleware between Claude Code CLI (Anthropic API) and NVIDIA NIM"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/tests/core/openai_responses/test_sse.py b/tests/core/openai_responses/test_sse.py
index dc3f0957..f3c265be 100644
--- a/tests/core/openai_responses/test_sse.py
+++ b/tests/core/openai_responses/test_sse.py
@@ -192,6 +192,69 @@ async def test_split_usage_deltas_are_accumulated() -> None:
assert "stop_reason" not in response
+async def test_reasoning_stream_reports_reasoning_usage_detail() -> None:
+ response = await _completed_response_from_sse(
+ _aiter(_anthropic_reasoning_stream("inspect the code before answering")),
+ {"model": "nvidia_nim/test-model", "stream": True},
+ )
+
+ usage = response["usage"]
+ assert usage["input_tokens"] == 3
+ assert usage["output_tokens"] == 20
+ assert usage["total_tokens"] == 23
+ assert usage["output_tokens_details"]["reasoning_tokens"] > 0
+
+
+async def test_reasoning_usage_detail_is_capped_at_output_tokens() -> None:
+ response = await _completed_response_from_sse(
+ _aiter(
+ _anthropic_reasoning_stream(
+ "this reasoning text is intentionally long enough to exceed one token",
+ output_tokens=1,
+ )
+ ),
+ {"model": "nvidia_nim/test-model", "stream": True},
+ )
+
+ assert response["usage"]["output_tokens"] == 1
+ assert response["usage"]["output_tokens_details"]["reasoning_tokens"] == 1
+
+
+async def test_reasoning_usage_detail_omits_zero_capped_count() -> None:
+ response = await _completed_response_from_sse(
+ _aiter(
+ _anthropic_reasoning_stream(
+ "reasoning text exists without reported output tokens",
+ output_tokens=None,
+ )
+ ),
+ {"model": "nvidia_nim/test-model", "stream": True},
+ )
+
+ assert response["usage"] == {
+ "input_tokens": 3,
+ "output_tokens": 0,
+ "total_tokens": 3,
+ }
+
+
+async def test_text_only_usage_omits_reasoning_usage_detail() -> None:
+ response = await _completed_response_from_sse(
+ _aiter(_anthropic_text_stream("plain text only")),
+ {"model": "nvidia_nim/test-model", "stream": True},
+ )
+
+ assert response["usage"] == {
+ "input_tokens": 3,
+ "output_tokens": 4,
+ "total_tokens": 7,
+ }
+
+
@pytest.mark.parametrize(
("request_payload", "tool_name", "partial_json", "expected_type", "expected_field"),
[
@@ -393,6 +456,49 @@ def _anthropic_tool_stream(
return chunks
+def _anthropic_reasoning_stream(
+ reasoning: str,
+ *,
+ output_tokens: int | None = 20,
+) -> list[str]:
+ usage = {"input_tokens": 3}
+ if output_tokens is not None:
+ usage["output_tokens"] = output_tokens
+
+ return [
+ format_sse_event("message_start", {"type": "message_start", "message": {}}),
+ format_sse_event(
+ "content_block_start",
+ {
+ "type": "content_block_start",
+ "index": 0,
+ "content_block": {"type": "thinking", "thinking": ""},
+ },
+ ),
+ format_sse_event(
+ "content_block_delta",
+ {
+ "type": "content_block_delta",
+ "index": 0,
+ "delta": {"type": "thinking_delta", "thinking": reasoning},
+ },
+ ),
+ format_sse_event(
+ "content_block_stop",
+ {"type": "content_block_stop", "index": 0},
+ ),
+ format_sse_event(
+ "message_delta",
+ {
+ "type": "message_delta",
+ "delta": {"stop_reason": "end_turn", "stop_sequence": None},
+ "usage": usage,
+ },
+ ),
+ format_sse_event("message_stop", {"type": "message_stop"}),
+ ]
+
+
def _overlapping_text_tool_stream() -> list[str]:
return [
format_sse_event("message_start", {"type": "message_start", "message": {}}),
diff --git a/uv.lock b/uv.lock
index cfa2734d..e23714f5 100644
--- a/uv.lock
+++ b/uv.lock
@@ -561,7 +561,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "2.3.8"
+version = "2.3.9"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },