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

Recover context-window exhaustion across providers and Chat (#1661)

Ali Khokhare6f2633b6969
diff --git a/pyproject.toml b/pyproject.toml
index 47bc2fba..beed6137 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "5.19.2"
+version = "5.19.3"
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/application/chat/service.py b/src/free_claude_code/application/chat/service.py
index 867433b1..82a3b04e 100644
--- a/src/free_claude_code/application/chat/service.py
+++ b/src/free_claude_code/application/chat/service.py
@@ -659,7 +659,14 @@ class ChatService:
"revision": transcript.session.revision + 1,
},
)
- await self._execute_generation(active, prepared=prepared, lease=lease)
+ await self._execute_generation_with_context_recovery(
+ active,
+ prepared=prepared,
+ builder=builder,
+ lease=lease,
+ prompt=prompt,
+ excluded_generation_id=generation_id,
+ )
finally:
await lease.release()
@@ -727,7 +734,14 @@ class ChatService:
"revision": transcript.session.revision + 1,
},
)
- await self._execute_generation(active, prepared=prepared, lease=lease)
+ await self._execute_generation_with_context_recovery(
+ active,
+ prepared=prepared,
+ builder=builder,
+ lease=lease,
+ prompt=prompt,
+ excluded_generation_id=generation_id,
+ )
finally:
await lease.release()
@@ -798,7 +812,14 @@ class ChatService:
"regeneration": True,
},
)
- await self._execute_generation(active, prepared=prepared, lease=lease)
+ await self._execute_generation_with_context_recovery(
+ active,
+ prepared=prepared,
+ builder=builder,
+ lease=lease,
+ prompt=prompt,
+ excluded_generation_id=latest.generation.id,
+ )
finally:
await lease.release()
@@ -836,6 +857,7 @@ class ChatService:
*,
prepared: PreparedChatRequest,
lease: RequestRuntimeLease,
+ candidate_failures: list[FailureKind] | None = None,
) -> None:
generation_id = active.generation_id
if generation_id is None:
@@ -853,11 +875,16 @@ class ChatService:
generation_id, target_model.provider_model_ref
)
+ def failed(failure: ExecutionFailure) -> None:
+ if candidate_failures is not None:
+ candidate_failures.append(failure.kind)
+
stream = executor.stream_messages(
prepared.routed,
raw_log_payload=prepared.routed.request.model_dump(mode="json"),
request_id=active.operation_id,
candidate_selected=selected,
+ candidate_failed=failed if candidate_failures is not None else None,
)
decoder = AnthropicSSEDecoder()
block_segments: dict[int, int] = {}
@@ -947,6 +974,59 @@ class ChatService:
publish_summary=True,
)
+ async def _execute_generation_with_context_recovery(
+ self,
+ active: _ActiveOperation,
+ *,
+ prepared: PreparedChatRequest,
+ builder: ChatContextBuilder,
+ lease: RequestRuntimeLease,
+ prompt: str,
+ excluded_generation_id: str,
+ ) -> None:
+ candidate_failures: list[FailureKind] = []
+ try:
+ await self._execute_generation(
+ active,
+ prepared=prepared,
+ lease=lease,
+ candidate_failures=candidate_failures,
+ )
+ return
+ except ExecutionFailure as exc:
+ if (
+ exc.kind is not FailureKind.CONTEXT_WINDOW_EXCEEDED
+ or active.segments
+ or not candidate_failures
+ or any(
+ kind is not FailureKind.CONTEXT_WINDOW_EXCEEDED
+ for kind in candidate_failures
+ )
+ ):
+ raise
+ context_failure = exc
+
+ transcript = await self._store.get_transcript(active.session_id)
+ if not builder.can_compact(transcript):
+ raise context_failure
+ await self._compact_transcript(
+ active,
+ builder=builder,
+ lease=lease,
+ transcript=transcript,
+ prompt=prompt,
+ pending_draft=None,
+ excluded_generation_id=excluded_generation_id,
+ )
+ transcript = await self._store.get_transcript(active.session_id)
+ prepared = builder.prepare(
+ transcript,
+ system_prompt=prompt,
+ exclude_generation_id=excluded_generation_id,
+ )
+ _require_request_fits(prepared.estimate)
+ await self._execute_generation(active, prepared=prepared, lease=lease)
+
async def _handle_sse_event(
self,
active: _ActiveOperation,
@@ -1221,15 +1301,28 @@ class ChatService:
take = candidate_count
if take == 0:
take = 1
- source = builder.compaction_source(summary, tuple(pending[:take]))
- summary, actual_model = await self._execute_summary(
- active,
- builder=builder,
- lease=lease,
- model_ref=model_ref,
- source=source,
- output_tokens=output_tokens,
- )
+ while True:
+ source = builder.compaction_source(summary, tuple(pending[:take]))
+ try:
+ summary, actual_model = await self._execute_summary(
+ active,
+ builder=builder,
+ lease=lease,
+ model_ref=model_ref,
+ source=source,
+ output_tokens=output_tokens,
+ )
+ break
+ except ExecutionFailure as exc:
+ if exc.kind is not FailureKind.CONTEXT_WINDOW_EXCEEDED:
+ raise
+ if take == 1:
+ raise ChatValidationError(
+ "The newest exchange cannot fit this model. Shorten the "
+ "system prompt, lower thinking, or choose a larger-context "
+ "model."
+ ) from exc
+ take = max(1, take // 2)
del pending[:take]
if summary is None:
raise ChatValidationError("Compaction produced no summary.")
diff --git a/src/free_claude_code/application/execution.py b/src/free_claude_code/application/execution.py
index f1fc457f..f48314bd 100644
--- a/src/free_claude_code/application/execution.py
+++ b/src/free_claude_code/application/execution.py
@@ -44,6 +44,7 @@ ResponsesTokenCounter = Callable[[OpenAIResponsesRequest], int]
WireApi = Literal["messages", "responses"]
CandidateStreamOpener = Callable[[int, ProviderModelTarget], AsyncIterator[str]]
CandidateSelected = Callable[[ProviderModelTarget], Awaitable[None] | None]
+CandidateFailed = Callable[[ExecutionFailure], None]
class ProviderExecutor:
@@ -163,16 +164,21 @@ class ProviderExecutor:
raw_log_payload: object,
request_id: str,
candidate_selected: CandidateSelected | None = None,
+ candidate_failed: CandidateFailed | None = None,
) -> AsyncIterator[str]:
"""Preflight and execute one Anthropic Messages request."""
primary = routed.resolved.primary
primary_provider = self._provider_resolver(primary.provider_id)
primary_request = routed.request.model_copy(deep=True)
- primary_provider.preflight_messages(
- primary_request,
- reasoning=routed.reasoning,
- )
+ primary_failure: ExecutionFailure | None = None
+ try:
+ primary_provider.preflight_messages(
+ primary_request,
+ reasoning=routed.reasoning,
+ )
+ except ExecutionFailure as failure:
+ primary_failure = failure
input_tokens = self._token_counter(
routed.request.messages,
routed.request.system,
@@ -196,6 +202,8 @@ class ProviderExecutor:
deep=True,
)
)
+ if index == 0 and primary_failure is not None:
+ raise primary_failure
if index > 0:
provider.preflight_messages(request, reasoning=routed.reasoning)
return provider.stream_messages(
@@ -218,6 +226,7 @@ class ProviderExecutor:
request_id=request_id,
open_candidate=open_candidate,
candidate_selected=candidate_selected,
+ candidate_failed=candidate_failed,
)
def stream_responses(
@@ -232,10 +241,14 @@ class ProviderExecutor:
primary = routed.resolved.primary
primary_provider = self._provider_resolver(primary.provider_id)
primary_request = routed.request.model_copy(deep=True)
- primary_provider.preflight_responses(
- primary_request,
- reasoning=routed.reasoning,
- )
+ primary_failure: ExecutionFailure | None = None
+ try:
+ primary_provider.preflight_responses(
+ primary_request,
+ reasoning=routed.reasoning,
+ )
+ except ExecutionFailure as failure:
+ primary_failure = failure
input_tokens = self._responses_token_counter(routed.request)
def open_candidate(
@@ -255,6 +268,8 @@ class ProviderExecutor:
deep=True,
)
)
+ if index == 0 and primary_failure is not None:
+ raise primary_failure
if index > 0:
provider.preflight_responses(request, reasoning=routed.reasoning)
return provider.stream_responses(
@@ -287,6 +302,7 @@ class ProviderExecutor:
request_id=request_id,
open_candidate=open_candidate,
candidate_selected=None,
+ candidate_failed=None,
)
def _stream_candidates(
@@ -303,6 +319,7 @@ class ProviderExecutor:
request_id: str,
open_candidate: CandidateStreamOpener,
candidate_selected: CandidateSelected | None,
+ candidate_failed: CandidateFailed | None,
) -> AsyncIterator[str]:
"""Run one protocol-blind candidate lifecycle after eager preflight."""
@@ -447,6 +464,8 @@ class ProviderExecutor:
if inspect.isawaitable(selected_result):
await selected_result
return
+ if candidate_failed is not None:
+ candidate_failed(candidate_failure)
if candidate_committed or index + 1 >= len(candidates):
raise candidate_failure
next_target = candidates[index + 1]
diff --git a/src/free_claude_code/core/diagnostics.py b/src/free_claude_code/core/diagnostics.py
index 8cf12edf..1f35b807 100644
--- a/src/free_claude_code/core/diagnostics.py
+++ b/src/free_claude_code/core/diagnostics.py
@@ -91,6 +91,12 @@ def attach_upstream_error_body(
setattr(exc, _UPSTREAM_BODY_TRUNCATED_ATTR, truncated)
+def attached_upstream_error_body(exc: BaseException) -> bytes | str | None:
+ """Return a bounded streamed body previously attached by the transport."""
+ body = getattr(exc, _UPSTREAM_BODY_ATTR, None)
+ return body if isinstance(body, bytes | str) else None
+
+
def exception_cause_types(exc: BaseException) -> tuple[str, ...]:
"""Return exception cause type names without logging their contents."""
return tuple(type(cause).__name__ for cause in _exception_causes(exc))
@@ -103,7 +109,7 @@ def redacted_exception_traceback(exc: BaseException) -> str:
def extract_upstream_error_detail(exc: Exception) -> UpstreamErrorDetail:
"""Extract bounded, redacted body, exception, and cause-chain details."""
- raw_body = getattr(exc, _UPSTREAM_BODY_ATTR, None)
+ raw_body = attached_upstream_error_body(exc)
body_truncated = bool(getattr(exc, _UPSTREAM_BODY_TRUNCATED_ATTR, False))
if raw_body is None:
raw_body = getattr(exc, "body", None)
diff --git a/src/free_claude_code/core/openai_responses/errors.py b/src/free_claude_code/core/openai_responses/errors.py
index 4798054b..81c6c9b6 100644
--- a/src/free_claude_code/core/openai_responses/errors.py
+++ b/src/free_claude_code/core/openai_responses/errors.py
@@ -42,7 +42,12 @@ def openai_error_type_for_failure(
return _FAILURE_ERROR_TYPES[kind]
-def openai_error_payload(*, message: str, error_type: str) -> dict[str, Any]:
+def openai_error_payload(
+ *,
+ message: str,
+ error_type: str,
+ code: str | None = None,
+) -> dict[str, Any]:
"""Return an OpenAI-compatible error envelope."""
return {
@@ -50,7 +55,7 @@ def openai_error_payload(*, message: str, error_type: str) -> dict[str, Any]:
"message": redact_sensitive_error_text(message),
"type": error_type,
"param": None,
- "code": None,
+ "code": code,
}
}
@@ -60,6 +65,11 @@ def openai_error_from_failure(failure: ExecutionFailure) -> dict[str, Any]:
return openai_error_payload(
message=failure.message,
error_type=openai_error_type_for_failure(failure),
+ code=(
+ "context_length_exceeded"
+ if failure.kind is FailureKind.CONTEXT_WINDOW_EXCEEDED
+ else None
+ ),
)["error"]
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 95ffb5b2..db299492 100644
--- a/src/free_claude_code/core/openai_responses/provider_stream.py
+++ b/src/free_claude_code/core/openai_responses/provider_stream.py
@@ -249,7 +249,8 @@ def responses_stream_failure_from_event(
response = data.get("response")
response = response if isinstance(response, dict) else {}
error = response.get("error", data.get("error"))
- error = error if isinstance(error, dict) else {}
+ if not isinstance(error, dict):
+ error = data if event_type == "error" else {}
message = error.get("message")
code = error.get("code", error.get("type"))
return ResponsesStreamFailure(
diff --git a/src/free_claude_code/providers/failure_policy.py b/src/free_claude_code/providers/failure_policy.py
index c4db62da..4029fed1 100644
--- a/src/free_claude_code/providers/failure_policy.py
+++ b/src/free_claude_code/providers/failure_policy.py
@@ -10,6 +10,7 @@ import httpx
import openai
from free_claude_code.core.diagnostics import (
+ attached_upstream_error_body,
extract_upstream_error_detail,
format_execution_failure_message,
safe_exception_message,
@@ -41,6 +42,8 @@ _INVALID_REQUEST_MESSAGE = "Invalid request sent to provider."
_REQUEST_TOO_LARGE_MESSAGE = "Provider rejected the request as too large."
_CONTEXT_WINDOW_EXCEEDED_MESSAGE = "Provider input exceeds the model context window."
_OVERLOADED_MESSAGE = "Provider is currently overloaded. Please retry."
+_CONTEXT_WINDOW_ERROR_CODE = "context_length_exceeded"
+_CONTEXT_WINDOW_FINISH_REASON = "model_context_window_exceeded"
class ProviderRecoveryExhausted(RuntimeError):
@@ -108,6 +111,38 @@ def context_window_exceeded_provider_failure(
return _failure(FailureKind.CONTEXT_WINDOW_EXCEEDED, 400, message, False)
+def is_context_window_error_code(value: object) -> bool:
+ """Return whether one structured provider discriminator means context exhaustion."""
+ return (
+ isinstance(value, str)
+ and value.strip().casefold() == _CONTEXT_WINDOW_ERROR_CODE
+ )
+
+
+def is_context_window_finish_reason(value: object) -> bool:
+ """Return whether one terminal provider reason means context exhaustion."""
+ return (
+ isinstance(value, str)
+ and value.strip().casefold() == _CONTEXT_WINDOW_FINISH_REASON
+ )
+
+
+def reports_context_window_incomplete(
+ event_type: str,
+ payload: Mapping[str, object],
+) -> bool:
+ """Return whether one Responses incomplete terminal reports context exhaustion."""
+ if event_type != "response.incomplete":
+ return False
+ response = payload.get("response")
+ if not isinstance(response, Mapping):
+ return False
+ details = response.get("incomplete_details")
+ return isinstance(details, Mapping) and is_context_window_finish_reason(
+ details.get("reason")
+ )
+
+
def retryable_transient_status(exc: BaseException) -> int | None:
"""Infer a retryable HTTP-like status from one upstream exception."""
if isinstance(exc, ProviderRecoveryExhausted):
@@ -115,6 +150,8 @@ def retryable_transient_status(exc: BaseException) -> int | None:
if isinstance(exc, ExecutionFailure):
status = exc.status_code
return status if exc.retryable and _is_retryable_status(status) else None
+ if _reports_context_window_exceeded(exc):
+ return None
if _reported_status(exc) == 413:
return None
if isinstance(exc, openai.RateLimitError):
@@ -267,6 +304,9 @@ def _classify_provider_failure(
if isinstance(exc, ExecutionFailure):
return exc
+ if _reports_context_window_exceeded(exc):
+ return context_window_exceeded_provider_failure()
+
if _reported_status(exc) == 413:
return _failure(
FailureKind.INVALID_REQUEST,
@@ -399,6 +439,26 @@ def _reported_status(exc: BaseException) -> int | None:
return _status_from_body(getattr(exc, "body", None))
+def _reports_context_window_exceeded(exc: BaseException) -> bool:
+ if is_context_window_error_code(getattr(exc, "code", None)):
+ return True
+
+ bodies = [attached_upstream_error_body(exc), getattr(exc, "body", None)]
+ response = getattr(exc, "response", None)
+ if response is not None:
+ with suppress(Exception):
+ bodies.append(response.content)
+ for body in bodies:
+ for item in _body_candidates(body):
+ if not isinstance(item, Mapping):
+ continue
+ if any(
+ is_context_window_error_code(item.get(key)) for key in ("code", "type")
+ ):
+ return True
+ return False
+
+
def _status_from_body(body: Any) -> int | None:
for item in _body_candidates(body):
if not isinstance(item, Mapping):
diff --git a/src/free_claude_code/providers/openai_chat/provider.py b/src/free_claude_code/providers/openai_chat/provider.py
index c8a29f9e..8b52892e 100644
--- a/src/free_claude_code/providers/openai_chat/provider.py
+++ b/src/free_claude_code/providers/openai_chat/provider.py
@@ -34,7 +34,7 @@ from free_claude_code.core.anthropic.streaming import (
tool_schemas_by_name,
)
from free_claude_code.core.anthropic.usage import anthropic_input_usage_fields
-from free_claude_code.core.failures import ExecutionFailure
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.core.json_types import JsonObject
from free_claude_code.core.openai_responses import (
OpenAIResponsesRequest,
@@ -59,6 +59,8 @@ from free_claude_code.providers.base import BaseProvider, ProviderConfig
from free_claude_code.providers.failure_policy import (
RetryableToolProtocolError,
classify_provider_failure,
+ context_window_exceeded_provider_failure,
+ is_context_window_finish_reason,
is_retryable_stream_error,
underlying_provider_error,
)
@@ -382,6 +384,8 @@ class _OpenAIChatStreamAssembler:
raise TruncatedProviderStreamError(
"Provider stream ended without finish_reason."
)
+ if is_context_window_finish_reason(self._finish_reason):
+ raise context_window_exceeded_provider_failure()
if any(
not self._tool_names.is_unchanged_name(name)
for name in self._tool_name_buffers.values()
@@ -1221,6 +1225,17 @@ class _OpenAIChatStreamRunner:
request_id=self._request_id,
exc_type=type(recovery_error).__name__,
)
+ recovery_failure = classify_provider_failure(
+ underlying_provider_error(recovery_error),
+ provider_name=tag,
+ read_timeout_s=self._provider._config.http_read_timeout,
+ request_id=self._request_id,
+ provider_failure_override=(
+ self._provider._provider_failure_override
+ ),
+ )
+ if recovery_failure.kind is FailureKind.CONTEXT_WINDOW_EXCEEDED:
+ error = recovery_failure
recovery_events = None
if recovery_events is not None:
return _OpenAIChatFailureResolution(
@@ -1326,7 +1341,10 @@ class _OpenAIChatStreamRunner:
if not getattr(chunk, "choices", None):
continue
choice = chunk.choices[0]
- if choice.finish_reason is not None:
+ finish_reason = choice.finish_reason
+ if is_context_window_finish_reason(finish_reason):
+ raise context_window_exceeded_provider_failure()
+ if finish_reason is not None:
terminal_seen = True
delta = choice.delta
if delta is None:
diff --git a/src/free_claude_code/providers/openai_codex/provider.py b/src/free_claude_code/providers/openai_codex/provider.py
index 83d9c505..f17bb61a 100644
--- a/src/free_claude_code/providers/openai_codex/provider.py
+++ b/src/free_claude_code/providers/openai_codex/provider.py
@@ -45,7 +45,10 @@ from free_claude_code.providers.base import BaseProvider, ProviderConfig
from free_claude_code.providers.failure_policy import (
RetryableProviderProtocolError,
classify_provider_failure,
+ context_window_exceeded_provider_failure,
+ is_context_window_error_code,
is_retryable_stream_error,
+ reports_context_window_incomplete,
)
from free_claude_code.providers.http import ProviderAttemptScope, maybe_await_aclose
from free_claude_code.providers.model_listing import (
@@ -410,6 +413,8 @@ class OpenAICodexProvider(BaseProvider):
for event in start_events:
for held in recovery.push(event):
yield held
+ if reports_context_window_incomplete(event_type, payload):
+ raise context_window_exceeded_provider_failure()
if event_type in {
"response.failed",
"error",
@@ -647,6 +652,8 @@ def _effective_error(error: Exception) -> Exception:
extract_upstream_error_detail(error).exception_text
or "OpenAI response failed."
)
+ if is_context_window_error_code(error.code):
+ return context_window_exceeded_provider_failure()
code = (error.code or "").lower()
if "rate" in code or "429" in code:
return ExecutionFailure(FailureKind.RATE_LIMIT, 429, message, True)
diff --git a/src/free_claude_code/providers/openai_responses/transport.py b/src/free_claude_code/providers/openai_responses/transport.py
index 2cefdc68..f96037a3 100644
--- a/src/free_claude_code/providers/openai_responses/transport.py
+++ b/src/free_claude_code/providers/openai_responses/transport.py
@@ -35,7 +35,10 @@ from free_claude_code.providers.admission import (
from free_claude_code.providers.failure_policy import (
RetryableProviderProtocolError,
classify_provider_failure,
+ context_window_exceeded_provider_failure,
+ is_context_window_error_code,
is_retryable_stream_error,
+ reports_context_window_incomplete,
)
from free_claude_code.providers.http import ProviderAttemptScope, maybe_await_aclose
from free_claude_code.providers.stream_recovery import (
@@ -282,6 +285,11 @@ class OpenAIResponsesTransport:
upstream_event.type,
payload,
)
+ if reports_context_window_incomplete(
+ upstream_event.type,
+ payload,
+ ):
+ raise context_window_exceeded_provider_failure()
for event in presenter.feed(upstream_event.type, payload):
for held in recovery.push(event):
yield held
@@ -403,6 +411,8 @@ def _effective_error(error: Exception) -> Exception:
extract_upstream_error_detail(error).exception_text
or "Provider response failed."
)
+ if is_context_window_error_code(error.code):
+ return context_window_exceeded_provider_failure()
code = (error.code or "").lower()
if "rate" in code or "429" in code:
return ExecutionFailure(FailureKind.RATE_LIMIT, 429, message, True)
diff --git a/tests/api/test_execution_failure_contract.py b/tests/api/test_execution_failure_contract.py
index 0b021d62..3b9b4d2b 100644
--- a/tests/api/test_execution_failure_contract.py
+++ b/tests/api/test_execution_failure_contract.py
@@ -592,6 +592,33 @@ def test_messages_context_window_failure_triggers_client_compaction() -> None:
assert trace["provider_retryable"] is False
+def test_responses_context_window_failure_triggers_client_compaction() -> None:
+ provider = CanonicalFailureProvider(
+ [],
+ kind=FailureKind.CONTEXT_WINDOW_EXCEEDED,
+ status_code=400,
+ message="Provider input exceeds the model context window.",
+ retryable=False,
+ )
+ resolver_patch, client = _client_for(provider)
+
+ with resolver_patch, client:
+ response = client.post("/v1/responses", json=_responses_payload())
+
+ request_id = response.headers["request-id"]
+ assert response.status_code == 400
+ assert response.headers["x-should-retry"] == "false"
+ assert response.json()["error"] == {
+ "message": (
+ "Provider input exceeds the model context window.\n\n"
+ f"Request ID: {request_id}"
+ ),
+ "type": "invalid_request_error",
+ "param": None,
+ "code": "context_length_exceeded",
+ }
+
+
def test_responses_pre_start_execution_failure_is_correlated_terminal_json() -> None:
provider = CanonicalFailureProvider(
[],
@@ -711,6 +738,24 @@ def test_responses_post_start_execution_failure_retains_id_after_block_close() -
trace_mock.assert_not_called()
+def test_responses_post_start_context_failure_retains_compaction_code() -> None:
+ provider = CanonicalFailureProvider(
+ _partial_anthropic_stream(close_block=True),
+ kind=FailureKind.CONTEXT_WINDOW_EXCEEDED,
+ status_code=400,
+ message="Provider input exceeds the model context window.",
+ retryable=False,
+ )
+ resolver_patch, client = _client_for(provider)
+
+ with resolver_patch, client:
+ response = client.post("/v1/responses", json=_responses_payload())
+
+ events = parse_sse_text(response.text)
+ assert events[-1].event == "response.failed"
+ assert events[-1].data["response"]["error"]["code"] == ("context_length_exceeded")
+
+
def test_messages_stream_false_discards_partial_content_on_execution_failure() -> None:
provider = CanonicalFailureProvider(
_partial_anthropic_stream(close_block=False),
diff --git a/tests/api/test_model_fallback.py b/tests/api/test_model_fallback.py
index b93c8e7e..15c444f3 100644
--- a/tests/api/test_model_fallback.py
+++ b/tests/api/test_model_fallback.py
@@ -69,18 +69,30 @@ def test_responses_fallback_emits_one_stable_response_lifecycle() -> None:
("/v1/responses", responses_payload()),
),
)
-def test_nonretryable_provider_failure_uses_fallback_before_output(
- path: str,
- payload: dict[str, object],
-) -> None:
- primary = ControlledFallbackProvider(
- failure=ExecutionFailure(
+ "failure",
+ (
+ ExecutionFailure(
kind=FailureKind.PERMISSION,
status_code=403,
message="primary quota exhausted",
retryable=False,
- )
- )
+ ),
+ ExecutionFailure(
+ kind=FailureKind.CONTEXT_WINDOW_EXCEEDED,
+ status_code=400,
+ message="primary context exhausted",
+ retryable=False,
+ ),
+ ),
+ ids=["permission", "context_window"],
+)
+def test_nonretryable_provider_failure_uses_fallback_before_output(
+ path: str,
+ payload: dict[str, object],
+ failure: ExecutionFailure,
+) -> None:
+ primary = ControlledFallbackProvider(failure=failure)
fallback = ControlledFallbackProvider(text="fallback worked")
with fallback_client(primary, fallback) as client:
@@ -88,7 +100,7 @@ def test_nonretryable_provider_failure_uses_fallback_before_output(
assert response.status_code == 200
assert "fallback worked" in response.text
- assert "primary quota exhausted" not in response.text
+ assert failure.message not in response.text
assert primary.close_calls == fallback.close_calls == 1
diff --git a/tests/application/test_chat_service.py b/tests/application/test_chat_service.py
index 5eb65e6d..0235d2b3 100644
--- a/tests/application/test_chat_service.py
+++ b/tests/application/test_chat_service.py
@@ -13,6 +13,7 @@ from free_claude_code.application.chat import (
ChatOperationAcknowledgement,
ChatOperationKind,
ChatService,
+ ChatSession,
ChatUnavailableError,
GenerationStatus,
)
@@ -21,6 +22,7 @@ from free_claude_code.application.ports import ProviderPort, RequestRuntimeLease
from free_claude_code.config.settings import Settings
from free_claude_code.core.anthropic import MessagesRequest
from free_claude_code.core.anthropic.streaming import format_sse_event
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.core.openai_responses import OpenAIResponsesRequest
from free_claude_code.core.reasoning import ReasoningPolicy
from free_claude_code.runtime.chat_sqlite import SQLiteChatStore
@@ -144,6 +146,117 @@ class FakeChatProvider:
yield ""
+def _context_failure() -> ExecutionFailure:
+ return ExecutionFailure(
+ kind=FailureKind.CONTEXT_WINDOW_EXCEEDED,
+ status_code=400,
+ message="Provider input exceeds the model context window.",
+ retryable=False,
+ )
+
+
+class ContextRecoveryProvider(FakeChatProvider):
+ def __init__(self) -> None:
+ super().__init__()
+ self.generation_failures = 0
+ self.generation_failure_after_segment = False
+ self.generation_attempts = 0
+ self.summary_batch_limit: int | None = None
+ self.summary_failure: ExecutionFailure | None = None
+ self.summary_batch_sizes: list[int] = []
+ self.block_summary = False
+ self.summary_started = asyncio.Event()
+
+ async def stream_messages(
+ self,
+ request: MessagesRequest,
+ *,
+ input_tokens: int,
+ request_id: str,
+ response_model: str,
+ reasoning: ReasoningPolicy,
+ ) -> AsyncIterator[str]:
+ is_summary = str(request.system).startswith("Summarize")
+ if is_summary:
+ source = request.messages[0].content
+ if not isinstance(source, str):
+ raise AssertionError("Compaction source must be text.")
+ batch_size = source.count("USER\n")
+ self.summary_batch_sizes.append(batch_size)
+ self.summary_started.set()
+ if self.block_summary:
+ await asyncio.Event().wait()
+ if self.summary_failure is not None:
+ raise self.summary_failure
+ if (
+ self.summary_batch_limit is not None
+ and batch_size > self.summary_batch_limit
+ ):
+ raise _context_failure()
+ else:
+ self.generation_attempts += 1
+ if self.generation_failures > 0:
+ self.generation_failures -= 1
+ if self.generation_failure_after_segment:
+ yield format_sse_event(
+ "message_start",
+ {"type": "message_start", "message": {"content": []}},
+ )
+ yield format_sse_event(
+ "content_block_start",
+ {
+ "type": "content_block_start",
+ "index": 0,
+ "content_block": {"type": "text", "text": ""},
+ },
+ )
+ raise _context_failure()
+
+ async for frame in super().stream_messages(
+ request,
+ input_tokens=input_tokens,
+ request_id=request_id,
+ response_model=response_model,
+ reasoning=reasoning,
+ ):
+ yield frame
+
+
+class MixedFallbackFailureProvider(ContextRecoveryProvider):
+ def __init__(self) -> None:
+ super().__init__()
+ self.fail_candidates = False
+
+ async def stream_messages(
+ self,
+ request: MessagesRequest,
+ *,
+ input_tokens: int,
+ request_id: str,
+ response_model: str,
+ reasoning: ReasoningPolicy,
+ ) -> AsyncIterator[str]:
+ if self.fail_candidates and not str(request.system).startswith("Summarize"):
+ if request.model == "model":
+ raise ExecutionFailure(
+ kind=FailureKind.PERMISSION,
+ status_code=403,
+ message="primary denied access",
+ retryable=False,
+ )
+ if request.model == "fallback":
+ raise _context_failure()
+ raise AssertionError(f"Unexpected fallback model: {request.model}")
+ async for frame in super().stream_messages(
+ request,
+ input_tokens=input_tokens,
+ request_id=request_id,
+ response_model=response_model,
+ reasoning=reasoning,
+ ):
+ yield frame
+
+
class BackpressuredCompletionProvider(FakeChatProvider):
async def stream_messages(
self,
@@ -222,7 +335,7 @@ class FakeRuntime:
self,
provider: FakeChatProvider,
*,
- context_window_tokens: int = 100_000,
+ context_window_tokens: int | None = 100_000,
) -> None:
self.settings = Settings().model_copy(
update={
@@ -341,6 +454,28 @@ async def _drain(operation: _ObservedOperation) -> list[str]:
return events
+async def _seed_completed_turns(
+ service: ChatService,
+ session: ChatSession,
+ *,
+ count: int,
+ operation_offset: int = 1,
+) -> ChatSession:
+ current = session
+ for index in range(operation_offset, operation_offset + count):
+ operation = await _observe_call(
+ service,
+ service.send,
+ current.id,
+ expected_revision=current.revision,
+ operation_id=f"00000000-0000-4000-8000-{index:012d}",
+ text=f"turn {index}",
+ )
+ assert (await _drain(operation))[-1] == "turn.completed"
+ current = await service.get_session(current.id)
+ return current
+
+
@pytest.mark.asyncio
async def test_send_streams_and_persists_interleaved_segments(tmp_path: Path):
provider = FakeChatProvider()
@@ -1847,6 +1982,381 @@ async def test_disconnect_after_durable_completion_cannot_downgrade_status(
await service.close()
[email protected]("operation_kind", ["send", "regenerate"])
+async def test_context_failure_compacts_once_and_retries_same_operation(
+ tmp_path: Path,
+ operation_kind: str,
+) -> None:
+ provider = ContextRecoveryProvider()
+ service, _runtime, store = await _service(tmp_path, provider)
+ try:
+ session = await _seed_completed_turns(
+ service,
+ await service.create_session(),
+ count=2,
+ )
+ prior_generation_id = (
+ (await store.get_transcript(session.id)).turns[-1].generation.id
+ )
+ provider.generation_attempts = 0
+ provider.summary_batch_sizes.clear()
+ provider.generation_failures = 1
+
+ if operation_kind == "send":
+ operation = await _observe_call(
+ service,
+ service.send,
+ session.id,
+ expected_revision=session.revision,
+ operation_id="00000000-0000-4000-8000-000000000100",
+ text="recover this send",
+ )
+ else:
+ operation = await _observe_call(
+ service,
+ service.regenerate,
+ session.id,
+ expected_revision=session.revision,
+ operation_id="00000000-0000-4000-8000-000000000101",
+ )
+ events = await _drain(operation)
+
+ transcript = await store.get_transcript(session.id)
+ generation = transcript.turns[-1].generation
+ assert events.count("turn.started") == 1
+ assert events.count("compaction.started") == 1
+ assert events.count("compaction.completed") == 1
+ assert events[-1] == "turn.completed"
+ assert "turn.failed" not in events
+ assert provider.generation_attempts == 2
+ assert provider.summary_batch_sizes == [1]
+ assert transcript.compaction is not None
+ assert generation.status is GenerationStatus.COMPLETED
+ if operation_kind == "send":
+ assert len(transcript.turns) == 3
+ else:
+ assert len(transcript.turns) == 2
+ assert generation.id != prior_generation_id
+ generation_requests = [
+ request
+ for request in provider.requests
+ if not str(request.system).startswith("Summarize")
+ ]
+ retried_messages = generation_requests[-1].messages
+ assert all(message.role != "assistant" for message in retried_messages)
+ finally:
+ await service.close()
+
+
+async def test_mixed_fallback_failures_do_not_trigger_context_recovery(
+ tmp_path: Path,
+) -> None:
+ provider = MixedFallbackFailureProvider()
+ service, runtime, store = await _service(tmp_path, provider)
+ try:
+ session = await _seed_completed_turns(
+ service,
+ await service.create_session(),
+ count=2,
+ )
+ runtime.settings = runtime.settings.model_copy(
+ update={"model_fallbacks": ("groq/fallback",)}
+ )
+ provider.fail_candidates = True
+ provider.summary_batch_sizes.clear()
+
+ operation = await _observe_call(
+ service,
+ service.send,
+ session.id,
+ expected_revision=session.revision,
+ operation_id="00000000-0000-4000-8000-000000000105",
+ text="do not compact for mixed failures",
+ )
+ events = await _drain(operation)
+
+ transcript = await store.get_transcript(session.id)
+ generation = transcript.turns[-1].generation
+ assert events.count("compaction.started") == 0
+ assert events[-1] == "turn.failed"
+ assert transcript.compaction is None
+ assert provider.summary_batch_sizes == []
+ assert generation.status is GenerationStatus.FAILED
+ assert generation.error_code == FailureKind.CONTEXT_WINDOW_EXCEEDED.value
+ finally:
+ await service.close()
+
+
+async def test_retry_context_failure_reuses_failed_generation_after_compaction(
+ tmp_path: Path,
+) -> None:
+ provider = ContextRecoveryProvider()
+ service, _runtime, store = await _service(tmp_path, provider)
+ try:
+ session = await _seed_completed_turns(
+ service,
+ await service.create_session(),
+ count=1,
+ )
+ provider.generation_failures = 1
+ provider.generation_failure_after_segment = True
+ failed = await _observe_call(
+ service,
+ service.send,
+ session.id,
+ expected_revision=session.revision,
+ operation_id="00000000-0000-4000-8000-000000000110",
+ text="fail after output starts",
+ )
+ assert (await _drain(failed))[-1] == "turn.failed"
+ transcript = await store.get_transcript(session.id)
+ failed_generation_id = transcript.turns[-1].generation.id
+ assert transcript.compaction is None
+
+ session = transcript.session
+ provider.generation_attempts = 0
+ provider.summary_batch_sizes.clear()
+ provider.generation_failure_after_segment = False
+ provider.generation_failures = 1
+ retry = await _observe_call(
+ service,
+ service.retry,
+ session.id,
+ expected_revision=session.revision,
+ operation_id="00000000-0000-4000-8000-000000000111",
+ )
+ events = await _drain(retry)
+
+ transcript = await store.get_transcript(session.id)
+ generation = transcript.turns[-1].generation
+ assert events.count("turn.started") == 1
+ assert events.count("compaction.started") == 1
+ assert events.count("compaction.completed") == 1
+ assert events[-1] == "turn.completed"
+ assert generation.id == failed_generation_id
+ assert generation.status is GenerationStatus.COMPLETED
+ assert provider.generation_attempts == 2
+ assert provider.summary_batch_sizes == [1]
+ finally:
+ await service.close()
+
+
+async def test_second_context_failure_finishes_as_one_failed_generation(
+ tmp_path: Path,
+) -> None:
+ provider = ContextRecoveryProvider()
+ service, _runtime, store = await _service(tmp_path, provider)
+ try:
+ session = await _seed_completed_turns(
+ service,
+ await service.create_session(),
+ count=2,
+ )
+ provider.generation_attempts = 0
+ provider.generation_failures = 2
+ operation = await _observe_call(
+ service,
+ service.send,
+ session.id,
+ expected_revision=session.revision,
+ operation_id="00000000-0000-4000-8000-000000000120",
+ text="still too large after compaction",
+ )
+ events = await _drain(operation)
+
+ transcript = await store.get_transcript(session.id)
+ generation = transcript.turns[-1].generation
+ assert events.count("turn.started") == 1
+ assert events.count("compaction.started") == 1
+ assert events.count("compaction.completed") == 1
+ assert events.count("turn.failed") == 1
+ assert provider.generation_attempts == 2
+ assert generation.status is GenerationStatus.FAILED
+ assert generation.error_code == FailureKind.CONTEXT_WINDOW_EXCEEDED.value
+ finally:
+ await service.close()
+
+
+async def test_uncompactable_context_failure_keeps_canonical_error(
+ tmp_path: Path,
+) -> None:
+ provider = ContextRecoveryProvider()
+ service, _runtime, store = await _service(tmp_path, provider)
+ try:
+ session = await service.create_session()
+ provider.generation_failures = 1
+ operation = await _observe_call(
+ service,
+ service.send,
+ session.id,
+ expected_revision=session.revision,
+ operation_id="00000000-0000-4000-8000-000000000125",
+ text="one oversized turn",
+ )
+ events = await _drain(operation)
+
+ transcript = await store.get_transcript(session.id)
+ generation = transcript.turns[-1].generation
+ assert events.count("compaction.started") == 0
+ assert events[-1] == "turn.failed"
+ assert transcript.compaction is None
+ assert generation.error_code == FailureKind.CONTEXT_WINDOW_EXCEEDED.value
+ assert generation.error_message == (
+ "Provider input exceeds the model context window."
+ )
+ finally:
+ await service.close()
+
+
+async def test_stop_during_reactive_compaction_stops_the_original_generation(
+ tmp_path: Path,
+) -> None:
+ provider = ContextRecoveryProvider()
+ service, _runtime, store = await _service(tmp_path, provider)
+ try:
+ session = await _seed_completed_turns(
+ service,
+ await service.create_session(),
+ count=2,
+ )
+ provider.generation_failures = 1
+ provider.block_summary = True
+ provider.summary_started.clear()
+ operation = await _observe_call(
+ service,
+ service.send,
+ session.id,
+ expected_revision=session.revision,
+ operation_id="00000000-0000-4000-8000-000000000130",
+ text="stop while compacting",
+ )
+ await asyncio.wait_for(provider.summary_started.wait(), timeout=1)
+
+ assert await service.stop(
+ session.id,
+ operation_id=operation.acknowledgement.operation_id,
+ )
+ events = await _drain(operation)
+
+ transcript = await store.get_transcript(session.id)
+ assert events.count("compaction.started") == 1
+ assert events[-1] == "turn.stopped"
+ assert transcript.compaction is None
+ assert transcript.turns[-1].generation.status is GenerationStatus.STOPPED
+ finally:
+ await service.close()
+
+
+async def test_unknown_context_compaction_halves_only_whole_exchange_batches(
+ tmp_path: Path,
+) -> None:
+ provider = ContextRecoveryProvider()
+ runtime = FakeRuntime(provider, context_window_tokens=None)
+ store = SQLiteChatStore(tmp_path / "chat.db", tmp_path / "chat.lock")
+ service = ChatService(runtime, store)
+ await service.start()
+ try:
+ session = await _seed_completed_turns(
+ service,
+ await service.create_session(),
+ count=8,
+ )
+ provider.summary_batch_limit = 2
+ provider.summary_batch_sizes.clear()
+ compact = await _observe_call(
+ service,
+ service.compact,
+ session.id,
+ expected_revision=session.revision,
+ operation_id="00000000-0000-4000-8000-000000000140",
+ )
+
+ assert (await _drain(compact))[-1] == "compaction.completed"
+ assert provider.summary_batch_sizes == [4, 2, 2]
+ transcript = await store.get_transcript(session.id)
+ assert transcript.compaction is not None
+ assert transcript.compaction.covered_through_sequence == 4
+ assert len(transcript.turns) == 8
+ finally:
+ await service.close()
+
+
+async def test_unknown_context_single_exchange_failure_is_actionable(
+ tmp_path: Path,
+) -> None:
+ provider = ContextRecoveryProvider()
+ runtime = FakeRuntime(provider, context_window_tokens=None)
+ store = SQLiteChatStore(tmp_path / "chat.db", tmp_path / "chat.lock")
+ service = ChatService(runtime, store)
+ await service.start()
+ try:
+ session = await _seed_completed_turns(
+ service,
+ await service.create_session(),
+ count=2,
+ )
+ provider.summary_batch_limit = 0
+ provider.summary_batch_sizes.clear()
+ compact = await _observe_call(
+ service,
+ service.compact,
+ session.id,
+ expected_revision=session.revision,
+ operation_id="00000000-0000-4000-8000-000000000150",
+ )
+
+ assert (await _drain(compact))[-1] == "compaction.failed"
+ assert provider.summary_batch_sizes == [1]
+ assert (await store.get_transcript(session.id)).compaction is None
+ finally:
+ await service.close()
+
+
+async def test_unknown_context_non_context_summary_failure_is_not_resized(
+ tmp_path: Path,
+) -> None:
+ provider = ContextRecoveryProvider()
+ runtime = FakeRuntime(provider, context_window_tokens=None)
+ store = SQLiteChatStore(tmp_path / "chat.db", tmp_path / "chat.lock")
+ service = ChatService(runtime, store)
+ await service.start()
+ try:
+ session = await _seed_completed_turns(
+ service,
+ await service.create_session(),
+ count=6,
+ )
+ provider.summary_failure = ExecutionFailure(
+ kind=FailureKind.UPSTREAM,
+ status_code=502,
+ message="provider failed",
+ retryable=False,
+ )
+ provider.summary_batch_sizes.clear()
+ compact = await _observe_call(
+ service,
+ service.compact,
+ session.id,
+ expected_revision=session.revision,
+ operation_id="00000000-0000-4000-8000-000000000160",
+ )
+
+ assert (await _drain(compact))[-1] == "compaction.failed"
+ assert provider.summary_batch_sizes == [2]
+ assert (await store.get_transcript(session.id)).compaction is None
+ finally:
+ await service.close()
+
+
@pytest.mark.asyncio
async def test_stop_during_compaction_commit_waits_and_reports_completion(
tmp_path: Path,
diff --git a/tests/application/test_execution.py b/tests/application/test_execution.py
index e0288a13..7f48af8d 100644
--- a/tests/application/test_execution.py
+++ b/tests/application/test_execution.py
@@ -239,6 +239,21 @@ class ApplicationErrorPreflightProvider(FakeProvider):
raise self._error
+class ExecutionFailurePreflightProvider(FakeProvider):
+ def __init__(self, failure: ExecutionFailure) -> None:
+ super().__init__()
+ self._failure = failure
+
+ def preflight_messages(
+ self,
+ request: MessagesRequest,
+ *,
+ reasoning: ReasoningPolicy,
+ ) -> None:
+ super().preflight_messages(request, reasoning=reasoning)
+ raise self._failure
+
+
class FailingStreamConstructionProvider(FakeProvider):
def stream_messages(
self,
@@ -784,6 +799,36 @@ async def test_nonretryable_provider_failure_selects_fallback_before_first_frame
assert fallback_started["provider_retryable"] is False
+async def test_primary_canonical_preflight_failure_selects_fallback() -> None:
+ primary_failure = ExecutionFailure(
+ kind=FailureKind.CONTEXT_WINDOW_EXCEEDED,
+ status_code=400,
+ message="primary context exceeded",
+ retryable=False,
+ )
+ primary = ExecutionFailurePreflightProvider(primary_failure)
+ fallback = ControlledProvider(["fallback-frame"])
+ providers = {"provider": primary, "fallback": fallback}
+ failures: list[ExecutionFailure] = []
+ executor = ProviderExecutor(
+ providers.__getitem__,
+ progress_timeout_seconds=60.0,
+ )
+
+ stream = executor.stream_messages(
+ _routed_request(_target("fallback", "fallback-model")),
+ raw_log_payload={},
+ request_id="req_preflight_fallback",
+ candidate_failed=failures.append,
+ )
+
+ assert [chunk async for chunk in stream] == ["fallback-frame"]
+ assert failures == [primary_failure]
+ assert primary.stream_calls == []
+ assert fallback.preflight_calls[0][0].model == "fallback-model"
+
+
@pytest.mark.asyncio
async def test_nonretryable_stream_construction_failure_selects_fallback() -> None:
primary_failure = ExecutionFailure(
diff --git a/tests/core/test_failure_protocol_mapping.py b/tests/core/test_failure_protocol_mapping.py
index 8a795734..dbc05a60 100644
--- a/tests/core/test_failure_protocol_mapping.py
+++ b/tests/core/test_failure_protocol_mapping.py
@@ -54,7 +54,7 @@ def test_finalized_status_502_timeout_keeps_existing_api_error_wire_type() -> No
assert openai_failure_payload(failure)["error"]["type"] == "api_error"
-def test_only_anthropic_serialization_adds_the_client_compaction_trigger() -> None:
+def test_each_protocol_adds_its_client_compaction_trigger() -> None:
failure = ExecutionFailure(
kind=FailureKind.CONTEXT_WINDOW_EXCEEDED,
status_code=400,
@@ -78,5 +78,5 @@ def test_only_anthropic_serialization_adds_the_client_compaction_trigger() -> No
),
"type": "invalid_request_error",
"param": None,
- "code": None,
+ "code": "context_length_exceeded",
}
diff --git a/tests/providers/test_failure_policy.py b/tests/providers/test_failure_policy.py
index 134105e7..a6badbfe 100644
--- a/tests/providers/test_failure_policy.py
+++ b/tests/providers/test_failure_policy.py
@@ -48,16 +48,27 @@ def _statusless_openai_error(message: str, body: object | None) -> openai.APIErr
)
-def _http_status_error(status_code: int, message: str) -> httpx.HTTPStatusError:
+def _http_status_error(
+ status_code: int,
+ message: str,
+ *,
+ body: object | None = None,
+) -> httpx.HTTPStatusError:
request = httpx.Request("POST", "https://provider.test/v1/messages")
response = httpx.Response(
status_code,
request=request,
- json={"error": {"message": message, "api_key": "SECRET"}},
+ json=body or {"error": {"message": message, "api_key": "SECRET"}},
)
return httpx.HTTPStatusError(message, request=request, response=response)
+class _CodedError(RuntimeError):
+ def __init__(self, code: str) -> None:
+ super().__init__("provider request failed")
+ self.code = code
+
+
def test_stream_retry_classification_distinguishes_protocol_and_status() -> None:
assert is_retryable_stream_error(TruncatedProviderStreamError("truncated"))
assert is_retryable_stream_error(httpx.ReadError("disconnected"))
@@ -184,6 +195,88 @@ def test_http_413_sources_are_terminal_invalid_requests(error: Exception) -> Non
assert "Provider rejected the request as too large." in failure.message
+ "error",
+ [
+ _CodedError(" Context_Length_Exceeded "),
+ _openai_status_error(
+ openai.BadRequestError,
+ status_code=400,
+ message="maximum context reached",
+ body={"error": {"code": "context_length_exceeded"}},
+ ),
+ _statusless_openai_error(
+ "maximum context reached",
+ {"type": "context_length_exceeded"},
+ ),
+ _http_status_error(
+ 500,
+ "maximum context reached",
+ body={"error": {"type": "context_length_exceeded"}},
+ ),
+ ],
+ ids=["exception_code", "sdk_nested_code", "sdk_root_type", "http_body_type"],
+)
+def test_structured_context_window_signals_are_canonical_and_terminal(
+ error: Exception,
+) -> None:
+ assert not is_retryable_provider_error(error)
+ assert not is_retryable_stream_error(error)
+ assert retryable_upstream_status(error) is None
+
+ failure = classify_provider_failure(
+ error,
+ provider_name="TEST_PROVIDER",
+ read_timeout_s=60.0,
+ request_id="req_context",
+ )
+
+ assert failure.kind is FailureKind.CONTEXT_WINDOW_EXCEEDED
+ assert failure.status_code == 400
+ assert failure.retryable is False
+ assert "Provider input exceeds the model context window." in failure.message
+
+
+ "error",
+ [
+ _openai_status_error(
+ openai.BadRequestError,
+ status_code=400,
+ message="context_length_exceeded",
+ ),
+ _http_status_error(
+ 413,
+ "Request too large for model context_length_exceeded",
+ body={"error": {"code": "request_too_large"}},
+ ),
+ _http_status_error(
+ 413,
+ "Request requires 26206 tokens but TPM limit is 8000",
+ body={
+ "error": {
+ "type": "tokens",
+ "code": "rate_limit_exceeded",
+ "message": "Request too large for the tokens-per-minute limit",
+ }
+ },
+ ),
+ ],
+ ids=["message_only", "request_too_large", "groq_tpm"],
+)
+def test_ambiguous_large_request_signals_are_not_context_exhaustion(
+ error: Exception,
+) -> None:
+ failure = classify_provider_failure(
+ error,
+ provider_name="TEST_PROVIDER",
+ read_timeout_s=60.0,
+ request_id=None,
+ )
+
+ assert failure.kind is FailureKind.INVALID_REQUEST
+
+
def test_nonstandard_capacity_status_remains_retryable() -> None:
error = _openai_status_error(
openai.APIStatusError,
diff --git a/tests/providers/test_openai_codex_provider.py b/tests/providers/test_openai_codex_provider.py
index 8b57477f..14f1cc64 100644
--- a/tests/providers/test_openai_codex_provider.py
+++ b/tests/providers/test_openai_codex_provider.py
@@ -16,7 +16,7 @@ from free_claude_code.core.anthropic.stream_contracts import (
text_content,
)
from free_claude_code.core.diagnostics import ERROR_DETAIL_DISPLAY_CAP_BYTES
-from free_claude_code.core.failures import ExecutionFailure
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.core.model_capabilities import ModelInputModality
from free_claude_code.core.openai_responses import OpenAIResponsesRequest
from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
@@ -68,6 +68,14 @@ class _CloseTrackingResponse(httpx.Response):
raise self._close_error
+class _StaticAsyncBody(httpx.AsyncByteStream):
+ def __init__(self, body: bytes) -> None:
+ self._body = body
+
+ async def __aiter__(self) -> AsyncIterator[bytes]:
+ yield self._body
+
+
class _CloseAwareAuth(_FakeAuth):
def __init__(self, responses: list[_CloseTrackingResponse]) -> None:
super().__init__()
@@ -1123,3 +1131,197 @@ async def test_stream_failure_redacts_credentials_from_customer_diagnostic() ->
assert "sk-this-must-never-be-returned" not in exc_info.value.message
assert "Authorization: <redacted>" in exc_info.value.message
await client.aclose()
+
+
[email protected]("wire_api", ["messages", "responses"])
+ ("event_type", "response_fields"),
+ [
+ (
+ "response.failed",
+ {
+ "status": "failed",
+ "error": {
+ "code": "context_length_exceeded",
+ "message": "maximum context length exceeded",
+ },
+ },
+ ),
+ (
+ "response.incomplete",
+ {
+ "status": "incomplete",
+ "incomplete_details": {"reason": "model_context_window_exceeded"},
+ "usage": {"input_tokens": 10, "output_tokens": 0},
+ },
+ ),
+ ],
+)
+async def test_context_terminals_have_canonical_failure_semantics(
+ wire_api: str,
+ event_type: str,
+ response_fields: dict[str, Any],
+) -> None:
+ calls = 0
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ nonlocal calls
+ calls += 1
+ return httpx.Response(
+ 200,
+ text=_sse(
+ (
+ event_type,
+ {
+ "type": event_type,
+ "response": {"id": "resp_context", **response_fields},
+ },
+ )
+ ),
+ headers={"content-type": "text/event-stream"},
+ request=request,
+ )
+
+ client = httpx.AsyncClient(
+ base_url="https://chatgpt.com/backend-api/codex/",
+ transport=httpx.MockTransport(handler),
+ )
+ provider = OpenAICodexProvider(
+ _config(), auth=_FakeAuth(), admission=_admission(), client=client
+ )
+
+ stream = (
+ provider.stream_messages(
+ _request(),
+ request_id=f"req_context_{wire_api}",
+ response_model="claude-opus-4",
+ )
+ if wire_api == "messages"
+ else provider.stream_responses(
+ _responses_request(),
+ request_id=f"req_context_{wire_api}",
+ response_model="openai/gpt-test",
+ )
+ )
+ with pytest.raises(ExecutionFailure) as exc_info:
+ await _collect(stream)
+
+ assert exc_info.value.kind is FailureKind.CONTEXT_WINDOW_EXCEEDED
+ assert exc_info.value.retryable is False
+ assert calls == 1
+ await client.aclose()
+
+
[email protected]("wire_api", ["messages", "responses"])
+async def test_top_level_context_error_has_canonical_failure_semantics(
+ wire_api: str,
+) -> None:
+ calls = 0
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ nonlocal calls
+ calls += 1
+ return httpx.Response(
+ 200,
+ text=_sse(
+ (
+ "error",
+ {
+ "type": "error",
+ "sequence_number": 0,
+ "code": "context_length_exceeded",
+ "message": "maximum context length exceeded",
+ "param": None,
+ },
+ )
+ ),
+ headers={"content-type": "text/event-stream"},
+ request=request,
+ )
+
+ client = httpx.AsyncClient(
+ base_url="https://chatgpt.com/backend-api/codex/",
+ transport=httpx.MockTransport(handler),
+ )
+ provider = OpenAICodexProvider(
+ _config(), auth=_FakeAuth(), admission=_admission(), client=client
+ )
+
+ stream = (
+ provider.stream_messages(
+ _request(),
+ request_id=f"req_top_level_context_{wire_api}",
+ response_model="claude-opus-4",
+ )
+ if wire_api == "messages"
+ else provider.stream_responses(
+ _responses_request(),
+ request_id=f"req_top_level_context_{wire_api}",
+ response_model="openai/gpt-test",
+ )
+ )
+ with pytest.raises(ExecutionFailure) as exc_info:
+ await _collect(stream)
+
+ assert exc_info.value.kind is FailureKind.CONTEXT_WINDOW_EXCEEDED
+ assert exc_info.value.retryable is False
+ assert calls == 1
+ await client.aclose()
+
+
[email protected]("wire_api", ["messages", "responses"])
+async def test_streamed_context_http_error_has_canonical_failure_semantics(
+ wire_api: str,
+) -> None:
+ calls = 0
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ nonlocal calls
+ calls += 1
+ return httpx.Response(
+ 400,
+ stream=_StaticAsyncBody(
+ json.dumps(
+ {
+ "error": {
+ "code": "context_length_exceeded",
+ "message": "maximum context length exceeded",
+ }
+ }
+ ).encode()
+ ),
+ headers={"content-type": "application/json"},
+ request=request,
+ )
+
+ client = httpx.AsyncClient(
+ base_url="https://chatgpt.com/backend-api/codex/",
+ transport=httpx.MockTransport(handler),
+ )
+ provider = OpenAICodexProvider(
+ _config(), auth=_FakeAuth(), admission=_admission(), client=client
+ )
+
+ stream = (
+ provider.stream_messages(
+ _request(),
+ request_id=f"req_context_http_{wire_api}",
+ response_model="claude-opus-4",
+ )
+ if wire_api == "messages"
+ else provider.stream_responses(
+ _responses_request(),
+ request_id=f"req_context_http_{wire_api}",
+ response_model="openai/gpt-test",
+ )
+ )
+ with pytest.raises(ExecutionFailure) as exc_info:
+ await _collect(stream)
+
+ assert exc_info.value.kind is FailureKind.CONTEXT_WINDOW_EXCEEDED
+ assert exc_info.value.retryable is False
+ assert calls == 1
+ await client.aclose()
diff --git a/tests/providers/test_openai_responses_transport.py b/tests/providers/test_openai_responses_transport.py
index 3e21660c..6f31cac7 100644
--- a/tests/providers/test_openai_responses_transport.py
+++ b/tests/providers/test_openai_responses_transport.py
@@ -16,7 +16,7 @@ from free_claude_code.core.anthropic.stream_contracts import (
text_content,
thinking_content,
)
-from free_claude_code.core.failures import ExecutionFailure
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.core.openai_responses import OpenAIResponsesRequest
from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
from free_claude_code.providers.openai_responses import OpenAIResponsesTransport
@@ -329,6 +329,94 @@ async def test_native_response_failed_retries_before_public_commitment() -> None
assert events[0].data["response"]["id"] == "resp_attempt_2"
[email protected]("wire_api", ["messages", "responses"])
+async def test_context_failure_event_is_canonical_and_not_retried(
+ wire_api: str,
+) -> None:
+ attempts = 0
+ failed = {
+ "type": "response.failed",
+ "sequence_number": 0,
+ "response": {
+ **_completed_response(),
+ "status": "failed",
+ "error": {
+ "message": "maximum context reached",
+ "type": "invalid_request_error",
+ "code": " Context_Length_Exceeded ",
+ },
+ },
+ }
+
+ def handler(_request: httpx2.Request) -> httpx2.Response:
+ nonlocal attempts
+ attempts += 1
+ return httpx2.Response(
+ 200,
+ headers={"content-type": "text/event-stream"},
+ text=_sse(failed),
+ )
+
+ client = _client(handler)
+ try:
+ with pytest.raises(ExecutionFailure) as exc_info:
+ if wire_api == "messages":
+ await _collect(_transport(client, max_attempts=2))
+ else:
+ await _collect_native(
+ _transport(client, max_attempts=2),
+ OpenAIResponsesRequest(model="upstream-model", input="hello"),
+ )
+ finally:
+ await client.close()
+
+ assert attempts == 1
+ assert exc_info.value.kind is FailureKind.CONTEXT_WINDOW_EXCEEDED
+ assert exc_info.value.retryable is False
+
+
[email protected]("wire_api", ["messages", "responses"])
+async def test_top_level_context_error_is_canonical_and_not_retried(
+ wire_api: str,
+) -> None:
+ attempts = 0
+ failed = {
+ "type": "error",
+ "sequence_number": 0,
+ "code": "context_length_exceeded",
+ "message": "maximum context reached",
+ "param": None,
+ }
+
+ def handler(_request: httpx2.Request) -> httpx2.Response:
+ nonlocal attempts
+ attempts += 1
+ return httpx2.Response(
+ 200,
+ headers={"content-type": "text/event-stream"},
+ text=_sse(failed),
+ )
+
+ client = _client(handler)
+ try:
+ with pytest.raises(ExecutionFailure) as exc_info:
+ if wire_api == "messages":
+ await _collect(_transport(client, max_attempts=2))
+ else:
+ await _collect_native(
+ _transport(client, max_attempts=2),
+ OpenAIResponsesRequest(model="upstream-model", input="hello"),
+ )
+ finally:
+ await client.close()
+
+ assert attempts == 1
+ assert exc_info.value.kind is FailureKind.CONTEXT_WINDOW_EXCEEDED
+ assert exc_info.value.retryable is False
+
+
@pytest.mark.asyncio
async def test_native_committed_truncation_emits_one_failed_terminal() -> None:
attempts = 0
@@ -397,6 +485,47 @@ async def test_native_response_incomplete_is_a_normal_terminal() -> None:
assert [event.event for event in events] == ["response.incomplete"]
[email protected]("wire_api", ["messages", "responses"])
+async def test_context_incomplete_reason_is_canonical_failure(wire_api: str) -> None:
+ attempts = 0
+ incomplete = {
+ "type": "response.incomplete",
+ "sequence_number": 0,
+ "response": {
+ **_completed_response(),
+ "status": "incomplete",
+ "incomplete_details": {"reason": "model_context_window_exceeded"},
+ },
+ }
+
+ def handler(_request: httpx2.Request) -> httpx2.Response:
+ nonlocal attempts
+ attempts += 1
+ return httpx2.Response(
+ 200,
+ headers={"content-type": "text/event-stream"},
+ text=_sse(incomplete),
+ )
+
+ client = _client(handler)
+ try:
+ with pytest.raises(ExecutionFailure) as exc_info:
+ if wire_api == "messages":
+ await _collect(_transport(client, max_attempts=2))
+ else:
+ await _collect_native(
+ _transport(client, max_attempts=2),
+ OpenAIResponsesRequest(model="upstream-model", input="hello"),
+ )
+ finally:
+ await client.close()
+
+ assert attempts == 1
+ assert exc_info.value.kind is FailureKind.CONTEXT_WINDOW_EXCEEDED
+ assert exc_info.value.retryable is False
+
+
@pytest.mark.asyncio
async def test_native_response_stops_at_terminal_before_trailing_ping() -> None:
client = _client(
diff --git a/tests/providers/test_streaming_errors.py b/tests/providers/test_streaming_errors.py
index f1c6d059..65db25aa 100644
--- a/tests/providers/test_streaming_errors.py
+++ b/tests/providers/test_streaming_errors.py
@@ -19,7 +19,7 @@ from free_claude_code.core.anthropic.streaming import (
make_text_recovery_body,
tool_schemas_by_name,
)
-from free_claude_code.core.failures import ExecutionFailure
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.core.openai_responses import OpenAIResponsesRequest
from free_claude_code.core.openai_tool_names import OpenAIToolNameCodec
from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
@@ -202,6 +202,20 @@ def _make_chunk(
return chunk
+def _make_context_length_bad_request() -> openai.BadRequestError:
+ response = httpx2.Response(
+ status_code=400,
+ request=httpx2.Request(
+ "POST", "https://test.api.nvidia.com/v1/chat/completions"
+ ),
+ )
+ return openai.BadRequestError(
+ "maximum context reached",
+ response=response,
+ body={"error": {"code": "context_length_exceeded"}},
+ )
+
+
def _make_usage_chunk(*, prompt_tokens: int, completion_tokens: int):
chunk = MagicMock()
chunk.choices = []
@@ -350,6 +364,42 @@ class TestStreamingExceptionHandling:
assert "API failed" in error.message
+ @pytest.mark.asyncio
+ @pytest.mark.parametrize("wire_api", ["messages", "responses"])
+ async def test_context_finish_reason_is_terminal_before_output(
+ self,
+ wire_api: str,
+ ) -> None:
+ provider = _make_provider()
+ stream = AsyncStreamMock(
+ [_make_chunk(finish_reason=" Model_Context_Window_Exceeded ")]
+ )
+
+ with (
+ patch.object(
+ provider._client.chat.completions,
+ "create",
+ new_callable=AsyncMock,
+ return_value=stream,
+ ) as create,
+ pytest.raises(ExecutionFailure) as exc_info,
+ ):
+ if wire_api == "messages":
+ await _collect_stream(provider, _make_request())
+ else:
+ [
+ event
+ async for event in provider.stream_responses(
+ OpenAIResponsesRequest(model="test-model", input="hello"),
+ request_id="req_context",
+ response_model="public-model",
+ )
+ ]
+
+ assert create.await_count == 1
+ assert exc_info.value.kind is FailureKind.CONTEXT_WINDOW_EXCEEDED
+ assert exc_info.value.retryable is False
+
@pytest.mark.asyncio
async def test_read_timeout_with_empty_message_raises_fallback(self):
"""ReadTimeout(TimeoutError()) should raise a non-empty timeout message."""
@@ -1823,6 +1873,123 @@ class TestStreamingExceptionHandling:
assert result.tool_calls == ()
assert stream.closed is True
+ @pytest.mark.asyncio
+ async def test_context_exhaustion_during_recovery_remains_terminal(self):
+ """A recovery request cannot turn context exhaustion into success."""
+ original = ClosableAsyncStreamMock(
+ [_make_chunk(content="partial" + ("x" * 70_000))]
+ )
+ recovery = ClosableAsyncStreamMock(
+ [
+ _make_chunk(content="continued"),
+ _make_chunk(finish_reason="model_context_window_exceeded"),
+ ]
+ )
+ provider = _make_provider()
+
+ with patch.object(
+ provider._client.chat.completions,
+ "create",
+ new_callable=AsyncMock,
+ side_effect=[original, recovery],
+ ):
+ events, failure = await _collect_stream_and_error(
+ provider,
+ _make_request(),
+ )
+
+ assert failure.kind is FailureKind.CONTEXT_WINDOW_EXCEEDED
+ assert failure.retryable is False
+ assert not any(
+ event.event == "message_stop" for event in parse_sse_text("".join(events))
+ )
+ assert original.closed is True
+ assert recovery.closed is True
+
+ @pytest.mark.asyncio
+ async def test_context_error_opening_continuation_remains_terminal(self):
+ """A derived continuation's SDK context error replaces the cutoff."""
+ original = ClosableAsyncStreamMock(
+ [_make_chunk(content="partial" + ("x" * 70_000))]
+ )
+ provider = _make_provider()
+
+ with patch.object(
+ provider._client.chat.completions,
+ "create",
+ new_callable=AsyncMock,
+ side_effect=[original, _make_context_length_bad_request()],
+ ) as create:
+ events, failure = await _collect_stream_and_error(
+ provider,
+ _make_request(),
+ )
+
+ assert create.await_count == 2
+ assert failure.kind is FailureKind.CONTEXT_WINDOW_EXCEEDED
+ assert failure.retryable is False
+ assert not any(
+ event.event == "message_stop" for event in parse_sse_text("".join(events))
+ )
+ assert original.closed is True
+
+ @pytest.mark.asyncio
+ async def test_context_error_opening_tool_repair_remains_terminal(self):
+ """A derived tool repair's SDK context error replaces the truncation."""
+ provider = _make_provider()
+ request = _make_request(
+ tools=[
+ {
+ "name": "echo_smoke",
+ "description": "Echo",
+ "input_schema": {
+ "type": "object",
+ "properties": {"message": {"type": "string"}},
+ "required": ["message"],
+ "additionalProperties": False,
+ },
+ }
+ ]
+ )
+ original = ClosableAsyncStreamMock(
+ [
+ _make_tool_calls_chunk(
+ name="echo_smoke",
+ arguments='{"message":"' + ("x" * 70_000),
+ tool_id="call_repair",
+ )
+ ],
+ error=httpx.ReadError("tool stream cutoff"),
+ )
+
+ with (
+ patch.object(
+ provider,
+ "_create_stream",
+ new_callable=AsyncMock,
+ wraps=provider._create_stream,
+ ) as create_stream,
+ patch.object(
+ provider._client.chat.completions,
+ "create",
+ new_callable=AsyncMock,
+ side_effect=[original, _make_context_length_bad_request()],
+ ) as create,
+ ):
+ events, failure = await _collect_stream_and_error(provider, request)
+
+ assert create.await_count == 2
+ assert [call.args[2] for call in create_stream.await_args_list] == [
+ ProviderOperationKind.GENERATION,
+ ProviderOperationKind.TOOL_REPAIR,
+ ]
+ assert failure.kind is FailureKind.CONTEXT_WINDOW_EXCEEDED
+ assert failure.retryable is False
+ assert not any(
+ event.event == "message_stop" for event in parse_sse_text("".join(events))
+ )
+ assert original.closed is True
+
@pytest.mark.asyncio
async def test_recovery_close_failure_preserves_completed_output(self):
"""A failed stream close cannot replace completed recovery output."""
diff --git a/uv.lock b/uv.lock
index 0afd5bbb..92b2b086 100644
--- a/uv.lock
+++ b/uv.lock
@@ -598,7 +598,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "5.19.2"
+version = "5.19.3"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },