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
Make stream recovery a pure commit policy (#1507)
Ali Khokhar7bf094147f47
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.mdindex a012708e..adacb83a 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -1066,7 +1066,9 @@ map the canonical kind and status to their wire error types.[providers/failure_policy.py](src/free_claude_code/providers/failure_policy.py)owns generic raw OpenAI SDK and `httpx` exception classification,transient status/body inference, stable provider wording, and final diagnostic-construction for those failures.+construction for those failures. It also owns phase-specific retry+qualification: admission classifies failures while opening an operation, while+an already-open stream uses the narrower stream-failure policy.Concrete adapters may supply one narrow semantic override for an upstream quirkthat the shared SDK cannot express correctly. The concrete adapter owns theexact upstream marker, while the shared failure policy owns its canonical@@ -1081,6 +1083,8 @@ marker enters `core/`, another provider, or an API adapter.[providers/stream_recovery.py](src/free_claude_code/providers/stream_recovery.py)owns only the 0.75-second/65,536-byte commit holdback and the choice betweentransparent replay, request-local continuation/tool salvage, and final failure.+It consumes an explicit retryability decision and does not import provider+transport SDKs or classify exceptions.`ProviderRetrySession` owns one five-attempt budget for the whole logicalexecution: initial opening, deterministic request-shape corrections, earlyreplay, continuation, and tool repair all consume that same budget. There are nodiff --git a/pyproject.toml b/pyproject.tomlindex 7fb27a74..d8821f80 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "free-claude-code"-version = "5.13.0"+version = "5.13.1"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/providers/failure_policy.py b/src/free_claude_code/providers/failure_policy.pyindex 36daba17..c0488278 100644--- a/src/free_claude_code/providers/failure_policy.py+++ b/src/free_claude_code/providers/failure_policy.py@@ -192,6 +192,31 @@ def is_retryable_provider_error(exc: BaseException) -> bool:)+def is_retryable_stream_error(exc: BaseException) -> bool:+ """Return whether an opened stream failure permits replay or recovery."""+ if isinstance(exc, RetryableProviderProtocolError):+ return True+ if isinstance(exc, ExecutionFailure):+ return exc.retryable+ if isinstance(exc, openai.AuthenticationError | openai.BadRequestError):+ return False+ if retryable_transient_status(exc) is not None:+ return True+ return isinstance(+ exc,+ (+ TimeoutError,+ httpx.ReadTimeout,+ httpx.ReadError,+ httpx.RemoteProtocolError,+ httpx.ConnectError,+ httpx.NetworkError,+ openai.APITimeoutError,+ openai.APIConnectionError,+ ),+ )++def retryable_upstream_status(exc: BaseException) -> int | None:"""Return a status eligible for provider-opening backoff."""status = retryable_transient_status(exc)diff --git a/src/free_claude_code/providers/openai_chat/provider.py b/src/free_claude_code/providers/openai_chat/provider.pyindex 1ff93348..834f9ee2 100644--- a/src/free_claude_code/providers/openai_chat/provider.py+++ b/src/free_claude_code/providers/openai_chat/provider.py@@ -43,6 +43,7 @@ from free_claude_code.providers.base import BaseProvider, ProviderConfigfrom free_claude_code.providers.failure_policy import (RetryableToolProtocolError,classify_provider_failure,+ is_retryable_stream_error,underlying_provider_error,)from free_claude_code.providers.http import (@@ -58,7 +59,6 @@ from free_claude_code.providers.stream_recovery import (RecoveryController,RecoveryFailureAction,TruncatedProviderStreamError,- is_retryable_stream_error,)from .output_cap import clamp_output_tokens, parse_output_token_cap@@ -733,15 +733,17 @@ class _OpenAIChatStreamRunner:and ledger.has_emitted_tool_block()and all_emitted_tools_complete(ledger, self._request))+ retryable = (+ attempt.failure_retryable+ if attempt is not None and attempt.failure_retryable is not None+ else is_retryable_stream_error(error)+ )decision = recovery.advance_failure(- error,+ retryable=retryable,stream_opened=stream_opened,generated_output=generated_output,complete_tool_salvageable=complete_tool_salvageable,attempts_remaining=retry_session.attempts_remaining,- retryable_override=(- attempt.failure_retryable if attempt is not None else None- ),)if decision.action == RecoveryFailureAction.EARLY_RETRY:trace_event(@@ -1031,9 +1033,6 @@ class _OpenAIChatStreamRunner:retry_session: ProviderRetrySession,) -> list[str] | None:"""Build terminal recovery events when the interrupted stream permits it."""- if not is_retryable_stream_error(error):- return None-if ledger.has_emitted_tool_block():if not all_emitted_tools_complete(ledger, self._request):repair_events = await self._repair_tool_args(diff --git a/src/free_claude_code/providers/openai_codex/provider.py b/src/free_claude_code/providers/openai_codex/provider.pyindex aecdae29..277e4cab 100644--- a/src/free_claude_code/providers/openai_codex/provider.py+++ b/src/free_claude_code/providers/openai_codex/provider.py@@ -38,6 +38,7 @@ from free_claude_code.providers.base import BaseProvider, ProviderConfigfrom free_claude_code.providers.failure_policy import (RetryableProviderProtocolError,classify_provider_failure,+ is_retryable_stream_error,)from free_claude_code.providers.stream_recovery import RecoveryController@@ -277,18 +278,22 @@ class OpenAICodexProvider(BaseProvider):error = _effective_error(raw_error)if attempt is not None and not attempt.accepted:await attempt.retry(error)- retryable = (+ retryable_override = (attempt.failure_retryableif attempt is not None and attempt.failure_retryable is not Noneelse None)+ retryable = (+ retryable_override+ if retryable_override is not None+ else is_retryable_stream_error(error)+ )decision = recovery.advance_failure(- error,+ retryable=retryable,stream_opened=stream_opened,generated_output=recovery.committed,complete_tool_salvageable=False,attempts_remaining=retry_session.attempts_remaining,- retryable_override=retryable,)if (not decision.committeddiff --git a/src/free_claude_code/providers/stream_recovery.py b/src/free_claude_code/providers/stream_recovery.pyindex 3fafd0a8..149bef2c 100644--- a/src/free_claude_code/providers/stream_recovery.py+++ b/src/free_claude_code/providers/stream_recovery.py@@ -5,12 +5,7 @@ from collections.abc import Callablefrom dataclasses import dataclassfrom enum import StrEnum-import httpx-import openai--from free_claude_code.core.failures import ExecutionFailure--from .failure_policy import RetryableProviderProtocolError, retryable_transient_status+from .failure_policy import RetryableProviderProtocolErrorEARLY_HOLDBACK_SECONDS = 0.75RECOVERY_BUFFER_MAX_BYTES = 65_536@@ -120,19 +115,13 @@ class RecoveryController:def advance_failure(self,- error: BaseException,*,+ retryable: bool,stream_opened: bool,generated_output: bool,complete_tool_salvageable: bool,attempts_remaining: int,- retryable_override: bool | None = None,) -> RecoveryDecision:- retryable = (- is_retryable_stream_error(error)- if retryable_override is None- else retryable_override- )committed = self._holdback.committedhas_buffered = self._holdback.has_bufferedretry_available = attempts_remaining > 0@@ -173,28 +162,3 @@ class RecoveryController:committed=committed,has_buffered=has_buffered,)---def is_retryable_stream_error(exc: BaseException) -> bool:- """Return whether one stream failure qualifies for retry or recovery."""- if isinstance(exc, RetryableProviderProtocolError):- return True- if isinstance(exc, ExecutionFailure):- return exc.retryable- if isinstance(exc, openai.AuthenticationError | openai.BadRequestError):- return False- if retryable_transient_status(exc) is not None:- return True- return isinstance(- exc,- (- TimeoutError,- httpx.ReadTimeout,- httpx.ReadError,- httpx.RemoteProtocolError,- httpx.ConnectError,- httpx.NetworkError,- openai.APITimeoutError,- openai.APIConnectionError,- ),- )diff --git a/tests/providers/test_failure_policy.py b/tests/providers/test_failure_policy.pyindex 195a2960..60497b7b 100644--- a/tests/providers/test_failure_policy.py+++ b/tests/providers/test_failure_policy.py@@ -17,8 +17,10 @@ from free_claude_code.providers.failure_policy import (ProviderRecoveryExhausted,classify_provider_failure,is_retryable_provider_error,+ is_retryable_stream_error,retryable_upstream_status,)+from free_claude_code.providers.stream_recovery import TruncatedProviderStreamErrordef _openai_status_error(@@ -55,6 +57,63 @@ def _http_status_error(status_code: int, message: str) -> httpx.HTTPStatusError:return httpx.HTTPStatusError(message, request=request, response=response)+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"))+ assert is_retryable_stream_error(_http_status_error(503, "unavailable"))+ assert not is_retryable_stream_error(_http_status_error(400, "bad request"))+++def test_stream_retry_classification_only_accepts_post_open_timeouts() -> None:+ request = httpx.Request("POST", "https://provider.test/v1/messages")++ assert is_retryable_stream_error(httpx.ReadTimeout("read", request=request))+ assert not is_retryable_stream_error(+ httpx.ConnectTimeout("connect", request=request)+ )+ assert not is_retryable_stream_error(httpx.WriteTimeout("write", request=request))+ assert not is_retryable_stream_error(httpx.PoolTimeout("pool", request=request))+++ ("message", "body"),+ (+ (+ "stream embedded error",+ {"error": {"message": "internal failure", "code": 500}},+ ),+ (+ "stream embedded error",+ {+ "error": {+ "message": "internal failure",+ "type": "internal_server_error",+ }+ },+ ),+ (+ "ResourceExhausted: limit reached while generating response",+ {"error": {"message": "ResourceExhausted: limit reached"}},+ ),+ ),+)+def test_stream_retry_classification_accepts_statusless_transients(+ message: str,+ body: object,+) -> None:+ assert is_retryable_stream_error(_statusless_openai_error(message, body))+++def test_stream_retry_classification_rejects_openai_bad_request() -> None:+ assert not is_retryable_stream_error(+ _openai_status_error(+ openai.BadRequestError,+ status_code=400,+ message="bad request",+ )+ )++@dataclass(frozen=True, slots=True)class _ClassificationCase:name: strdiff --git a/tests/providers/test_stream_recovery.py b/tests/providers/test_stream_recovery.pyindex db194dd7..959d6ab2 100644--- a/tests/providers/test_stream_recovery.py+++ b/tests/providers/test_stream_recovery.py@@ -1,102 +1,18 @@"""Provider stream commit-boundary and recovery policy."""-import httpx-import httpx2-import openai-from free_claude_code.providers.stream_recovery import (RecoveryController,RecoveryFailureAction,RecoveryHoldbackBuffer,- TruncatedProviderStreamError,- is_retryable_stream_error,)-def _statusless_openai_api_error(- message: str, body: object | None = None-) -> openai.APIError:- return openai.APIError(- message,- request=httpx2.Request("POST", "https://provider.test/messages"),- body=body,- )---def test_retryable_stream_error_classifies_protocol_transport_and_status() -> None:- assert is_retryable_stream_error(- TruncatedProviderStreamError("missing terminal marker")- )- assert is_retryable_stream_error(httpx.ReadError("cut off"))-- request = httpx.Request("GET", "https://example.test")- assert is_retryable_stream_error(- httpx.HTTPStatusError(- "server error", request=request, response=httpx.Response(503)- )- )- assert not is_retryable_stream_error(- httpx.HTTPStatusError(- "bad request", request=request, response=httpx.Response(400)- )- )---def test_stream_retry_preserves_timeout_scope() -> None:- request = httpx.Request("POST", "https://provider.test/messages")-- assert is_retryable_stream_error(httpx.ReadTimeout("read", request=request))- assert not is_retryable_stream_error(- httpx.ConnectTimeout("connect", request=request)- )- assert not is_retryable_stream_error(httpx.WriteTimeout("write", request=request))- assert not is_retryable_stream_error(httpx.PoolTimeout("pool", request=request))---def test_retryable_stream_error_classifies_statusless_api_error_body_status() -> None:- assert is_retryable_stream_error(- _statusless_openai_api_error(- "stream embedded error",- {"error": {"message": "internal failure", "code": 500}},- )- )---def test_retryable_stream_error_classifies_statusless_internal_error_type() -> None:- assert is_retryable_stream_error(- _statusless_openai_api_error(- "stream embedded error",- {"error": {"message": "internal failure", "type": "internal_server_error"}},- )- )---def test_retryable_stream_error_classifies_resource_exhausted_text() -> None:- assert is_retryable_stream_error(- _statusless_openai_api_error(- "ResourceExhausted: limit reached while generating response",- {"error": {"message": "ResourceExhausted: limit reached"}},- )- )---def test_retryable_stream_error_does_not_retry_bad_request_status() -> None:- request = httpx2.Request("POST", "https://provider.test/messages")- assert not is_retryable_stream_error(- openai.BadRequestError(- "bad request",- response=httpx2.Response(400, request=request),- body={"error": {"message": "bad request"}},- )- )--def test_early_retry_discards_uncommitted_holdback() -> None:controller = RecoveryController()assert controller.push("hidden") == []decision = controller.advance_failure(- httpx.ReadError("early cutoff"),+ retryable=True,stream_opened=True,generated_output=True,complete_tool_salvageable=False,@@ -116,7 +32,7 @@ def test_early_retry_requires_remaining_execution_budget() -> None:assert controller.push("hidden") == []decision = controller.advance_failure(- httpx.ReadError("early cutoff"),+ retryable=True,stream_opened=True,generated_output=True,complete_tool_salvageable=False,@@ -133,7 +49,7 @@ def test_last_attempt_is_reserved_for_partial_output_recovery() -> None:assert controller.push("partial") == []decision = controller.advance_failure(- httpx.ReadError("early cutoff"),+ retryable=True,stream_opened=True,generated_output=True,complete_tool_salvageable=False,@@ -147,7 +63,7 @@ def test_last_attempt_is_reserved_for_partial_output_recovery() -> None:def test_create_failure_is_owned_by_admission_not_stream_recovery() -> None:decision = RecoveryController().advance_failure(- httpx.ConnectError("connect failed"),+ retryable=True,stream_opened=False,generated_output=False,complete_tool_salvageable=False,@@ -160,10 +76,7 @@ def test_create_failure_is_owned_by_admission_not_stream_recovery() -> None:def test_statusless_transient_api_error_allows_early_retry() -> None:decision = RecoveryController().advance_failure(- _statusless_openai_api_error(- "ResourceExhausted: limit reached while generating response",- {"error": {"message": "ResourceExhausted: limit reached"}},- ),+ retryable=True,stream_opened=True,generated_output=False,complete_tool_salvageable=False,@@ -180,7 +93,7 @@ def test_committed_output_allows_midstream_recovery() -> None:assert controller.push("event: content_block_delta\n\n") == []assert controller.flush() == ["event: content_block_delta\n\n"]decision = controller.advance_failure(- httpx.ReadError("midstream cutoff"),+ retryable=True,stream_opened=True,generated_output=True,complete_tool_salvageable=False,@@ -198,7 +111,7 @@ def test_uncommitted_complete_tool_can_be_salvaged() -> None:assert controller.push("event: content_block_delta\n\n") == []decision = controller.advance_failure(- httpx.ReadError("midstream cutoff"),+ retryable=True,stream_opened=True,generated_output=True,complete_tool_salvageable=True,@@ -214,15 +127,8 @@ def test_uncommitted_complete_tool_can_be_salvaged() -> None:def test_non_retryable_error_is_final() -> None:- request = httpx.Request("POST", "https://example.test/messages")- error = httpx.HTTPStatusError(- "bad request",- request=request,- response=httpx.Response(400, request=request),- )-decision = RecoveryController().advance_failure(- error,+ retryable=False,stream_opened=True,generated_output=True,complete_tool_salvageable=False,diff --git a/uv.lock b/uv.lockindex eefb9276..14c75d5d 100644--- a/uv.lock+++ b/uv.lock@@ -607,7 +607,7 @@ wheels = [[[package]]name = "free-claude-code"-version = "5.13.0"+version = "5.13.1"source = { editable = "." }dependencies = [{ name = "aiohttp" },