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 Claude sessions from provider context overflow (#1215)
Ali Khokhar36bb28255892
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.mdindex 83564066..8cc4aeb9 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -609,6 +609,10 @@ upstream request body it will later stream. `BaseProvider` makes that operationabstract, so a new provider cannot silently omit the commit-boundary validation.LM Studio composes the OpenAI-chat conversion first and its context-budget probesecond; conversion failure therefore cannot open a stream or run the probe.+Provider classifiers and preflights report context exhaustion as the neutral+`CONTEXT_WINDOW_EXCEEDED` execution failure. The Anthropic serializer alone adds+Claude's `prompt is too long` compaction trigger; providers never encode a+client-specific recovery phrase.Providers call the OpenAI request policy for Anthropic-to-OpenAI conversion,reasoning replay selection, `extra_body`, and chat-completion field normalization.diff --git a/pyproject.toml b/pyproject.tomlindex be53a66d..c5e19f27 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "free-claude-code"-version = "4.11.3"+version = "4.11.4"description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"readme = "README.md"requires-python = ">=3.14.0"diff --git a/src/free_claude_code/core/anthropic/errors.py b/src/free_claude_code/core/anthropic/errors.pyindex 200b1116..3b8374bb 100644--- a/src/free_claude_code/core/anthropic/errors.py+++ b/src/free_claude_code/core/anthropic/errors.py@@ -20,6 +20,7 @@ _ANTHROPIC_ERROR_STATUS_CODES = {_FAILURE_ERROR_TYPES = {FailureKind.INVALID_REQUEST: "invalid_request_error",+ FailureKind.CONTEXT_WINDOW_EXCEEDED: "invalid_request_error",FailureKind.AUTHENTICATION: "authentication_error",FailureKind.PERMISSION: "permission_error",FailureKind.RATE_LIMIT: "rate_limit_error",@@ -77,11 +78,20 @@ def anthropic_failure_payload("""Serialize a canonical execution failure as an Anthropic JSON error."""return anthropic_error_payload(error_type=anthropic_error_type_for_failure(failure),- message=failure.message,+ message=_anthropic_failure_message(failure),request_id=request_id,)+def _anthropic_failure_message(failure: ExecutionFailure) -> str:+ """Add client-recognized wording only at the Anthropic wire boundary."""+ if failure.kind != FailureKind.CONTEXT_WINDOW_EXCEEDED:+ return failure.message+ if failure.message.lstrip().lower().startswith("prompt is too long"):+ return failure.message+ return f"prompt is too long\n\n{failure.message}"++def anthropic_status_for_error_type(error_type: str) -> int:"""Return the standard HTTP status for an Anthropic error type."""return _ANTHROPIC_ERROR_STATUS_CODES.get(error_type, 500)diff --git a/src/free_claude_code/core/failures.py b/src/free_claude_code/core/failures.pyindex c2dacbf5..9f813ca7 100644--- a/src/free_claude_code/core/failures.py+++ b/src/free_claude_code/core/failures.py@@ -8,6 +8,7 @@ class FailureKind(StrEnum):"""Stable failure categories shared across execution and wire adapters."""INVALID_REQUEST = "invalid_request"+ CONTEXT_WINDOW_EXCEEDED = "context_window_exceeded"AUTHENTICATION = "authentication"PERMISSION = "permission"RATE_LIMIT = "rate_limit"diff --git a/src/free_claude_code/core/openai_responses/errors.py b/src/free_claude_code/core/openai_responses/errors.pyindex 1e288670..4798054b 100644--- a/src/free_claude_code/core/openai_responses/errors.py+++ b/src/free_claude_code/core/openai_responses/errors.py@@ -7,6 +7,7 @@ from free_claude_code.core.failures import ExecutionFailure, FailureKind_FAILURE_ERROR_TYPES = {FailureKind.INVALID_REQUEST: "invalid_request_error",+ FailureKind.CONTEXT_WINDOW_EXCEEDED: "invalid_request_error",FailureKind.AUTHENTICATION: "authentication_error",FailureKind.PERMISSION: "permission_error",FailureKind.RATE_LIMIT: "rate_limit_error",diff --git a/src/free_claude_code/providers/failure_policy.py b/src/free_claude_code/providers/failure_policy.pyindex 412918d5..fe6743ff 100644--- a/src/free_claude_code/providers/failure_policy.py+++ b/src/free_claude_code/providers/failure_policy.py@@ -32,6 +32,7 @@ _INTERNAL_ERROR_MARKERS = frozenset({"internal_server_error", "internal server e_AUTHENTICATION_MESSAGE = "Provider authentication failed. Check API key."_RATE_LIMIT_MESSAGE = "Provider rate limit reached. Please retry shortly."_INVALID_REQUEST_MESSAGE = "Invalid request sent to provider."+_CONTEXT_WINDOW_EXCEEDED_MESSAGE = "Provider input exceeds the model context window."_OVERLOADED_MESSAGE = "Provider is currently overloaded. Please retry."@@ -89,6 +90,13 @@ def overloaded_provider_failure() -> ExecutionFailure:return _failure(FailureKind.OVERLOADED, 529, _OVERLOADED_MESSAGE, True)+def context_window_exceeded_provider_failure(+ message: str = _CONTEXT_WINDOW_EXCEEDED_MESSAGE,+) -> ExecutionFailure:+ """Return the canonical non-retryable provider context-window failure."""+ return _failure(FailureKind.CONTEXT_WINDOW_EXCEEDED, 400, message, False)++def retryable_transient_status(exc: BaseException) -> int | None:"""Infer a retryable HTTP-like status from one upstream exception."""if isinstance(exc, ProviderRecoveryExhausted):diff --git a/src/free_claude_code/providers/lmstudio/client.py b/src/free_claude_code/providers/lmstudio/client.pyindex 243957d8..2916c009 100644--- a/src/free_claude_code/providers/lmstudio/client.py+++ b/src/free_claude_code/providers/lmstudio/client.py@@ -16,7 +16,6 @@ import timeimport httpxfrom loguru import logger-from free_claude_code.application.errors import InvalidRequestErrorfrom free_claude_code.core.anthropic import ReasoningReplayMode, get_token_countfrom free_claude_code.core.anthropic.models import MessagesRequestfrom free_claude_code.core.reasoning import (@@ -26,6 +25,9 @@ from free_claude_code.core.reasoning import ()from free_claude_code.providers.admission import ProviderAdmissionControllerfrom free_claude_code.providers.base import ProviderConfig+from free_claude_code.providers.failure_policy import (+ context_window_exceeded_provider_failure,+)from free_claude_code.providers.openai_chat import (NamedEffortReasoning,OpenAIChatProfile,@@ -59,9 +61,8 @@ class LMStudioProvider(OpenAIChatProvider):# LM Studio truncates the stream silently (no terminal event) when the# prompt exceeds the loaded context. Refuse clearly over-budget prompts- # up front with the same "prompt is too long" invalid_request_error the- # real Anthropic API uses, so Claude Code can compact/retry instead of- # dying mid-stream.+ # up front as a context-window failure so protocol adapters can tell their+ # clients to compact/retry instead of letting the stream die silently._CONTEXT_CACHE_TTL_S = 30.0def __init__(@@ -98,9 +99,10 @@ class LMStudioProvider(OpenAIChatProvider):# fired, and letting it through risks a silent LM Studio truncation.budget = int(loaded_context * 0.9)if estimate > budget:- raise InvalidRequestError(- f"prompt is too long: {estimate} tokens > {budget} "- f"maximum (90% of loaded LM Studio context {loaded_context})"+ raise context_window_exceeded_provider_failure(+ f"Estimated provider input ({estimate} tokens) exceeds the safe "+ f"LM Studio context budget ({budget} tokens; 90% of loaded "+ f"context {loaded_context}).")def _loaded_context_length(self) -> int | None:diff --git a/src/free_claude_code/providers/nvidia_nim/client.py b/src/free_claude_code/providers/nvidia_nim/client.pyindex a75124bb..252651ac 100644--- a/src/free_claude_code/providers/nvidia_nim/client.py+++ b/src/free_claude_code/providers/nvidia_nim/client.py@@ -1,6 +1,7 @@"""NVIDIA NIM provider implementation."""import json+import refrom collections.abc import Mappingfrom typing import Any@@ -14,6 +15,7 @@ from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPfrom free_claude_code.providers.admission import ProviderAdmissionControllerfrom free_claude_code.providers.base import ProviderConfigfrom free_claude_code.providers.failure_policy import (+ context_window_exceeded_provider_failure,overloaded_provider_failure,)from free_claude_code.providers.openai_chat import (@@ -34,6 +36,10 @@ from .tool_schema import ()_DEGRADED_FUNCTION_STATE = "degraded function cannot be invoked"+_NEGATIVE_MAX_TOKENS_PATTERN = re.compile(+ r"\bmax_tokens must be at least 1,\s*got\s+-[1-9]\d*\b",+ re.IGNORECASE,+)_PROFILE = OpenAIChatProfile(NIM_REQUEST_POLICY,NO_REASONING,@@ -124,27 +130,50 @@ class NvidiaNimProvider(OpenAIChatProvider):return Nonedef _provider_failure_override(self, error: Exception) -> ExecutionFailure | None:- """Map NVIDIA Cloud Function deployment failure onto canonical overload."""+ """Classify NVIDIA-specific 400 responses by their actual semantics."""if not isinstance(error, openai.BadRequestError):return Noneif getattr(error, "status_code", None) != 400:return None- body = getattr(error, "body", None)- if not isinstance(body, Mapping):- return None- detail = body.get("detail")- if not isinstance(detail, str):- return None- function_ref, separator, state = detail.lower().partition(": ")- function_id = function_ref.removeprefix("function id ").strip(" '\"")- if (- not separator- or not function_ref.startswith("function id ")- or not function_id- or state.strip() != _DEGRADED_FUNCTION_STATE- ):- return None- return overloaded_provider_failure()+ bodies = _nim_error_bodies(error)+ if any(_is_context_window_exhaustion(body) for body in bodies):+ return context_window_exceeded_provider_failure()+ if any(_is_degraded_function(body) for body in bodies):+ return overloaded_provider_failure()+ return None+++def _nim_error_bodies(error: Exception) -> tuple[Mapping[str, Any], ...]:+ body = getattr(error, "body", None)+ if not isinstance(body, Mapping):+ return ()+ nested = body.get("error")+ if isinstance(nested, Mapping):+ return body, nested+ return (body,)+++def _is_context_window_exhaustion(body: Mapping[str, Any]) -> bool:+ message = body.get("message")+ return (+ body.get("param") == "max_tokens"+ and isinstance(message, str)+ and _NEGATIVE_MAX_TOKENS_PATTERN.search(message) is not None+ )+++def _is_degraded_function(body: Mapping[str, Any]) -> bool:+ detail = body.get("detail")+ if not isinstance(detail, str):+ return False+ function_ref, separator, state = detail.lower().partition(": ")+ function_id = function_ref.removeprefix("function id ").strip(" '\"")+ return bool(+ separator+ and function_ref.startswith("function id ")+ and function_id+ and state.strip() == _DEGRADED_FUNCTION_STATE+ )def _is_reasoning_budget_rejection(error_text: str) -> bool:diff --git a/tests/api/test_execution_failure_contract.py b/tests/api/test_execution_failure_contract.pyindex b2e86e51..32e98be4 100644--- a/tests/api/test_execution_failure_contract.py+++ b/tests/api/test_execution_failure_contract.py@@ -265,6 +265,45 @@ def test_messages_pre_start_execution_failure_is_correlated_terminal_json() -> Nassert provider.stream_kwargs[0]["request_id"] == request_id+def test_messages_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,+ patch("free_claude_code.api.response_streams.trace_event") as trace_mock,+ client,+ ):+ response = client.post("/v1/messages", json=_messages_payload(stream=True))++ request_id = response.headers["request-id"]+ assert response.status_code == 400+ assert response.headers["x-should-retry"] == "false"+ assert response.json() == {+ "type": "error",+ "error": {+ "type": "invalid_request_error",+ "message": (+ "prompt is too long\n\n"+ "Provider input exceeds the model context window.\n\n"+ f"Request ID: {request_id}"+ ),+ },+ "request_id": request_id,+ }+ trace = _terminal_trace(trace_mock)+ assert trace["failure_kind"] == "context_window_exceeded"+ assert trace["status_code"] == 400+ assert trace["error_type"] == "invalid_request_error"+ assert trace["provider_retryable"] is False++def test_responses_pre_start_execution_failure_is_correlated_terminal_json() -> None:provider = CanonicalFailureProvider([],diff --git a/tests/core/test_failure_protocol_mapping.py b/tests/core/test_failure_protocol_mapping.pyindex dbf70324..8a795734 100644--- a/tests/core/test_failure_protocol_mapping.py+++ b/tests/core/test_failure_protocol_mapping.py@@ -17,6 +17,11 @@ from free_claude_code.core.openai_responses.errors import (("kind", "anthropic_type", "openai_type"),[(FailureKind.INVALID_REQUEST, "invalid_request_error", "invalid_request_error"),+ (+ FailureKind.CONTEXT_WINDOW_EXCEEDED,+ "invalid_request_error",+ "invalid_request_error",+ ),(FailureKind.AUTHENTICATION, "authentication_error", "authentication_error"),(FailureKind.PERMISSION, "permission_error", "permission_error"),(FailureKind.RATE_LIMIT, "rate_limit_error", "rate_limit_error"),@@ -47,3 +52,31 @@ def test_finalized_status_502_timeout_keeps_existing_api_error_wire_type() -> Noassert anthropic_failure_payload(failure)["error"]["type"] == "api_error"assert openai_failure_payload(failure)["error"]["type"] == "api_error"+++def test_only_anthropic_serialization_adds_the_client_compaction_trigger() -> None:+ failure = ExecutionFailure(+ kind=FailureKind.CONTEXT_WINDOW_EXCEEDED,+ status_code=400,+ message="Provider input exceeds its context window.\n\nRequest ID: req_context",+ retryable=False,+ )++ anthropic_error = anthropic_failure_payload(failure)["error"]+ openai_error = openai_failure_payload(failure)["error"]++ assert anthropic_error == {+ "type": "invalid_request_error",+ "message": (+ "prompt is too long\n\nProvider input exceeds its context window."+ "\n\nRequest ID: req_context"+ ),+ }+ assert openai_error == {+ "message": (+ "Provider input exceeds its context window.\n\nRequest ID: req_context"+ ),+ "type": "invalid_request_error",+ "param": None,+ "code": None,+ }diff --git a/tests/core/test_failures.py b/tests/core/test_failures.pyindex 1a2672bb..00a4a580 100644--- a/tests/core/test_failures.py+++ b/tests/core/test_failures.py@@ -14,6 +14,7 @@ from free_claude_code.core.failures import (def test_failure_kind_has_only_protocol_neutral_semantics() -> None:assert tuple(FailureKind) == (FailureKind.INVALID_REQUEST,+ FailureKind.CONTEXT_WINDOW_EXCEEDED,FailureKind.AUTHENTICATION,FailureKind.PERMISSION,FailureKind.RATE_LIMIT,@@ -24,6 +25,7 @@ def test_failure_kind_has_only_protocol_neutral_semantics() -> None:)assert tuple(kind.value for kind in FailureKind) == ("invalid_request",+ "context_window_exceeded","authentication","permission","rate_limit",diff --git a/tests/providers/test_lmstudio.py b/tests/providers/test_lmstudio.pyindex 418918eb..f162c590 100644--- a/tests/providers/test_lmstudio.py+++ b/tests/providers/test_lmstudio.py@@ -7,6 +7,7 @@ import pytestfrom free_claude_code.application.errors import InvalidRequestErrorfrom free_claude_code.config.provider_catalog import LMSTUDIO_DEFAULT_BASE+from free_claude_code.core.failures import ExecutionFailure, FailureKindfrom free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicyfrom free_claude_code.providers.base import ProviderConfigfrom free_claude_code.providers.lmstudio import LMStudioProvider@@ -219,10 +220,20 @@ def test_preflight_context_budget_rejects_request_over_90_percent(lmstudio_provi"free_claude_code.providers.lmstudio.client.get_token_count",return_value=901,),- pytest.raises(InvalidRequestError, match="prompt is too long"),+ pytest.raises(ExecutionFailure) as exc_info,):lmstudio_provider._preflight_context_budget(make_request())+ failure = exc_info.value+ assert failure.kind is FailureKind.CONTEXT_WINDOW_EXCEEDED+ assert failure.status_code == 400+ assert failure.retryable is False+ assert failure.message == (+ "Estimated provider input (901 tokens) exceeds the safe LM Studio "+ "context budget (900 tokens; 90% of loaded context 1000)."+ )+ assert "prompt is too long" not in failure.message+def test_loaded_context_length_reads_max_across_loaded_models(lmstudio_provider):response = MagicMock()diff --git a/tests/providers/test_nvidia_nim_degraded_retry.py b/tests/providers/test_nvidia_nim_degraded_retry.pyindex 4b50ea39..067334e8 100644--- a/tests/providers/test_nvidia_nim_degraded_retry.py+++ b/tests/providers/test_nvidia_nim_degraded_retry.py@@ -70,6 +70,28 @@ def _bad_request(return openai.BadRequestError("Bad Request", response=response, body=body)+def _context_window_error(+ *,+ message: str = (+ "max_tokens must be at least 1, got -853. (parameter=max_tokens, value=-853)"+ ),+ param: str = "max_tokens",+ nested: bool = False,+) -> openai.BadRequestError:+ request = httpx.Request(+ "POST", "https://integrate.api.nvidia.com/v1/chat/completions"+ )+ response = httpx.Response(400, request=request)+ error_body: dict[str, object] = {+ "message": message,+ "type": "BadRequestError",+ "param": param,+ "code": 400,+ }+ body = {"error": error_body} if nested else error_body+ return openai.BadRequestError("Bad Request", response=response, body=body)++def _successful_stream(text: str = "Recovered"):chunk = MagicMock()chunk.choices = [@@ -174,6 +196,74 @@ async def test_degraded_function_exhaustion_is_detailed_redacted_overload() -> Nassert "error_message" not in error_traces[-1][email protected]("nested", [False, True])+async def test_negative_derived_max_tokens_is_context_window_failure(+ nested: bool,+) -> None:+ provider = _nim(_admission())++ with (+ patch.object(+ provider._client.chat.completions,+ "create",+ new_callable=AsyncMock,+ side_effect=_context_window_error(nested=nested),+ ) as create,+ pytest.raises(ExecutionFailure) as exc_info,+ ):+ [+ event+ async for event in provider.stream_response(+ make_messages_request(), request_id="req_context"+ )+ ]++ assert create.await_count == 1+ failure = exc_info.value+ assert failure.kind is FailureKind.CONTEXT_WINDOW_EXCEEDED+ assert failure.status_code == 400+ assert failure.retryable is False+ assert "Mapped message: Provider input exceeds the model context window." in (+ failure.message+ )+ assert "max_tokens must be at least 1, got -853" in failure.message+ assert "Request ID: req_context" in failure.message+ assert "prompt is too long" not in failure.message+++ ("message", "param"),+ [+ ("max_tokens must be at least 1, got 0", "max_tokens"),+ ("max_tokens must be at least 1, got -853", "temperature"),+ ("max_tokens must be less than or equal to 8192", "max_tokens"),+ ],+)+async def test_other_nim_max_token_errors_remain_invalid_requests(+ message: str,+ param: str,+) -> None:+ provider = _nim(_admission())++ with (+ patch.object(+ provider._client.chat.completions,+ "create",+ new_callable=AsyncMock,+ side_effect=_context_window_error(message=message, param=param),+ ) as create,+ pytest.raises(ExecutionFailure) as exc_info,+ ):+ [event async for event in provider.stream_response(make_messages_request())]++ assert create.await_count == 1+ assert exc_info.value.kind is FailureKind.INVALID_REQUEST+ assert exc_info.value.status_code == 400+ assert exc_info.value.retryable is False++@pytest.mark.parametrize("detail",[diff --git a/uv.lock b/uv.lockindex 62ee825b..1f84a7f8 100644--- a/uv.lock+++ b/uv.lock@@ -620,7 +620,7 @@ wheels = [[[package]]name = "free-claude-code"-version = "4.11.3"+version = "4.11.4"source = { editable = "." }dependencies = [{ name = "aiohttp" },