Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

Extract shared stream recovery session for provider transports (#835)

Ali Khokhare2fa4b66d944
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 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 small
helpers.
- [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, tree
queueing, CLI session execution, transcript updates, and persistence
coordination. 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.py
new file mode 100644
index 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.py
index 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_text
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,
@@ -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_event
from providers.base import BaseProvider, ProviderConfig
from providers.error_mapping import (
@@ -564,10 +565,12 @@ class AnthropicMessagesTransport(BaseProvider):
sent_any_event = False
state = 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 = 0
while True:
stream_opened = False
try:
@@ -587,7 +590,7 @@ class AnthropicMessagesTransport(BaseProvider):
chunk_count += 1
chunk_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 = True
yield 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 = True
yield event
return
except Exception as error:
- committed = holdback.committed
generated_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 = None
if 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 event
for event in recovery_events:
yield event
return
@@ -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 = True
yield event
for event in emitted_tracker.iter_close_unclosed_blocks():
@@ -712,7 +704,7 @@ class AnthropicMessagesTransport(BaseProvider):
):
yield event
else:
- 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.py
index 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_event
from providers.base import BaseProvider, ProviderConfig
from 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 = 0
while True:
stream_opened = False
try:
@@ -783,23 +786,19 @@ class OpenAIChatTransport(BaseProvider):
except asyncio.CancelledError, GeneratorExit:
raise
except Exception as e:
- committed = holdback.committed
generated_output = self._has_committed_sse_output(sse)
complete_tool_salvageable = (
generated_output
and 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 = None
tool_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 = None
if recovery_events is not None:
- if not committed:
- for event in holdback.flush():
- yield event
+ for event in recovery_session.flush_uncommitted(decision):
+ yield event
for event in recovery_events:
yield event
return
@@ -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 event
for event in hold_event(sse.message_stop()):
yield event
- for event in holdback.flush():
+ for event in recovery_session.flush():
yield event
diff --git a/pyproject.toml b/pyproject.toml
index 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.py
index 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.py
index 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 parsed
if 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.py
index 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 parsed
if 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.lock
index 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" },