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
Extract shared stream recovery session for provider transports (#835)
Ali Khokhare2fa4b66d944
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.mdindex 65e7a1df..6a3c63c7 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -78,10 +78,10 @@ new places to add unrelated behavior:should keep route handlers thin and move separable use-case logic behind smallhelpers.- [providers/openai_compat.py](providers/openai_compat.py) and- [providers/anthropic_messages.py](providers/anthropic_messages.py) own shared- transport behavior plus retry, recovery, stream translation, and error- handling. Shared protocol rules should continue moving toward [core/](core/)- when they are not provider-specific.+ [providers/anthropic_messages.py](providers/anthropic_messages.py) still own+ provider-specific stream parsing, request construction, and recovery event+ construction. Shared protocol rules should continue moving toward+ [core/](core/) when they are not provider-specific.- [messaging/handler.py](messaging/handler.py) owns command dispatch, treequeueing, CLI session execution, transcript updates, and persistencecoordination. New platform-specific behavior should stay in platform or@@ -306,9 +306,18 @@ where supported, and returning Anthropic SSE strings to the service layer.- thinking block handling;- SSE event formatting through `SSEBuilder`;- native Anthropic stream policy;-- stream recovery and repair helpers;+- stream recovery policy, holdback, continuation, and repair helpers;- token counting and user-facing error formatting.+Shared stream recovery policy lives in+[core/anthropic/stream_recovery_session.py](core/anthropic/stream_recovery_session.py)+and [core/anthropic/stream_recovery.py](core/anthropic/stream_recovery.py). The+shared layer owns early retry classification, holdback buffering, retry attempt+counting, and common flush/discard behavior. Provider transports still own+upstream request construction, stream semantic parsing, transport-specific state+tracking, and the actual recovery SSE events emitted for OpenAI-chat or native+Anthropic streams.+[core/openai_responses/](core/openai_responses/) owns OpenAI Responses support:- Responses request conversion into Anthropic Messages payloads;diff --git a/core/anthropic/stream_recovery_session.py b/core/anthropic/stream_recovery_session.pynew file mode 100644index 00000000..7cbf2dcc--- /dev/null+++ b/core/anthropic/stream_recovery_session.py@@ -0,0 +1,133 @@+"""Shared stream recovery policy for provider transports."""++from __future__ import annotations++from dataclasses import dataclass+from enum import StrEnum++from core.anthropic.stream_recovery import (+ EARLY_TRANSPARENT_MAX_RETRIES,+ EARLY_TRANSPARENT_TOTAL_ATTEMPTS,+ RecoveryHoldbackBuffer,+ is_retryable_stream_error,+)+from core.trace import trace_event+++class StreamFailureAction(StrEnum):+ """Transport action selected after a provider stream failure."""++ EARLY_RETRY = "early_retry"+ MIDSTREAM_RECOVERY = "midstream_recovery"+ FINAL_ERROR = "final_error"+++@dataclass(frozen=True, slots=True)+class StreamFailureDecision:+ """Failure-state snapshot for the current provider stream transition."""++ action: StreamFailureAction+ retryable: bool+ committed: bool+ has_buffered: bool+ early_retry_attempt: int | None = None+++class StreamRecoverySession:+ """Own holdback and retry policy shared by provider stream transports."""++ def __init__(self, *, provider_name: str, request_id: str | None) -> None:+ self._provider_name = provider_name+ self._request_id = request_id+ self._holdback = RecoveryHoldbackBuffer()+ self._early_retries = 0++ @property+ def committed(self) -> bool:+ return self._holdback.committed++ @property+ def has_buffered(self) -> bool:+ return self._holdback.has_buffered++ @property+ def early_retries(self) -> int:+ return self._early_retries++ def push(self, event: str) -> list[str]:+ """Buffer one downstream event through the early retry holdback."""+ return self._holdback.push(event)++ def flush(self) -> list[str]:+ """Commit and return held events."""+ return self._holdback.flush()++ def flush_uncommitted(self, decision: StreamFailureDecision) -> list[str]:+ """Commit held events when the decision snapshot is still uncommitted."""+ if decision.committed:+ return []+ return self.flush()++ def discard(self) -> None:+ """Drop held events without committing them."""+ self._holdback.discard()++ def advance_failure(+ self,+ error: BaseException,+ *,+ stream_opened: bool,+ generated_output: bool,+ complete_tool_salvageable: bool,+ ) -> StreamFailureDecision:+ """Consume a stream failure and apply shared recovery state changes."""+ committed = self.committed+ has_buffered = self.has_buffered+ retryable = is_retryable_stream_error(error)++ if (+ not committed+ and stream_opened+ and retryable+ and not complete_tool_salvageable+ and self._early_retries < EARLY_TRANSPARENT_MAX_RETRIES+ ):+ self._early_retries += 1+ attempt = self._early_retries+ self._reset_holdback()+ trace_event(+ stage="provider",+ event="provider.recovery.early_retry",+ source="provider",+ provider=self._provider_name,+ request_id=self._request_id,+ attempt=attempt,+ max_attempts=EARLY_TRANSPARENT_TOTAL_ATTEMPTS,+ exc_type=type(error).__name__,+ )+ return StreamFailureDecision(+ action=StreamFailureAction.EARLY_RETRY,+ retryable=retryable,+ committed=committed,+ has_buffered=has_buffered,+ early_retry_attempt=attempt,+ )++ if generated_output and retryable:+ return StreamFailureDecision(+ action=StreamFailureAction.MIDSTREAM_RECOVERY,+ retryable=retryable,+ committed=committed,+ has_buffered=has_buffered,+ )++ return StreamFailureDecision(+ action=StreamFailureAction.FINAL_ERROR,+ retryable=retryable,+ committed=committed,+ has_buffered=has_buffered,+ )++ def _reset_holdback(self) -> None:+ self._holdback.discard()+ self._holdback = RecoveryHoldbackBuffer()diff --git a/providers/anthropic_messages.py b/providers/anthropic_messages.pyindex 59aaef0c..65d13264 100644--- a/providers/anthropic_messages.py+++ b/providers/anthropic_messages.py@@ -25,10 +25,7 @@ from core.anthropic.native_sse_block_policy import ()from core.anthropic.stream_contracts import parse_sse_textfrom core.anthropic.stream_recovery import (- EARLY_TRANSPARENT_MAX_RETRIES,- EARLY_TRANSPARENT_TOTAL_ATTEMPTS,MIDSTREAM_RECOVERY_ATTEMPTS,- RecoveryHoldbackBuffer,TruncatedProviderStreamError,accept_tool_json_repair,continuation_suffix,@@ -38,6 +35,10 @@ from core.anthropic.stream_recovery import (parse_complete_tool_input,tool_schemas_by_name,)+from core.anthropic.stream_recovery_session import (+ StreamFailureAction,+ StreamRecoverySession,+)from core.trace import provider_native_messages_body_snapshot, trace_eventfrom providers.base import BaseProvider, ProviderConfigfrom providers.error_mapping import (@@ -564,10 +565,12 @@ class AnthropicMessagesTransport(BaseProvider):sent_any_event = Falsestate = self._new_stream_state(request, thinking_enabled=thinking_enabled)emitted_tracker = EmittedNativeSseTracker()- holdback = RecoveryHoldbackBuffer()+ recovery_session = StreamRecoverySession(+ provider_name=self._provider_name,+ request_id=request_id,+ )async with self._global_rate_limiter.concurrency_slot():- early_retries = 0while True:stream_opened = Falsetry:@@ -587,7 +590,7 @@ class AnthropicMessagesTransport(BaseProvider):chunk_count += 1chunk_bytes += len(chunk.encode("utf-8", errors="replace"))emitted_tracker.feed(chunk)- for event in holdback.push(chunk):+ for event in recovery_session.push(chunk):sent_any_event = Trueyield event@@ -605,13 +608,12 @@ class AnthropicMessagesTransport(BaseProvider):sse_chunks_out=chunk_count,sse_bytes_out=chunk_bytes,)- for event in holdback.flush():+ for event in recovery_session.flush():sent_any_event = Trueyield eventreturnexcept Exception as error:- committed = holdback.committedgenerated_output = emitted_tracker.has_content_block()complete_tool_salvageable = (generated_output@@ -619,16 +621,13 @@ class AnthropicMessagesTransport(BaseProvider):tool_schemas_by_name(request)))- if (- not committed- and stream_opened- and is_retryable_stream_error(error)- and not complete_tool_salvageable- and early_retries < EARLY_TRANSPARENT_MAX_RETRIES- ):- early_retries += 1- holdback.discard()- holdback = RecoveryHoldbackBuffer()+ decision = recovery_session.advance_failure(+ error,+ stream_opened=stream_opened,+ generated_output=generated_output,+ complete_tool_salvageable=complete_tool_salvageable,+ )+ if decision.action == StreamFailureAction.EARLY_RETRY:if response is not None and not response.is_closed:await _maybe_await_aclose(response)response = None@@ -637,19 +636,9 @@ class AnthropicMessagesTransport(BaseProvider):)emitted_tracker = EmittedNativeSseTracker()sent_any_event = False- trace_event(- stage="provider",- event="provider.recovery.early_retry",- source="provider",- provider=self._provider_name,- request_id=request_id,- attempt=early_retries,- max_attempts=EARLY_TRANSPARENT_TOTAL_ATTEMPTS,- exc_type=type(error).__name__,- )continue- if generated_output and is_retryable_stream_error(error):+ if decision.action == StreamFailureAction.MIDSTREAM_RECOVERY:try:recovery_events = await self._native_recovery_events(body=body,@@ -671,10 +660,9 @@ class AnthropicMessagesTransport(BaseProvider):)recovery_events = Noneif recovery_events is not None:- if not committed:- for event in holdback.flush():- sent_any_event = True- yield event+ for event in recovery_session.flush_uncommitted(decision):+ sent_any_event = True+ yield eventfor event in recovery_events:yield eventreturn@@ -695,11 +683,15 @@ class AnthropicMessagesTransport(BaseProvider):provider=self._provider_name,error_message=error_message,exc_type=type(error).__name__,- mid_stream=sent_any_event or committed or holdback.has_buffered,+ mid_stream=(+ sent_any_event+ or decision.committed+ or decision.has_buffered+ ),)- if committed or holdback.has_buffered:- if not committed:- for event in holdback.flush():+ if decision.committed or decision.has_buffered:+ if not decision.committed:+ for event in recovery_session.flush():sent_any_event = Trueyield eventfor event in emitted_tracker.iter_close_unclosed_blocks():@@ -712,7 +704,7 @@ class AnthropicMessagesTransport(BaseProvider):):yield eventelse:- holdback.discard()+ recovery_session.discard()for event in self._emit_error_events(request=request,input_tokens=input_tokens,diff --git a/providers/openai_compat.py b/providers/openai_compat.pyindex 258262e6..eef02efa 100644--- a/providers/openai_compat.py+++ b/providers/openai_compat.py@@ -23,10 +23,7 @@ from core.anthropic import (map_stop_reason,)from core.anthropic.stream_recovery import (- EARLY_TRANSPARENT_MAX_RETRIES,- EARLY_TRANSPARENT_TOTAL_ATTEMPTS,MIDSTREAM_RECOVERY_ATTEMPTS,- RecoveryHoldbackBuffer,TruncatedProviderStreamError,accept_tool_json_repair,continuation_suffix,@@ -36,6 +33,10 @@ from core.anthropic.stream_recovery import (parse_complete_tool_input,tool_schemas_by_name,)+from core.anthropic.stream_recovery_session import (+ StreamFailureAction,+ StreamRecoverySession,+)from core.trace import provider_chat_body_snapshot, trace_eventfrom providers.base import BaseProvider, ProviderConfigfrom providers.error_mapping import (@@ -638,10 +639,13 @@ class OpenAIChatTransport(BaseProvider):)sse = new_sse_builder()- holdback = RecoveryHoldbackBuffer()+ recovery_session = StreamRecoverySession(+ provider_name=tag,+ request_id=request_id,+ )def hold_event(event: str) -> Iterator[str]:- yield from holdback.push(event)+ yield from recovery_session.push(event)def hold_events(events: Iterator[str]) -> Iterator[str]:for event in events:@@ -672,7 +676,6 @@ class OpenAIChatTransport(BaseProvider):tool_argument_alias_buffers: dict[int, str] = {}async with self._global_rate_limiter.concurrency_slot():- early_retries = 0while True:stream_opened = Falsetry:@@ -783,23 +786,19 @@ class OpenAIChatTransport(BaseProvider):except asyncio.CancelledError, GeneratorExit:raiseexcept Exception as e:- committed = holdback.committedgenerated_output = self._has_committed_sse_output(sse)complete_tool_salvageable = (generated_outputand sse.blocks.has_emitted_tool_block()and self._all_started_tools_complete(sse, request))- if (- not committed- and stream_opened- and is_retryable_stream_error(e)- and not complete_tool_salvageable- and early_retries < EARLY_TRANSPARENT_MAX_RETRIES- ):- early_retries += 1- holdback.discard()- holdback = RecoveryHoldbackBuffer()+ decision = recovery_session.advance_failure(+ e,+ stream_opened=stream_opened,+ generated_output=generated_output,+ complete_tool_salvageable=complete_tool_salvageable,+ )+ if decision.action == StreamFailureAction.EARLY_RETRY:sse = new_sse_builder()think_parser = ThinkTagParser()heuristic_parser = HeuristicToolParser()@@ -807,19 +806,9 @@ class OpenAIChatTransport(BaseProvider):usage_info = Nonetool_argument_aliases = {}tool_argument_alias_buffers = {}- trace_event(- stage="provider",- event="provider.recovery.early_retry",- source="provider",- provider=tag,- request_id=request_id,- attempt=early_retries,- max_attempts=EARLY_TRANSPARENT_TOTAL_ATTEMPTS,- exc_type=type(e).__name__,- )continue- if generated_output and is_retryable_stream_error(e):+ if decision.action == StreamFailureAction.MIDSTREAM_RECOVERY:try:recovery_events = await self._openai_recovery_events(body=body,@@ -840,9 +829,8 @@ class OpenAIChatTransport(BaseProvider):)recovery_events = Noneif recovery_events is not None:- if not committed:- for event in holdback.flush():- yield event+ for event in recovery_session.flush_uncommitted(decision):+ yield eventfor event in recovery_events:yield eventreturn@@ -861,11 +849,11 @@ class OpenAIChatTransport(BaseProvider):map_error(e, rate_limiter=self._global_rate_limiter)).__name__,)- if not committed and holdback.has_buffered:- for event in holdback.flush():+ if not decision.committed and decision.has_buffered:+ for event in recovery_session.flush():yield event- elif not committed:- holdback.discard()+ elif not decision.committed:+ recovery_session.discard()sse = new_sse_builder()for event in self._emit_openai_error_tail(sse, error_message):yield event@@ -963,5 +951,5 @@ class OpenAIChatTransport(BaseProvider):yield eventfor event in hold_event(sse.message_stop()):yield event- for event in holdback.flush():+ for event in recovery_session.flush():yield eventdiff --git a/pyproject.toml b/pyproject.tomlindex a9fea79d..675a0b6b 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "free-claude-code"-version = "2.2.0"+version = "2.2.1"description = "Middleware between Claude Code CLI (Anthropic API) and NVIDIA NIM"readme = "README.md"requires-python = ">=3.14.0"diff --git a/tests/core/anthropic/test_stream_recovery.py b/tests/core/anthropic/test_stream_recovery.pyindex b1f940f0..49dbe968 100644--- a/tests/core/anthropic/test_stream_recovery.py+++ b/tests/core/anthropic/test_stream_recovery.py@@ -12,6 +12,10 @@ from core.anthropic.stream_recovery import (continuation_suffix,is_retryable_stream_error,)+from core.anthropic.stream_recovery_session import (+ StreamFailureAction,+ StreamRecoverySession,+)def test_early_transparent_retry_total_attempts_is_five() -> None:@@ -39,6 +43,112 @@ def test_retryable_stream_error_classifies_transport_and_http_status() -> None:)+def test_stream_recovery_session_advances_early_retry_and_discards_holdback() -> None:+ session = StreamRecoverySession(provider_name="TEST", request_id="REQ")++ assert session.push("hidden") == []+ decision = session.advance_failure(+ httpx.ReadError("early cutoff"),+ stream_opened=True,+ generated_output=True,+ complete_tool_salvageable=False,+ )++ assert decision.action == StreamFailureAction.EARLY_RETRY+ assert decision.early_retry_attempt == 1+ assert session.early_retries == 1+ assert not session.committed+ assert not session.has_buffered+ assert session.flush() == []+++def test_stream_recovery_session_respects_early_retry_limit() -> None:+ session = StreamRecoverySession(provider_name="TEST", request_id=None)++ for attempt in range(1, EARLY_TRANSPARENT_MAX_RETRIES + 1):+ decision = session.advance_failure(+ httpx.ReadError("cutoff"),+ stream_opened=True,+ generated_output=False,+ complete_tool_salvageable=False,+ )+ assert decision.action == StreamFailureAction.EARLY_RETRY+ assert decision.early_retry_attempt == attempt++ decision = session.advance_failure(+ httpx.ReadError("cutoff"),+ stream_opened=True,+ generated_output=False,+ complete_tool_salvageable=False,+ )++ assert decision.action == StreamFailureAction.FINAL_ERROR+ assert session.early_retries == EARLY_TRANSPARENT_MAX_RETRIES+++def test_stream_recovery_session_classifies_midstream_recovery_after_commit() -> None:+ session = StreamRecoverySession(provider_name="TEST", request_id=None)++ assert session.push("event: content_block_delta\n\n") == []+ assert session.flush() == ["event: content_block_delta\n\n"]+ decision = session.advance_failure(+ httpx.ReadError("midstream cutoff"),+ stream_opened=True,+ generated_output=True,+ complete_tool_salvageable=False,+ )++ assert decision.action == StreamFailureAction.MIDSTREAM_RECOVERY+ assert decision.retryable+ assert decision.committed+ assert session.flush_uncommitted(decision) == []+++def test_stream_recovery_session_flushes_uncommitted_midstream_decision() -> None:+ session = StreamRecoverySession(provider_name="TEST", request_id=None)++ assert session.push("event: content_block_delta\n\n") == []+ decision = session.advance_failure(+ httpx.ReadError("midstream cutoff"),+ stream_opened=True,+ generated_output=True,+ complete_tool_salvageable=True,+ )++ assert decision.action == StreamFailureAction.MIDSTREAM_RECOVERY+ assert not decision.committed+ assert decision.has_buffered+ assert not session.committed+ assert session.has_buffered++ assert session.flush_uncommitted(decision) == ["event: content_block_delta\n\n"]+ assert not decision.committed+ assert decision.has_buffered+ assert session.committed+ assert not session.has_buffered+++def test_stream_recovery_session_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),+ )+ session = StreamRecoverySession(provider_name="TEST", request_id=None)++ decision = session.advance_failure(+ error,+ stream_opened=True,+ generated_output=True,+ complete_tool_salvageable=False,+ )++ assert decision.action == StreamFailureAction.FINAL_ERROR+ assert not decision.retryable+ assert session.early_retries == 0++def test_continuation_suffix_trims_overlap() -> None:assert continuation_suffix("hello wor", "world") == "ld"assert continuation_suffix("alpha", "alpha beta") == " beta"diff --git a/tests/providers/test_anthropic_messages.py b/tests/providers/test_anthropic_messages.pyindex f2c5580f..4bce4b71 100644--- a/tests/providers/test_anthropic_messages.py+++ b/tests/providers/test_anthropic_messages.py@@ -442,12 +442,13 @@ async def test_clean_eof_after_native_text_continues_with_overlap_trim(events = [e async for e in provider.stream_response(req)]parsed = parse_sse_text("".join(events))- text = "".join(+ text_deltas = [event.data.get("delta", {}).get("text", "")for event in parsedif event.event == "content_block_delta"- )- assert text == "hello world"+ ]+ assert text_deltas == ["hello wor", "ld"]+ assert "".join(text_deltas) == "hello world"assert any(event.event == "message_delta"and event.data.get("delta", {}).get("stop_reason") == "end_turn"diff --git a/tests/providers/test_streaming_errors.py b/tests/providers/test_streaming_errors.pyindex fcf513e8..7e7573cf 100644--- a/tests/providers/test_streaming_errors.py+++ b/tests/providers/test_streaming_errors.py@@ -681,12 +681,13 @@ class TestStreamingExceptionHandling:events = await _collect_stream(provider, request)parsed = parse_sse_text("".join(events))- text = "".join(+ text_deltas = [event.data.get("delta", {}).get("text", "")for event in parsedif event.event == "content_block_delta"- )- assert text == "hello world"+ ]+ assert text_deltas == ["hello wor", "ld"]+ assert "".join(text_deltas) == "hello world"assert any(event.event == "message_delta"and event.data.get("delta", {}).get("stop_reason") == "end_turn"diff --git a/uv.lock b/uv.lockindex b149199d..40750114 100644--- a/uv.lock+++ b/uv.lock@@ -561,7 +561,7 @@ wheels = [[[package]]name = "free-claude-code"-version = "2.2.0"+version = "2.2.1"source = { editable = "." }dependencies = [{ name = "aiohttp" },