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

Report output-limit truncation as incomplete Responses (#1180)

Ali Khokharac2ccbdd164c
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 6047a722..d3504b01 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -805,6 +805,11 @@ Post-start Responses failures are assembler-owned: the active
`ResponsesStreamAssembler` emits `response.failed` so the terminal event keeps
the same `response.id`, output ledger, and usage state as the earlier
`response.created`.
+Provider completion reasons remain canonical until that same assembler chooses
+the Responses terminal event. Anthropic `max_tokens` becomes
+`response.incomplete` with `incomplete_details.reason=max_output_tokens` while
+preserving partial output and usage; normal terminal reasons remain
+`response.completed`.
Responses custom tools are also boundary-owned. The adapter accepts native
Responses `custom` tool declarations, represents them internally as Anthropic
diff --git a/pyproject.toml b/pyproject.toml
index bd6c32fb..9ef30c7c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "4.8.6"
+version = "4.8.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/streaming/assembler.py b/src/free_claude_code/core/openai_responses/streaming/assembler.py
index 1511e3f7..1d26ac4c 100644
--- a/src/free_claude_code/core/openai_responses/streaming/assembler.py
+++ b/src/free_claude_code/core/openai_responses/streaming/assembler.py
@@ -42,6 +42,7 @@ class ResponsesStreamAssembler:
on_invalid_function_call=self._fail_invalid_function_call,
)
self._started = False
+ self._stop_reason: str | None = None
self._provisional_error: dict[str, Any] | None = None
self.terminal = False
self.final_response: dict[str, Any] | None = None
@@ -58,9 +59,9 @@ class ResponsesStreamAssembler:
elif event.event == "content_block_stop":
chunks.extend(self._handle_content_block_stop(event.data))
elif event.event == "message_delta":
- self._ledger.record_usage_delta(event.data)
+ self._record_message_delta(event.data)
elif event.event == "message_stop":
- chunks.extend(self.complete_response())
+ chunks.extend(self.finish_response())
elif event.event == "error":
chunks.extend(self.fail_response(event.data))
return chunks
@@ -69,11 +70,15 @@ class ResponsesStreamAssembler:
if self.terminal:
return []
chunks = self._ensure_started()
- chunks.extend(self.complete_response())
+ chunks.extend(self.finish_response())
return chunks
def response_payload(
- self, *, status: str, error: dict[str, Any] | None = None
+ self,
+ *,
+ status: str,
+ error: dict[str, Any] | None = None,
+ incomplete_details: dict[str, str] | None = None,
) -> dict[str, Any]:
return {
"id": self._response_id,
@@ -97,15 +102,19 @@ class ResponsesStreamAssembler:
"max_output_tokens": self._request.max_output_tokens,
"usage": self._ledger.usage(),
"error": error,
+ "incomplete_details": incomplete_details,
}
- def complete_response(self) -> list[str]:
+ def finish_response(self) -> list[str]:
chunks = self._flush_active_blocks()
if self.terminal:
return chunks
if self._provisional_error is not None:
chunks.extend(self._finish_failed_response(self._provisional_error))
return chunks
+ if self._stop_reason == "max_tokens":
+ chunks.extend(self._finish_incomplete_response())
+ return chunks
self.final_response = self.response_payload(status="completed")
chunks.append(events.response_completed(self.final_response))
self.terminal = True
@@ -133,6 +142,14 @@ class ResponsesStreamAssembler:
self.terminal = True
return [events.response_failed(self.final_response)]
+ def _finish_incomplete_response(self) -> list[str]:
+ self.final_response = self.response_payload(
+ status="incomplete",
+ incomplete_details={"reason": "max_output_tokens"},
+ )
+ self.terminal = True
+ return [events.response_incomplete(self.final_response)]
+
def _ensure_started(self) -> list[str]:
if self._started:
return []
@@ -221,6 +238,15 @@ class ResponsesStreamAssembler:
return []
return self._completer.complete_block(state)
+ def _record_message_delta(self, data: Mapping[str, Any]) -> None:
+ self._ledger.record_usage_delta(data)
+ delta = data.get("delta")
+ if not isinstance(delta, Mapping):
+ return
+ stop_reason = delta.get("stop_reason")
+ if isinstance(stop_reason, str):
+ self._stop_reason = stop_reason
+
def _start_text_block(self, index: int) -> tuple[list[str], TextBlockState | None]:
chunks = self._complete_existing_block(index)
if self.terminal:
diff --git a/src/free_claude_code/core/openai_responses/streaming/event_builders.py b/src/free_claude_code/core/openai_responses/streaming/event_builders.py
index bad91224..5eb8b40a 100644
--- a/src/free_claude_code/core/openai_responses/streaming/event_builders.py
+++ b/src/free_claude_code/core/openai_responses/streaming/event_builders.py
@@ -19,6 +19,13 @@ def response_completed(response: dict[str, Any]) -> str:
)
+def response_incomplete(response: dict[str, Any]) -> str:
+ return format_response_sse_event(
+ "response.incomplete",
+ {"type": "response.incomplete", "response": response},
+ )
+
+
def response_failed(response: dict[str, Any]) -> str:
return format_response_sse_event(
"response.failed",
diff --git a/tests/api/test_openai_responses.py b/tests/api/test_openai_responses.py
index 08e44830..4a428059 100644
--- a/tests/api/test_openai_responses.py
+++ b/tests/api/test_openai_responses.py
@@ -110,6 +110,34 @@ def test_create_response_stream_routes_through_provider(
assert provider.stream_kwargs[0]["request_id"] == response.headers["request-id"]
+def test_create_response_stream_preserves_output_limit_as_incomplete() -> None:
+ provider = FakeProvider(
+ _anthropic_text_stream("partial output", stop_reason="max_tokens")
+ )
+ app = create_test_app()
+ with (
+ patch("free_claude_code.api.routes.resolve_provider", return_value=provider),
+ TestClient(app) as client,
+ ):
+ response = client.post(
+ "/v1/responses",
+ json={
+ "model": "nvidia_nim/test-model",
+ "input": "Keep working",
+ "max_output_tokens": 32,
+ },
+ )
+
+ assert response.status_code == 200
+ events = parse_sse_text(response.text)
+ assert events[-1].event == "response.incomplete"
+ incomplete = events[-1].data["response"]
+ assert incomplete["id"] == events[0].data["response"]["id"]
+ assert incomplete["status"] == "incomplete"
+ assert incomplete["incomplete_details"] == {"reason": "max_output_tokens"}
+ assert incomplete["output"][0]["content"][0]["text"] == "partial output"
+
+
def test_create_response_preflight_rejection_stays_an_ordinary_http_error() -> None:
provider = FakeProvider(_anthropic_text_stream("unused"))
provider.preflight_stream.side_effect = InvalidRequestError("bad tool shape")
@@ -685,7 +713,7 @@ def test_create_response_unsupported_tool_returns_openai_error(
assert "Unsupported Responses tool type" in payload["error"]["message"]
-def _anthropic_text_stream(text: str) -> list[str]:
+def _anthropic_text_stream(text: str, *, stop_reason: str = "end_turn") -> list[str]:
return [
format_sse_event("message_start", {"type": "message_start", "message": {}}),
format_sse_event(
@@ -712,7 +740,7 @@ def _anthropic_text_stream(text: str) -> list[str]:
"message_delta",
{
"type": "message_delta",
- "delta": {"stop_reason": "end_turn", "stop_sequence": None},
+ "delta": {"stop_reason": stop_reason, "stop_sequence": None},
"usage": {"input_tokens": 3, "output_tokens": 4},
},
),
diff --git a/tests/core/openai_responses/test_sse.py b/tests/core/openai_responses/test_sse.py
index ededbfec..8023fcd0 100644
--- a/tests/core/openai_responses/test_sse.py
+++ b/tests/core/openai_responses/test_sse.py
@@ -186,6 +186,63 @@ async def test_anthropic_text_stream_converts_to_responses_sse() -> None:
assert completed["tool_choice"] == "auto"
+async def test_max_tokens_stop_reason_converts_to_response_incomplete() -> None:
+ text = await _collect_sse(
+ _responses_sse(
+ _aiter(_anthropic_text_stream("partial output", stop_reason="max_tokens")),
+ {"model": "nvidia_nim/test-model", "stream": True},
+ )
+ )
+
+ events = parse_sse_text(text)
+ assert events[-1].event == "response.incomplete"
+ assert "response.completed" not in [event.event for event in events]
+ incomplete = events[-1].data["response"]
+ assert incomplete["id"] == events[0].data["response"]["id"]
+ assert incomplete["status"] == "incomplete"
+ assert incomplete["incomplete_details"] == {"reason": "max_output_tokens"}
+ assert incomplete["error"] is None
+ assert incomplete["output"][0]["content"][0]["text"] == "partial output"
+ assert incomplete["usage"] == {
+ "input_tokens": 3,
+ "output_tokens": 4,
+ "total_tokens": 7,
+ }
+
+
+async def test_max_tokens_without_visible_output_is_still_incomplete() -> None:
+ text = await _collect_sse(
+ _responses_sse(
+ _aiter(
+ [
+ format_sse_event(
+ "message_start", {"type": "message_start", "message": {}}
+ ),
+ format_sse_event(
+ "message_delta",
+ {
+ "type": "message_delta",
+ "delta": {"stop_reason": "max_tokens"},
+ "usage": {"input_tokens": 3, "output_tokens": 64},
+ },
+ ),
+ format_sse_event("message_stop", {"type": "message_stop"}),
+ ]
+ ),
+ {"model": "nvidia_nim/test-model", "stream": True},
+ )
+ )
+
+ incomplete = parse_sse_text(text)[-1]
+ assert incomplete.event == "response.incomplete"
+ assert incomplete.data["response"]["output"] == []
+ assert incomplete.data["response"]["incomplete_details"] == {
+ "reason": "max_output_tokens"
+ }
+
+
@pytest.mark.asyncio
async def test_response_payload_preserves_explicit_request_options() -> None:
response = await _completed_response_from_sse(
@@ -710,7 +767,7 @@ async def _aiter_then_raise(
raise failure
-def _anthropic_text_stream(text: str) -> list[str]:
+def _anthropic_text_stream(text: str, *, stop_reason: str = "end_turn") -> list[str]:
return [
format_sse_event("message_start", {"type": "message_start", "message": {}}),
format_sse_event(
@@ -737,7 +794,7 @@ def _anthropic_text_stream(text: str) -> list[str]:
"message_delta",
{
"type": "message_delta",
- "delta": {"stop_reason": "end_turn", "stop_sequence": None},
+ "delta": {"stop_reason": stop_reason, "stop_sequence": None},
"usage": {"input_tokens": 3, "output_tokens": 4},
},
),
diff --git a/uv.lock b/uv.lock
index 6d49a2b0..11bee666 100644
--- a/uv.lock
+++ b/uv.lock
@@ -570,7 +570,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "4.8.6"
+version = "4.8.7"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },