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.tomlindex 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.pyindex 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_idif 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_countif 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.pyindex 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.primaryprimary_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 = failureinput_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_failureif 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.primaryprimary_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 = failureinput_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_failureif 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_resultreturn+ if candidate_failed is not None:+ candidate_failed(candidate_failure)if candidate_committed or index + 1 >= len(candidates):raise candidate_failurenext_target = candidates[index + 1]diff --git a/src/free_claude_code/core/diagnostics.py b/src/free_claude_code/core/diagnostics.pyindex 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.pyindex 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.pyindex 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.pyindex 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 httpximport openaifrom 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_codereturn status if exc.retryable and _is_retryable_status(status) else None+ if _reports_context_window_exceeded(exc):+ return Noneif _reported_status(exc) == 413:return Noneif 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.pyindex 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, FailureKindfrom free_claude_code.core.json_types import JsonObjectfrom free_claude_code.core.openai_responses import (OpenAIResponsesRequest,@@ -59,6 +59,8 @@ from free_claude_code.providers.base import BaseProvider, ProviderConfigfrom 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_failurerecovery_events = Noneif recovery_events is not None:return _OpenAIChatFailureResolution(@@ -1326,7 +1341,10 @@ class _OpenAIChatStreamRunner:if not getattr(chunk, "choices", None):continuechoice = 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 = Truedelta = choice.deltaif delta is None:diff --git a/src/free_claude_code/providers/openai_codex/provider.py b/src/free_claude_code/providers/openai_codex/provider.pyindex 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, ProviderConfigfrom 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_aclosefrom 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_textor "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.pyindex 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_aclosefrom 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_textor "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.pyindex 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.pyindex 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 == 200assert "fallback worked" in response.text- assert "primary quota exhausted" not in response.text+ assert failure.message not in response.textassert primary.close_calls == fallback.close_calls == 1diff --git a/tests/application/test_chat_service.py b/tests/application/test_chat_service.pyindex 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, RequestRuntimeLeasefrom free_claude_code.config.settings import Settingsfrom free_claude_code.core.anthropic import MessagesRequestfrom free_claude_code.core.anthropic.streaming import format_sse_event+from free_claude_code.core.failures import ExecutionFailure, FailureKindfrom free_claude_code.core.openai_responses import OpenAIResponsesRequestfrom free_claude_code.core.reasoning import ReasoningPolicyfrom 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.asyncioasync 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.asyncioasync 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.pyindex 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_frameassert 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.asyncioasync 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.pyindex 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() -> Noassert 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.pyindex 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) -> Nonassert "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.pyindex 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, FailureKindfrom free_claude_code.core.model_capabilities import ModelInputModalityfrom free_claude_code.core.openai_responses import OpenAIResponsesRequestfrom 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.messageassert "Authorization: <redacted>" in exc_info.value.messageawait 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.pyindex 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, FailureKindfrom free_claude_code.core.openai_responses import OpenAIResponsesRequestfrom free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicyfrom free_claude_code.providers.openai_responses import OpenAIResponsesTransport@@ -329,6 +329,94 @@ async def test_native_response_failed_retries_before_public_commitment() -> Noneassert 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.asyncioasync 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.asyncioasync 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.pyindex 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, FailureKindfrom free_claude_code.core.openai_responses import OpenAIResponsesRequestfrom free_claude_code.core.openai_tool_names import OpenAIToolNameCodecfrom 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.asyncioasync 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.asyncioasync 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.lockindex 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" },