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

minor: continue interrupted responses across fallback models (#1994)

Ali Khokhar3816a8a59427
diff --git a/e2e/conftest.py b/e2e/conftest.py
index 9072f422..ea4cfa36 100644
--- a/e2e/conftest.py
+++ b/e2e/conftest.py
@@ -102,6 +102,7 @@ class _ModelListingProvider(BaseProvider):
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation=None,
) -> AsyncIterator[str]:
if False:
yield ""
@@ -116,6 +117,7 @@ class _ModelListingProvider(BaseProvider):
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation=None,
) -> AsyncIterator[str]:
if False:
yield ""
diff --git a/src/free_claude_code/api/stream_delivery.py b/src/free_claude_code/api/stream_delivery.py
index 7eabd9aa..96d860b1 100644
--- a/src/free_claude_code/api/stream_delivery.py
+++ b/src/free_claude_code/api/stream_delivery.py
@@ -105,7 +105,6 @@ class PublicResponseStream(AsyncIterator[str]):
except (Exception, BaseExceptionGroup) as exc:
self._done = True
self._pending_starts.clear()
- self._tools = ToolCallBuffer(self._wire_api)
failure = find_execution_failure(exc) or exc
if self._terminal_frame is None:
raise
@@ -114,6 +113,9 @@ class PublicResponseStream(AsyncIterator[str]):
frame = self._terminal_frame(
self.start_frame or self._initial_chunk, self._latest_chunk, failure
)
+ # Filter with the failing attempt's call identities before discarding it.
+ (frame,) = self._tools.feed(frame)
+ self._tools = ToolCallBuffer(self._wire_api)
frame = self._finalize_frame(frame)
return self._publish(frame, synthetic=True) or frame
@@ -262,7 +264,7 @@ class PublicResponseStream(AsyncIterator[str]):
self._delivered.unsafe_reason = "unknown_event"
def _publish(self, frame: str, *, synthetic: bool = False) -> str | None:
- """Normalize only a replacement envelope and mark actually released frames."""
+ """Keep replacement and failure envelopes in the public response lifecycle."""
payload = frame_data(frame)
if payload is None:
if any(
@@ -298,7 +300,8 @@ class PublicResponseStream(AsyncIterator[str]):
self._created_at = value.get("created_at")
changed = False
- if self._replacement and self._wire_api == "responses":
+ failure = kind == "response.failed"
+ if (self._replacement or failure) and self._wire_api == "responses":
response = payload.get("response")
if isinstance(response, dict):
if (
@@ -321,8 +324,12 @@ class PublicResponseStream(AsyncIterator[str]):
payload["response_id"] = self._public_id
changed = True
number = payload.get("sequence_number")
+ if failure:
+ number = self._sequence + 1
+ payload["sequence_number"] = number
+ changed = True
if isinstance(number, int) and not isinstance(number, bool):
- if self._replacement:
+ if self._replacement and not failure:
if self._offset is None:
self._offset = max(0, self._sequence + 1 - number)
if self._offset:
diff --git a/src/free_claude_code/api/tool_call_buffer.py b/src/free_claude_code/api/tool_call_buffer.py
index 053a9d3e..f6f84725 100644
--- a/src/free_claude_code/api/tool_call_buffer.py
+++ b/src/free_claude_code/api/tool_call_buffer.py
@@ -66,7 +66,7 @@ class ToolCallBuffer:
kind = event.event or data.get("type")
if kind in _FAILURES:
self._discard_group()
- return [self._filter_snapshot(frame)]
+ return [self._filter_snapshot(frame, failed=True)]
if self._wire_api == "messages":
index = data.get("index")
block = data.get("content_block")
@@ -158,7 +158,7 @@ class ToolCallBuffer:
self._calls.clear()
self._pending.clear()
- def _filter_snapshot(self, frame: str) -> str:
+ def _filter_snapshot(self, frame: str, *, failed: bool = False) -> str:
# Parse only frames we may edit using decimal-aware JSON; all other
# payloads, including argument strings and SSE framing, stay verbatim.
value = frame_data(frame)
@@ -176,7 +176,7 @@ class ToolCallBuffer:
if not (
isinstance(item, Mapping)
and _client_call(item)
- and (self._withheld_item(item, response.get("status")))
+ and self._withheld_item(item, response.get("status"), failed=failed)
)
]
if len(retained) == len(output):
@@ -185,13 +185,18 @@ class ToolCallBuffer:
return replace_frame_data(frame, value)
def _withheld_item(
- self, item: Mapping[str, object], response_status: object
+ self,
+ item: Mapping[str, object],
+ response_status: object,
+ *,
+ failed: bool = False,
) -> bool:
key = self._key({}, item)
status = item.get("status")
return (
key in self._discarded
or status in _UNFINISHED
+ or (failed and key not in self._delivered)
or (
status is None
and response_status != "completed"
diff --git a/src/free_claude_code/application/execution.py b/src/free_claude_code/application/execution.py
index d6c22c66..cccb2a74 100644
--- a/src/free_claude_code/application/execution.py
+++ b/src/free_claude_code/application/execution.py
@@ -22,6 +22,12 @@ from free_claude_code.core.openai_responses import (
)
from free_claude_code.core.reasoning import ReasoningPolicy
from free_claude_code.core.request_outcomes import record_request_route
+from free_claude_code.core.stream_delivery import current_stream_delivery
+from free_claude_code.core.stream_recovery import (
+ ContinuationSeed,
+ RecoveryAction,
+ assess_recovery,
+)
from free_claude_code.core.trace import (
close_stream_input,
trace_event,
@@ -40,7 +46,7 @@ from .routing import (
ResponsesTokenCounter = Callable[[OpenAIResponsesRequest], int]
WireApi = Literal["messages", "responses"]
CandidateStreamOpener = Callable[
- [int, ProviderModelTarget], Awaitable[AsyncIterator[str]]
+ [int, ProviderModelTarget, ContinuationSeed | None], Awaitable[AsyncIterator[str]]
]
@@ -105,6 +111,8 @@ class ProviderExecutor:
failure: ExecutionFailure,
candidate_index: int,
candidate_count: int,
+ recovery_action: str,
+ recovery_reason: str | None,
) -> None:
fields: dict[str, object] = {
"stage": "execution",
@@ -119,6 +127,8 @@ class ProviderExecutor:
"failure_kind": failure.kind.value,
"status_code": failure.status_code,
"provider_retryable": failure.retryable,
+ "recovery_action": recovery_action,
+ "recovery_reason": recovery_reason,
}
if self._generation_id is not None:
fields["generation_id"] = self._generation_id
@@ -165,7 +175,9 @@ class ProviderExecutor:
request_id: str,
) -> AsyncIterator[str]:
async def open_candidate(
- index: int, target: ProviderModelTarget
+ index: int,
+ target: ProviderModelTarget,
+ continuation: ContinuationSeed | None,
) -> AsyncIterator[str]:
provider = await self._provider_resolver(target.provider_id)
return provider.stream_native_messages(
@@ -173,6 +185,7 @@ class ProviderExecutor:
request_id=request_id,
response_model=routed.resolved.original_model,
request_headers=self._request_headers,
+ continuation=continuation,
)
messages = routed.request.body["messages"]
@@ -213,6 +226,7 @@ class ProviderExecutor:
async def open_candidate(
index: int,
target: ProviderModelTarget,
+ continuation: ContinuationSeed | None,
) -> AsyncIterator[str]:
provider = await self._provider_resolver(target.provider_id)
request = (
@@ -233,6 +247,7 @@ class ProviderExecutor:
target.provider_id, target.provider_model
),
request_headers=self._request_headers,
+ continuation=continuation,
)
return self._stream_candidates(
@@ -263,6 +278,7 @@ class ProviderExecutor:
async def open_candidate(
index: int,
target: ProviderModelTarget,
+ continuation: ContinuationSeed | None,
) -> AsyncIterator[str]:
provider = await self._provider_resolver(target.provider_id)
request = (
@@ -280,6 +296,7 @@ class ProviderExecutor:
response_model=routed.resolved.original_model,
reasoning=routed.reasoning,
request_headers=self._request_headers,
+ continuation=continuation,
model_info=self._model_info_lookup(
target.provider_id, target.provider_model
),
@@ -373,6 +390,8 @@ class ProviderExecutor:
async def provider_body() -> AsyncIterator[str]:
loop = asyncio.get_running_loop()
progress_deadline = loop.time() + self._progress_timeout_seconds
+ delivery = current_stream_delivery()
+ continuation: ContinuationSeed | None = None
for index, target in enumerate(candidates):
record_request_route(target.provider_id, target.provider_model)
provider_stream: AsyncIterator[str] | None = None
@@ -381,7 +400,9 @@ class ProviderExecutor:
try:
opening_started = monotonic()
try:
- provider_stream = await open_candidate(index, target)
+ provider_stream = await open_candidate(
+ index, target, continuation
+ )
except ExecutionFailure as failure:
candidate_failure = failure
finally:
@@ -464,8 +485,31 @@ class ProviderExecutor:
if candidate_failure is None:
return
- if candidate_committed or index + 1 >= len(candidates):
+ recovery_action = "continue" if continuation is not None else "restart"
+ recovery_reason = "no_candidate_output"
+ context = candidate_failure.stream_context
+ if delivery is None or context is None:
+ if candidate_committed:
+ raise candidate_failure
+ else:
+ assessment = assess_recovery(
+ content_released=delivery.content_released,
+ prefix=delivery.prefix,
+ source=context.source,
+ retryable=candidate_failure.retryable,
+ )
+ if assessment.action is RecoveryAction.STOP:
+ raise candidate_failure
+ if assessment.action is RecoveryAction.HANDOFF:
+ delivery.begin_continuation(handoff=True)
+ return
+ continuation = assessment.seed
+ recovery_action = assessment.action.value
+ recovery_reason = assessment.reason
+ if index + 1 >= len(candidates):
raise candidate_failure
+ if delivery is not None and continuation is not None:
+ delivery.begin_continuation()
next_target = candidates[index + 1]
self._trace_fallback_started(
request_id=request_id,
@@ -475,6 +519,8 @@ class ProviderExecutor:
failure=candidate_failure,
candidate_index=index + 2,
candidate_count=len(candidates),
+ recovery_action=recovery_action,
+ recovery_reason=recovery_reason,
)
stream_trace: dict[str, object] = {
diff --git a/src/free_claude_code/application/ports.py b/src/free_claude_code/application/ports.py
index 15376c78..4b68ac4a 100644
--- a/src/free_claude_code/application/ports.py
+++ b/src/free_claude_code/application/ports.py
@@ -10,6 +10,7 @@ from free_claude_code.core.anthropic.passthrough import NativeMessagesRequest
from free_claude_code.core.json_types import JsonObject
from free_claude_code.core.openai_responses import OpenAIResponsesRequest
from free_claude_code.core.reasoning import ReasoningPolicy
+from free_claude_code.core.stream_recovery import ContinuationSeed
from .model_metadata import ProviderModelInfo
@@ -24,6 +25,7 @@ class ProviderPort(Protocol):
request_id: str,
response_model: str,
request_headers: Mapping[str, str] | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]: ...
def stream_messages(
@@ -36,6 +38,7 @@ class ProviderPort(Protocol):
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]: ...
def stream_responses(
@@ -48,6 +51,7 @@ class ProviderPort(Protocol):
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]: ...
diff --git a/src/free_claude_code/core/delivered_response.py b/src/free_claude_code/core/delivered_response.py
index e210c30a..0a7f777a 100644
--- a/src/free_claude_code/core/delivered_response.py
+++ b/src/free_claude_code/core/delivered_response.py
@@ -1,7 +1,6 @@
"""Bounded, request-local evidence of output released to a stream consumer."""
from copy import deepcopy
-from dataclasses import dataclass
from typing import Any, Literal
import simplejson
@@ -13,6 +12,7 @@ from .history_replay import (
unencrypted_responses_replay,
)
from .openai_responses import is_client_search
+from .stream_recovery import DeliveredPrefix
from .token_estimation import estimate_text_tokens
RECOVERY_RETENTION_BYTES = 1_048_576
@@ -67,16 +67,6 @@ def responses_text_constraint(data: dict[str, Any]) -> str | None:
return None
-@dataclass(frozen=True, slots=True)
-class DeliveredPrefix:
- text: str
- thinking: str
- has_calls: bool
- eligible: bool
- can_handoff: bool
- unsafe_reason: str | None
-
-
class DeliveredResponse:
"""Track this response only; the harness continues to own conversation history."""
diff --git a/src/free_claude_code/core/failures.py b/src/free_claude_code/core/failures.py
index 9f813ca7..f95d015a 100644
--- a/src/free_claude_code/core/failures.py
+++ b/src/free_claude_code/core/failures.py
@@ -3,6 +3,8 @@
from dataclasses import FrozenInstanceError, dataclass
from enum import StrEnum
+from .stream_recovery import StreamFailureContext
+
class FailureKind(StrEnum):
"""Stable failure categories shared across execution and wire adapters."""
@@ -26,6 +28,7 @@ class ExecutionFailure(Exception):
status_code: int
message: str
retryable: bool
+ stream_context: StreamFailureContext | None = None
def __post_init__(self) -> None:
Exception.__init__(self, self.message)
diff --git a/src/free_claude_code/core/openai_responses/__init__.py b/src/free_claude_code/core/openai_responses/__init__.py
index d0c29709..549a753c 100644
--- a/src/free_claude_code/core/openai_responses/__init__.py
+++ b/src/free_claude_code/core/openai_responses/__init__.py
@@ -8,7 +8,11 @@ from .errors import (
openai_error_type_for_failure,
openai_failure_payload,
)
-from .events import OPENAI_RESPONSES_SSE_HEADERS, committed_response_failure_frame
+from .events import (
+ OPENAI_RESPONSES_SSE_HEADERS,
+ committed_response_failure_frame,
+ format_response_sse_event,
+)
from .ids import (
new_call_id,
new_message_item_id,
@@ -73,6 +77,7 @@ __all__ = [
"committed_response_failure_frame",
"estimate_responses_input_tokens",
"flatten_responses_tool_name",
+ "format_response_sse_event",
"is_client_search",
"new_call_id",
"new_message_item_id",
diff --git a/src/free_claude_code/core/openai_responses/events.py b/src/free_claude_code/core/openai_responses/events.py
index 940b8fe9..c50f0ba7 100644
--- a/src/free_claude_code/core/openai_responses/events.py
+++ b/src/free_claude_code/core/openai_responses/events.py
@@ -33,6 +33,15 @@ def committed_response_failure_frame(
) -> str:
"""Close an already-public Responses lifecycle after a boundary failure."""
+ failure = find_execution_failure(exc)
+ if (
+ failure is not None
+ and failure.stream_context is not None
+ and failure.stream_context.responses_failure_payload is not None
+ ):
+ return format_response_sse_event(
+ "response.failed", failure.stream_context.responses_failure_payload
+ )
created = _response_event_payload(first_chunk)
response_value = created.get("response") if created is not None else None
if not isinstance(response_value, Mapping) or not isinstance(
@@ -41,7 +50,6 @@ def committed_response_failure_frame(
raise exc
response = cast(JsonObject, deepcopy(dict(response_value)))
- failure = find_execution_failure(exc)
if failure is not None:
error = openai_error_from_failure(failure)
else:
diff --git a/src/free_claude_code/core/openai_responses/messages_stream.py b/src/free_claude_code/core/openai_responses/messages_stream.py
index cdb22c74..293eb20e 100644
--- a/src/free_claude_code/core/openai_responses/messages_stream.py
+++ b/src/free_claude_code/core/openai_responses/messages_stream.py
@@ -21,6 +21,7 @@ from free_claude_code.core.history_replay import (
from free_claude_code.core.json_types import JsonObject, JsonValue
from .errors import openai_error_from_failure
+from .events import format_response_sse_event
from .ids import (
new_message_item_id,
new_reasoning_item_id,
@@ -387,20 +388,14 @@ class AnthropicToResponsesStream:
if not self._started:
self._started = True
events.append(self._events.response_created(self._payload("in_progress")))
- for state in self._ledger.pop_active_blocks_by_output_order():
- if isinstance(state, TextBlockState):
- item = message_item(
- state.item_id, "".join(state.text_parts), "incomplete"
- )
- elif isinstance(state, ReasoningBlockState):
- item = reasoning_item(
- state.item_id, "".join(state.text_parts), "incomplete"
- )
- else:
- item = tool_item(state, status="incomplete")
- self._ledger.commit_output(state.output_index, item)
- self._terminal = True
events.append(
- self._events.response_failed(self._payload("failed", failure=failure))
+ format_response_sse_event("response.failed", self.failure_payload(failure))
)
return events
+
+ def failure_payload(self, failure: ExecutionFailure) -> JsonObject:
+ self._completer.retain_incomplete_blocks()
+ self._terminal = True
+ return self._events.response_failed_payload(
+ self._payload("failed", failure=failure)
+ )
diff --git a/src/free_claude_code/core/openai_responses/native.py b/src/free_claude_code/core/openai_responses/native.py
index 39e0f0a4..58c48181 100644
--- a/src/free_claude_code/core/openai_responses/native.py
+++ b/src/free_claude_code/core/openai_responses/native.py
@@ -81,6 +81,9 @@ class NativeResponsesRelay:
return self._terminal_type is not None
def feed(self, event_type: str, payload: Mapping[str, object]) -> str:
+ return format_response_sse_event(event_type, self.project(event_type, payload))
+
+ def project(self, event_type: str, payload: Mapping[str, object]) -> JsonObject:
"""Format public model metadata and canonical whole-second timestamps."""
if self._terminal_type is not None:
@@ -110,9 +113,14 @@ class NativeResponsesRelay:
)
if event_type in _TERMINAL_EVENT_TYPES:
self._terminal_type = event_type
- return format_response_sse_event(event_type, data)
+ return data
def synthesize_failure(self, failure: ExecutionFailure) -> str:
+ return format_response_sse_event(
+ "response.failed", self.failure_payload(failure)
+ )
+
+ def failure_payload(self, failure: ExecutionFailure) -> JsonObject:
"""Terminate one already-public truncated stream with a safe failure."""
if self._terminal_type is not None:
@@ -137,7 +145,7 @@ class NativeResponsesRelay:
response["model"] = self._public_model
response["status"] = "failed"
response["error"] = cast(JsonValue, openai_error_from_failure(failure))
- return self.feed(
+ return self.project(
"response.failed",
{
"type": "response.failed",
diff --git a/src/free_claude_code/core/openai_responses/streaming/completion.py b/src/free_claude_code/core/openai_responses/streaming/completion.py
index 658b0e3b..dcb35176 100644
--- a/src/free_claude_code/core/openai_responses/streaming/completion.py
+++ b/src/free_claude_code/core/openai_responses/streaming/completion.py
@@ -28,6 +28,19 @@ class ResponseBlockCompleter:
return self._complete_reasoning_block(state)
return self._complete_tool_block(state)
+ def retain_incomplete_blocks(self) -> None:
+ """Keep a failure snapshot without publishing synthetic completions."""
+ for state in self._ledger.pop_active_blocks_by_output_order():
+ if isinstance(state, TextBlockState):
+ item = message_item(
+ state.item_id, "".join(state.text_parts), "incomplete"
+ )
+ elif isinstance(state, ReasoningBlockState):
+ item = reasoning_output_item(state, status="incomplete")
+ else:
+ item = tool_item(state, status="incomplete")
+ self._ledger.commit_output(state.output_index, item)
+
def _complete_text_block(self, state: TextBlockState) -> list[str]:
text = "".join(state.text_parts)
item = message_item(state.item_id, text, "completed")
diff --git a/src/free_claude_code/core/openai_responses/streaming/event_builders.py b/src/free_claude_code/core/openai_responses/streaming/event_builders.py
index 025142f3..4dc691a7 100644
--- a/src/free_claude_code/core/openai_responses/streaming/event_builders.py
+++ b/src/free_claude_code/core/openai_responses/streaming/event_builders.py
@@ -38,10 +38,16 @@ class ResponseEventBuilder:
)
def response_failed(self, response: dict[str, Any]) -> str:
- return self._format(
+ return format_response_sse_event(
+ "response.failed", self.response_failed_payload(response)
+ )
+
+ def response_failed_payload(self, response: dict[str, Any]) -> JsonObject:
+ ((_, payload),) = self._project(
"response.failed",
{"type": "response.failed", "response": response},
)
+ return payload
def output_item_added(self, output_index: int, item: dict[str, Any]) -> str:
return self._format(
@@ -188,11 +194,16 @@ class ResponseEventBuilder:
)
def _format(self, event_type: str, data: dict[str, Any]) -> str:
+ return "".join(
+ format_response_sse_event(kind, payload)
+ for kind, payload in self._project(event_type, data)
+ )
+
+ def _project(
+ self, event_type: str, data: dict[str, Any]
+ ) -> Iterable[tuple[str, JsonObject]]:
data["sequence_number"] = self._next_sequence_number
self._next_sequence_number += 1
if self._transform is not None:
- return "".join(
- format_response_sse_event(kind, payload)
- for kind, payload in self._transform(event_type, cast(JsonObject, data))
- )
- return format_response_sse_event(event_type, data)
+ return self._transform(event_type, cast(JsonObject, data))
+ return ((event_type, cast(JsonObject, data)),)
diff --git a/src/free_claude_code/core/openai_responses/tool_adaptation.py b/src/free_claude_code/core/openai_responses/tool_adaptation.py
index 5a7ef66a..a67bc2f3 100644
--- a/src/free_claude_code/core/openai_responses/tool_adaptation.py
+++ b/src/free_claude_code/core/openai_responses/tool_adaptation.py
@@ -687,9 +687,16 @@ class ResponsesToolEventAdapter:
response = data.get("response")
if isinstance(response, dict):
if isinstance(output := response.get("output"), list):
- response["output"] = [
- self._tools.restore_item(value) for value in output
- ]
+ restored: list[JsonValue] = []
+ for value in output:
+ try:
+ restored.append(self._tools.restore_item(value))
+ except ResponsesConversionError:
+ if event_type != "response.failed":
+ raise
+ # An unusable call in a failed snapshot must not replace
+ # the provider's error or prevent safe model fallback.
+ response["output"] = restored
if "tools" in response:
response["tools"] = (
deepcopy(self._tools.original.tools or [])
diff --git a/src/free_claude_code/core/stream_delivery.py b/src/free_claude_code/core/stream_delivery.py
index 0a1f7a39..893c2a95 100644
--- a/src/free_claude_code/core/stream_delivery.py
+++ b/src/free_claude_code/core/stream_delivery.py
@@ -5,7 +5,7 @@ from contextlib import contextmanager
from contextvars import ContextVar
from typing import Literal
-from .delivered_response import DeliveredPrefix
+from .stream_recovery import DeliveredPrefix
class StreamDeliveryState:
diff --git a/src/free_claude_code/core/stream_recovery.py b/src/free_claude_code/core/stream_recovery.py
new file mode 100644
index 00000000..3c171c41
--- /dev/null
+++ b/src/free_claude_code/core/stream_recovery.py
@@ -0,0 +1,106 @@
+"""Portable recovery evidence shared by provider, routing, and public delivery."""
+
+from copy import deepcopy
+from dataclasses import dataclass
+from enum import StrEnum
+
+from .json_types import JsonObject
+
+
+@dataclass(frozen=True, slots=True)
+class DeliveredPrefix:
+ text: str
+ thinking: str
+ has_calls: bool
+ eligible: bool
+ can_handoff: bool
+ unsafe_reason: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class ContinuationSeed:
+ text: str
+ thinking: str
+
+
+@dataclass(frozen=True, slots=True)
+class SourceRecoverySnapshot:
+ normal_stop_seen: bool = False
+ structured_output: bool = False
+ unsafe_reason: str | None = None
+ can_handoff: bool = True
+
+
+@dataclass(frozen=True, slots=True)
+class StreamFailureContext:
+ source: SourceRecoverySnapshot
+ responses_failure_payload: JsonObject | None = None
+
+ def __post_init__(self) -> None:
+ if self.responses_failure_payload is not None:
+ object.__setattr__(
+ self,
+ "responses_failure_payload",
+ deepcopy(self.responses_failure_payload),
+ )
+
+
+class RecoveryAction(StrEnum):
+ RESTART = "restart"
+ CONTINUE = "continue"
+ HANDOFF = "handoff"
+ STOP = "stop"
+
+
+@dataclass(frozen=True, slots=True)
+class RecoveryAssessment:
+ action: RecoveryAction
+ seed: ContinuationSeed | None = None
+ reason: str | None = None
+
+
+def assess_recovery(
+ *,
+ content_released: bool,
+ prefix: DeliveredPrefix | None,
+ source: SourceRecoverySnapshot,
+ retryable: bool,
+) -> RecoveryAssessment:
+ """Assess safe response transitions independently of any attempt budget."""
+ if source.normal_stop_seen:
+ return RecoveryAssessment(RecoveryAction.STOP, reason="normal_stop")
+ if not content_released:
+ return (
+ RecoveryAssessment(RecoveryAction.STOP, reason=source.unsafe_reason)
+ if source.unsafe_reason
+ else RecoveryAssessment(
+ RecoveryAction.RESTART, reason="no_delivered_content"
+ )
+ )
+ if prefix is None:
+ return RecoveryAssessment(RecoveryAction.STOP, reason="missing_prefix")
+ if prefix.has_calls:
+ if (
+ retryable
+ and not source.structured_output
+ and source.can_handoff
+ and prefix.can_handoff
+ ):
+ return RecoveryAssessment(
+ RecoveryAction.HANDOFF, reason="completed_tool_calls"
+ )
+ return RecoveryAssessment(RecoveryAction.STOP, reason="released_tool_calls")
+ reason = (
+ "structured_output"
+ if source.structured_output
+ else source.unsafe_reason or prefix.unsafe_reason
+ )
+ if reason or not prefix.eligible:
+ return RecoveryAssessment(RecoveryAction.STOP, reason=reason or "unsafe_prefix")
+ if not (prefix.text or prefix.thinking):
+ return RecoveryAssessment(RecoveryAction.STOP, reason="empty_prefix")
+ return RecoveryAssessment(
+ RecoveryAction.CONTINUE,
+ ContinuationSeed(prefix.text, prefix.thinking),
+ reason="portable_prefix",
+ )
diff --git a/src/free_claude_code/providers/anthropic/provider.py b/src/free_claude_code/providers/anthropic/provider.py
index e5dd6a8e..535506e5 100644
--- a/src/free_claude_code/providers/anthropic/provider.py
+++ b/src/free_claude_code/providers/anthropic/provider.py
@@ -20,6 +20,7 @@ from free_claude_code.core.history_replay import HistoryReplayError
from free_claude_code.core.json_types import JsonObject
from free_claude_code.core.openai_responses import OpenAIResponsesRequest
from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
+from free_claude_code.core.stream_recovery import ContinuationSeed
from free_claude_code.providers.admission import (
ProviderAdmissionController,
ProviderOperationKind,
@@ -154,6 +155,7 @@ class AnthropicProvider(BaseProvider):
request_id: str | None = None,
response_model: str | None = None,
request_headers: Mapping[str, str] | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
body, headers = native_request(request.body, request_headers)
try:
@@ -175,6 +177,7 @@ class AnthropicProvider(BaseProvider):
provider_name="anthropic",
read_timeout_s=self._config.http_read_timeout,
request_id=request_id,
+ continuation=continuation,
)
async def stream_messages(
@@ -187,6 +190,7 @@ class AnthropicProvider(BaseProvider):
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
record = await self.model_record(request.model)
stream = self._transport(record).stream_messages(
@@ -196,6 +200,7 @@ class AnthropicProvider(BaseProvider):
response_model=response_model,
reasoning=reasoning,
model_info=record.info,
+ continuation=continuation,
)
try:
async for event in stream:
@@ -213,6 +218,7 @@ class AnthropicProvider(BaseProvider):
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
record = await self.model_record(request.model)
stream = self._transport(record).stream_responses(
@@ -222,6 +228,7 @@ class AnthropicProvider(BaseProvider):
response_model=response_model,
reasoning=reasoning,
model_info=record.info,
+ continuation=continuation,
)
try:
async for event in stream:
diff --git a/src/free_claude_code/providers/anthropic_messages/passthrough.py b/src/free_claude_code/providers/anthropic_messages/passthrough.py
index 7c961c25..61bd8dcd 100644
--- a/src/free_claude_code/providers/anthropic_messages/passthrough.py
+++ b/src/free_claude_code/providers/anthropic_messages/passthrough.py
@@ -19,6 +19,7 @@ from free_claude_code.core.diagnostics import (
)
from free_claude_code.core.failures import ExecutionFailure
from free_claude_code.core.json_types import JsonObject
+from free_claude_code.core.stream_recovery import ContinuationSeed
from free_claude_code.providers.admission import (
ProviderAdmissionController,
ProviderOperationKind,
@@ -27,6 +28,7 @@ from free_claude_code.providers.continuation import (
ContinuationRequest,
SourceRecoveryState,
public_recovery,
+ public_stream_failure,
)
from free_claude_code.providers.failure_policy import (
RetryableProviderProtocolError,
@@ -55,9 +57,12 @@ async def stream_native_messages(
provider_name: str,
read_timeout_s: float,
request_id: str | None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
execution = admission.start_execution(request_id=request_id)
streaming = body.get("stream", False) is True
+ source = SourceRecoveryState(execution)
+ normal_stop_seen = False
async def complete() -> str:
async with client.stream(
@@ -88,9 +93,14 @@ async def stream_native_messages(
committed = False
continuation_request = ContinuationRequest("messages")
operation_kind = ProviderOperationKind.GENERATION
+ if continuation is not None:
+ body = continuation_request.build(
+ body, continuation.text, continuation.thinking
+ )
+ operation_kind = ProviderOperationKind.CONTINUATION
while execution.can_attempt:
normal_stop_seen = False
- source = SourceRecoveryState(execution)
+ source = SourceRecoveryState(execution, previous=source)
scope = None
try:
attempt = await execution.open_attempt(operation_kind)
@@ -213,6 +223,14 @@ async def stream_native_messages(
read_timeout_s=read_timeout_s,
request_id=request_id,
)
+ if streaming and execution.delivery is not None:
+ failure = public_stream_failure(
+ failure,
+ source=source,
+ body=body,
+ protocol="messages",
+ normal_stop_seen=normal_stop_seen,
+ )
execution.fail(failure)
raise failure from error
finally:
diff --git a/src/free_claude_code/providers/anthropic_messages/transport.py b/src/free_claude_code/providers/anthropic_messages/transport.py
index 88f09807..7ecb93f5 100644
--- a/src/free_claude_code/providers/anthropic_messages/transport.py
+++ b/src/free_claude_code/providers/anthropic_messages/transport.py
@@ -32,6 +32,7 @@ from free_claude_code.core.reasoning import (
ReasoningControl,
ReasoningPolicy,
)
+from free_claude_code.core.stream_recovery import ContinuationSeed
from free_claude_code.core.trace import trace_event
from free_claude_code.providers.admission import (
ProviderAdmissionController,
@@ -42,6 +43,7 @@ from free_claude_code.providers.continuation import (
ContinuationRequest,
SourceRecoveryState,
public_recovery,
+ public_stream_failure,
)
from free_claude_code.providers.endpoint import RequestEndpoint
from free_claude_code.providers.endpoint_types import EndpointContext
@@ -169,6 +171,7 @@ class AnthropicMessagesTransport:
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
model_info: ProviderModelInfo | None = None,
preserve_native_controls: bool = False,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
capabilities = self._effective_capabilities(model_info)
if preserve_native_controls:
@@ -203,6 +206,7 @@ class AnthropicMessagesTransport:
presenter_factory=lambda origin: NativeMessagesRelay(
public_model=response_model or request.model, replay_origin=origin
),
+ continuation=continuation,
)
def stream_responses(
@@ -214,6 +218,7 @@ class AnthropicMessagesTransport:
response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
prepared = self._responses_body(
request, reasoning, self._effective_capabilities(model_info)
@@ -229,6 +234,7 @@ class AnthropicMessagesTransport:
tool_identities=prepared.tool_identities,
replay_origin=origin,
),
+ continuation=continuation,
)
async def _stream(
@@ -240,6 +246,7 @@ class AnthropicMessagesTransport:
request_id: str | None,
presenter_factory: Callable[[ReplayOrigin], _Presenter],
reasoning_correction: ReasoningCorrection | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
execution = self._admission.start_execution(request_id=request_id)
run = self._run(
@@ -249,6 +256,7 @@ class AnthropicMessagesTransport:
endpoint_context=endpoint_context,
execution=execution,
presenter_factory=presenter_factory,
+ continuation=continuation,
)
try:
async for event in run:
@@ -273,6 +281,7 @@ class AnthropicMessagesTransport:
execution: ProviderExecution,
presenter_factory: Callable[[ReplayOrigin], _Presenter],
reasoning_correction: ReasoningCorrection | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
recovery = RecoveryController(execution.delivery)
request_endpoint = RequestEndpoint(endpoint_context)
@@ -282,12 +291,19 @@ class AnthropicMessagesTransport:
corrections = RequestCorrections("messages", reasoning_correction)
continuation_request = ContinuationRequest("messages")
operation_kind = ProviderOperationKind.GENERATION
+ if continuation is not None:
+ body = continuation_request.build(
+ body, continuation.text, continuation.thinking
+ )
+ operation_kind = ProviderOperationKind.CONTINUATION
+ source: SourceRecoveryState | None = None
while execution.can_attempt:
normal_stop_seen = False
- source = SourceRecoveryState(execution)
+ source = SourceRecoveryState(execution, previous=source)
scope: ProviderAttemptScope | None = None
stream_opened = False
sent_body = body
+ presenter: _Presenter | None = None
try:
attempt = await execution.open_attempt(operation_kind)
scope = ProviderAttemptScope(
@@ -458,6 +474,20 @@ class AnthropicMessagesTransport:
transport="messages",
failure_kind=failure.kind.value,
)
+ if execution.delivery is not None:
+ recovery.discard()
+ raise public_stream_failure(
+ failure,
+ source=source,
+ body=body,
+ protocol="messages",
+ normal_stop_seen=normal_stop_seen,
+ responses_failure_payload=(
+ presenter.failure_payload(failure)
+ if isinstance(presenter, AnthropicToResponsesStream)
+ else None
+ ),
+ ) from raw_error
if decision.committed and isinstance(
presenter, AnthropicToResponsesStream
):
diff --git a/src/free_claude_code/providers/base.py b/src/free_claude_code/providers/base.py
index 4dae7210..28790155 100644
--- a/src/free_claude_code/providers/base.py
+++ b/src/free_claude_code/providers/base.py
@@ -10,6 +10,7 @@ from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.anthropic.passthrough import NativeMessagesRequest
from free_claude_code.core.openai_responses import OpenAIResponsesRequest
from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
+from free_claude_code.core.stream_recovery import ContinuationSeed
@dataclass(frozen=True, slots=True)
@@ -51,6 +52,7 @@ class BaseProvider(ABC):
request_id: str | None = None,
response_model: str | None = None,
request_headers: Mapping[str, str] | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
raise InvalidRequestError(
"This provider does not support native Messages execution."
@@ -67,6 +69,7 @@ class BaseProvider(ABC):
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
"""Validate the request before yielding a response in Anthropic SSE format."""
@@ -81,5 +84,6 @@ class BaseProvider(ABC):
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
"""Validate the request before yielding OpenAI Responses SSE events."""
diff --git a/src/free_claude_code/providers/continuation.py b/src/free_claude_code/providers/continuation.py
index ad547555..da3acac5 100644
--- a/src/free_claude_code/providers/continuation.py
+++ b/src/free_claude_code/providers/continuation.py
@@ -1,7 +1,7 @@
"""Same-provider continuation using evidence from the public delivery boundary."""
from copy import deepcopy
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
from typing import Any, Literal
from free_claude_code.core.delivered_response import (
@@ -10,6 +10,14 @@ from free_claude_code.core.delivered_response import (
)
from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.core.history_replay import reasoning_context
+from free_claude_code.core.json_types import JsonObject
+from free_claude_code.core.stream_recovery import (
+ ContinuationSeed,
+ RecoveryAction,
+ SourceRecoverySnapshot,
+ StreamFailureContext,
+ assess_recovery,
+)
from free_claude_code.core.trace import trace_event
from .admission import ProviderExecution
@@ -20,8 +28,18 @@ type UpstreamProtocol = Literal["chat", "messages", "responses"]
class SourceRecoveryState:
"""Native source evidence cannot be inferred from buffered public events."""
- def __init__(self, execution: ProviderExecution) -> None:
+ def __init__(
+ self,
+ execution: ProviderExecution,
+ *,
+ previous: SourceRecoveryState | None = None,
+ ) -> None:
self._execution = execution
+ self._prior_unsafe_reason = (
+ previous.unsafe_reason or previous._prior_unsafe_reason
+ if previous is not None
+ else None
+ )
self.unsafe_reason: str | None = None
self._pending_reasoning: set[int | str] = set()
self._signed: set[int | str] = set()
@@ -31,6 +49,22 @@ class SourceRecoveryState:
def can_handoff(self) -> bool:
return not self._handoff_blocked and not self._pending_reasoning
+ def snapshot(
+ self,
+ *,
+ body: dict[str, Any],
+ protocol: UpstreamProtocol,
+ normal_stop_seen: bool,
+ for_model_fallback: bool = False,
+ ) -> SourceRecoverySnapshot:
+ return SourceRecoverySnapshot(
+ normal_stop_seen=normal_stop_seen,
+ structured_output=_structured_output(body, protocol),
+ unsafe_reason=self.unsafe_reason
+ or (self._prior_unsafe_reason if for_model_fallback else None),
+ can_handoff=self.can_handoff,
+ )
+
def observe(
self,
protocol: UpstreamProtocol,
@@ -174,34 +208,64 @@ class ContinuationRequest:
if self._injected_rows:
# Request corrections preserve these trailing plain-text turns.
history = history[: -self._injected_rows]
- instruction = "The previous provider stream was interrupted. Continue the assistant response exactly where it stopped. Do not repeat text already written."
- if result.get("tools"):
- instruction += " No tool calls from this interrupted assistant turn were delivered or executed. Any unfinished calls were discarded. Emit the required tool calls using the provided tools."
- if thinking:
- instruction = f"{reasoning_context(thinking)}\n\n{instruction}"
- tail = []
- if text:
- tail.append(
+ tail = continuation_tail(
+ ContinuationSeed(text, thinking), tools=bool(result.get("tools"))
+ )
+ if responses:
+ tail = [
{
- "role": "assistant",
- "content": [{"type": "output_text", "text": text}]
- if responses
- else text,
+ "role": row["role"],
+ "content": [
+ {
+ "type": "output_text"
+ if row["role"] == "assistant"
+ else "input_text",
+ "text": row["content"],
+ }
+ ],
}
- )
- tail.append(
- {
- "role": "user",
- "content": [{"type": "input_text", "text": instruction}]
- if responses
- else instruction,
- }
- )
+ for row in tail
+ ]
result[field] = [*history, *tail]
self._injected_rows = len(tail)
return result
+def continuation_tail(seed: ContinuationSeed, *, tools: bool) -> list[dict[str, Any]]:
+ """Materialize the same private context for construction and estimation."""
+ instruction = "The previous provider stream was interrupted. Continue the assistant response exactly where it stopped. Do not repeat text already written."
+ if tools:
+ instruction += " No tool calls from this interrupted assistant turn were delivered or executed. Any unfinished calls were discarded. Emit the required tool calls using the provided tools."
+ if seed.thinking:
+ instruction = f"{reasoning_context(seed.thinking)}\n\n{instruction}"
+ tail = [{"role": "assistant", "content": seed.text}] if seed.text else []
+ return [*tail, {"role": "user", "content": instruction}]
+
+
+def public_stream_failure(
+ failure: ExecutionFailure,
+ *,
+ source: SourceRecoveryState,
+ body: dict[str, Any],
+ protocol: UpstreamProtocol,
+ normal_stop_seen: bool,
+ responses_failure_payload: JsonObject | None = None,
+) -> ExecutionFailure:
+ """Retain source evidence until routing has decided the public outcome."""
+ return replace(
+ failure,
+ stream_context=StreamFailureContext(
+ source.snapshot(
+ body=body,
+ protocol=protocol,
+ normal_stop_seen=normal_stop_seen,
+ for_model_fallback=True,
+ ),
+ responses_failure_payload,
+ ),
+ )
+
+
def _structured_output(body: dict[str, Any], protocol: UpstreamProtocol) -> bool:
if protocol == "chat":
extra = body.get("extra_body") or {}
@@ -224,30 +288,26 @@ def public_recovery(
delivery = execution.delivery
if delivery is None or not delivery.content_released:
return None
- if not retryable or normal_stop_seen:
- return None
- prefix = delivery.prefix
- if prefix is None:
+ if not retryable:
return None
- structured = _structured_output(body, request.protocol)
- handoff = (
- not structured
- and prefix.has_calls
- and source.can_handoff
- and prefix.can_handoff
+ assessment = assess_recovery(
+ content_released=True,
+ prefix=delivery.prefix,
+ source=source.snapshot(
+ body=body, protocol=request.protocol, normal_stop_seen=normal_stop_seen
+ ),
+ retryable=retryable,
)
- if not handoff and (structured or source.unsafe_reason or not prefix.eligible):
+ if assessment.action is RecoveryAction.STOP:
trace_event(
stage="provider",
event="provider.recovery.ineligible",
source="provider",
request_id=execution.request_id,
- reason="structured_output"
- if structured
- else source.unsafe_reason or prefix.unsafe_reason,
+ reason=assessment.reason,
)
return None
- if handoff:
+ if assessment.action is RecoveryAction.HANDOFF:
delivery.begin_continuation(handoff=True)
trace_event(
stage="provider",
@@ -267,9 +327,10 @@ def public_recovery(
max_attempts=execution.max_attempts,
)
return None
- if not (prefix.text or prefix.thinking):
+ seed = assessment.seed
+ if seed is None:
return None
- replacement = request.build(body, prefix.text, prefix.thinking)
+ replacement = request.build(body, seed.text, seed.thinking)
delivery.begin_continuation()
trace_event(
stage="provider",
diff --git a/src/free_claude_code/providers/custom.py b/src/free_claude_code/providers/custom.py
index 595ff4af..2ba1bbcc 100644
--- a/src/free_claude_code/providers/custom.py
+++ b/src/free_claude_code/providers/custom.py
@@ -18,6 +18,7 @@ from free_claude_code.core.reasoning import (
ReasoningEffort,
ReasoningPolicy,
)
+from free_claude_code.core.stream_recovery import ContinuationSeed
from free_claude_code.providers.admission import (
ProviderAdmissionController,
ProviderOperationKind,
@@ -219,6 +220,7 @@ class CustomProvider(BaseProvider):
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
reasoning = self._reasoning(reasoning)
if (
@@ -245,6 +247,7 @@ class CustomProvider(BaseProvider):
model_info=model_info,
preserve_native_controls=self._definition.reasoning_format
== "provider_default",
+ continuation=continuation,
)
transport = self._chat if self._chat is not None else self._responses
assert transport is not None
@@ -256,6 +259,7 @@ class CustomProvider(BaseProvider):
response_model=response_model or request.model,
reasoning=reasoning,
model_info=model_info,
+ continuation=continuation,
)
def stream_responses(
@@ -268,6 +272,7 @@ class CustomProvider(BaseProvider):
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
reasoning = (
responses_reasoning_policy(request.reasoning)
@@ -296,6 +301,7 @@ class CustomProvider(BaseProvider):
response_model=response_model,
reasoning=reasoning,
model_info=model_info,
+ continuation=continuation,
)
transport = self._chat if self._chat is not None else self._responses
assert transport is not None
@@ -306,6 +312,7 @@ class CustomProvider(BaseProvider):
request_id=request_id,
response_model=response_model or request.model,
reasoning=reasoning,
+ continuation=continuation,
)
async def list_model_infos(self) -> frozenset[ProviderModelInfo]:
diff --git a/src/free_claude_code/providers/github_copilot/provider.py b/src/free_claude_code/providers/github_copilot/provider.py
index c78815ae..391fa79c 100644
--- a/src/free_claude_code/providers/github_copilot/provider.py
+++ b/src/free_claude_code/providers/github_copilot/provider.py
@@ -16,6 +16,7 @@ from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.core.openai_responses import OpenAIResponsesRequest
from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
+from free_claude_code.core.stream_recovery import ContinuationSeed
from free_claude_code.providers.admission import ProviderAdmissionController
from free_claude_code.providers.anthropic_messages.transport import (
AnthropicMessagesTransport,
@@ -142,6 +143,7 @@ class GitHubCopilotProvider(BaseProvider):
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
self._check_model(request.model)
return self._dispatch(
@@ -150,6 +152,7 @@ class GitHubCopilotProvider(BaseProvider):
request_id,
response_model or request.model,
reasoning,
+ continuation=continuation,
)
def stream_responses(
@@ -162,6 +165,7 @@ class GitHubCopilotProvider(BaseProvider):
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
self._check_model(request.model)
return self._dispatch(
@@ -170,6 +174,7 @@ class GitHubCopilotProvider(BaseProvider):
request_id,
response_model or request.model,
reasoning,
+ continuation=continuation,
)
def _chat(self, model: CopilotModel) -> OpenAIChatTransport:
@@ -195,6 +200,7 @@ class GitHubCopilotProvider(BaseProvider):
request_id: str | None,
response_model: str,
reasoning: ReasoningPolicy,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
async with self._condition:
self._check_model(request.model)
@@ -231,6 +237,7 @@ class GitHubCopilotProvider(BaseProvider):
response_model=response_model,
reasoning=reasoning,
model_info=lease.model.info,
+ continuation=continuation,
)
else:
selected = native.stream_responses(
@@ -239,6 +246,7 @@ class GitHubCopilotProvider(BaseProvider):
request_id=request_id,
response_model=response_model,
reasoning=reasoning,
+ continuation=continuation,
)
else:
resolved = non_messages_reasoning(
@@ -261,6 +269,7 @@ class GitHubCopilotProvider(BaseProvider):
model_info=lease.model.info,
can_disable_reasoning="none"
in (lease.model.supported_efforts or ()),
+ continuation=continuation,
)
else:
selected = self._chat(lease.model).stream_messages(
@@ -271,6 +280,7 @@ class GitHubCopilotProvider(BaseProvider):
reasoning=resolved,
endpoint_context=lease,
model_info=lease.model.info,
+ continuation=continuation,
)
else:
selected = transport.stream_responses(
@@ -280,6 +290,7 @@ class GitHubCopilotProvider(BaseProvider):
response_model=response_model,
reasoning=resolved,
endpoint_context=lease,
+ continuation=continuation,
)
while True:
try:
diff --git a/src/free_claude_code/providers/lmstudio/client.py b/src/free_claude_code/providers/lmstudio/client.py
index ca20888a..22a38f12 100644
--- a/src/free_claude_code/providers/lmstudio/client.py
+++ b/src/free_claude_code/providers/lmstudio/client.py
@@ -31,8 +31,10 @@ from free_claude_code.core.reasoning import (
ReasoningEffort,
ReasoningPolicy,
)
+from free_claude_code.core.stream_recovery import ContinuationSeed
from free_claude_code.providers.admission import ProviderAdmissionController
from free_claude_code.providers.base import ProviderConfig
+from free_claude_code.providers.continuation import ContinuationRequest
from free_claude_code.providers.endpoint_types import EndpointContext
from free_claude_code.providers.failure_policy import (
context_window_exceeded_provider_failure,
@@ -98,6 +100,7 @@ class LMStudioProvider(OpenAIChatProvider):
model_info: ProviderModelInfo | None = None,
endpoint_context: EndpointContext | None = None,
request_headers: Mapping[str, str] | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
stream = super().stream_messages(
request,
@@ -108,10 +111,24 @@ class LMStudioProvider(OpenAIChatProvider):
model_info=model_info,
endpoint_context=endpoint_context,
request_headers=request_headers,
+ continuation=continuation,
)
+ estimate_request = request
+ if continuation is not None:
+ estimate_request = MessagesRequest.model_validate(
+ ContinuationRequest("messages").build(
+ request.model_dump(mode="json"),
+ continuation.text,
+ continuation.thinking,
+ )
+ )
return self._stream_with_context_budget(
stream,
- estimate=get_token_count(request.messages, request.system, request.tools),
+ estimate=get_token_count(
+ estimate_request.messages,
+ estimate_request.system,
+ estimate_request.tools,
+ ),
request_id=request_id,
)
@@ -126,6 +143,7 @@ class LMStudioProvider(OpenAIChatProvider):
endpoint_context: EndpointContext | None = None,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
stream = super().stream_responses(
request,
@@ -136,10 +154,20 @@ class LMStudioProvider(OpenAIChatProvider):
endpoint_context=endpoint_context,
request_headers=request_headers,
model_info=model_info,
+ continuation=continuation,
)
+ estimate_request = request
+ if continuation is not None:
+ estimate_request = OpenAIResponsesRequest.model_validate(
+ ContinuationRequest("responses").build(
+ request.model_dump(mode="json"),
+ continuation.text,
+ continuation.thinking,
+ )
+ )
return self._stream_with_context_budget(
stream,
- estimate=estimate_responses_input_tokens(request),
+ estimate=estimate_responses_input_tokens(estimate_request),
request_id=request_id,
)
diff --git a/src/free_claude_code/providers/openai_api/provider.py b/src/free_claude_code/providers/openai_api/provider.py
index 5e17e55d..84c791d0 100644
--- a/src/free_claude_code/providers/openai_api/provider.py
+++ b/src/free_claude_code/providers/openai_api/provider.py
@@ -14,6 +14,7 @@ from free_claude_code.core.openai_responses import (
ResponsesStreamFailure,
)
from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
+from free_claude_code.core.stream_recovery import ContinuationSeed
from free_claude_code.providers.admission import (
ProviderAdmissionController,
ProviderOperationKind,
@@ -121,6 +122,7 @@ class OpenAIAPIProvider(BaseProvider):
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
return self._responses.stream_messages(
request,
@@ -129,6 +131,7 @@ class OpenAIAPIProvider(BaseProvider):
response_model=response_model or request.model,
reasoning=reasoning,
model_info=model_info,
+ continuation=continuation,
)
def stream_responses(
@@ -141,6 +144,7 @@ class OpenAIAPIProvider(BaseProvider):
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
return self._responses.stream_responses(
request,
@@ -148,4 +152,5 @@ class OpenAIAPIProvider(BaseProvider):
request_id=request_id,
response_model=response_model or request.model,
reasoning=reasoning,
+ continuation=continuation,
)
diff --git a/src/free_claude_code/providers/openai_chat/provider.py b/src/free_claude_code/providers/openai_chat/provider.py
index 6bb65777..90a72f7a 100644
--- a/src/free_claude_code/providers/openai_chat/provider.py
+++ b/src/free_claude_code/providers/openai_chat/provider.py
@@ -16,6 +16,7 @@ from free_claude_code.core.reasoning import (
DEFAULT_REASONING_POLICY,
ReasoningPolicy,
)
+from free_claude_code.core.stream_recovery import ContinuationSeed
from free_claude_code.providers.admission import (
ProviderAdmissionController,
ProviderOperationKind,
@@ -213,6 +214,7 @@ class OpenAIChatProvider(BaseProvider):
model_info: ProviderModelInfo | None = None,
endpoint_context: EndpointContext | None = None,
request_headers: Mapping[str, str] | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
return self._chat.stream_messages(
request,
@@ -222,6 +224,7 @@ class OpenAIChatProvider(BaseProvider):
reasoning=reasoning,
endpoint_context=endpoint_context,
model_info=model_info,
+ continuation=continuation,
)
def stream_responses(
@@ -235,6 +238,7 @@ class OpenAIChatProvider(BaseProvider):
endpoint_context: EndpointContext | None = None,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
return self._chat.stream_responses(
request,
@@ -243,4 +247,5 @@ class OpenAIChatProvider(BaseProvider):
response_model=response_model,
reasoning=reasoning,
endpoint_context=endpoint_context,
+ continuation=continuation,
)
diff --git a/src/free_claude_code/providers/openai_chat/stream_output.py b/src/free_claude_code/providers/openai_chat/stream_output.py
index 412970b7..0cf6525b 100644
--- a/src/free_claude_code/providers/openai_chat/stream_output.py
+++ b/src/free_claude_code/providers/openai_chat/stream_output.py
@@ -327,6 +327,9 @@ class ChatStreamOutput(ABC):
self._terminal = True
return events
+ def failure_payload(self, failure: ExecutionFailure) -> JsonObject | None:
+ return None
+
@abstractmethod
def _start_events(self) -> list[str]: ...
@@ -755,6 +758,15 @@ class ResponsesChatStreamOutput(ChatStreamOutput):
)
return [self._events.response_failed(response)]
+ def failure_payload(self, failure: ExecutionFailure) -> JsonObject:
+ self._completer.retain_incomplete_blocks()
+ self._terminal = True
+ return self._events.response_failed_payload(
+ self._response_payload(
+ status="failed", error=openai_error_from_failure(failure)
+ )
+ )
+
def _responses_usage(usage: ChatStreamUsage) -> dict[str, object]:
cached_tokens = usage.cached_tokens
diff --git a/src/free_claude_code/providers/openai_chat/transport.py b/src/free_claude_code/providers/openai_chat/transport.py
index b6c33b39..0c18fedb 100644
--- a/src/free_claude_code/providers/openai_chat/transport.py
+++ b/src/free_claude_code/providers/openai_chat/transport.py
@@ -54,6 +54,7 @@ from free_claude_code.core.reasoning import (
ReasoningControl,
ReasoningPolicy,
)
+from free_claude_code.core.stream_recovery import ContinuationSeed
from free_claude_code.core.trace import provider_chat_body_snapshot, trace_event
from free_claude_code.providers.admission import (
ProviderAdmissionController,
@@ -64,6 +65,7 @@ from free_claude_code.providers.continuation import (
ContinuationRequest,
SourceRecoveryState,
public_recovery,
+ public_stream_failure,
)
from free_claude_code.providers.endpoint import RequestEndpoint
from free_claude_code.providers.endpoint_types import EndpointContext
@@ -786,6 +788,7 @@ class OpenAIChatTransport:
model_info: ProviderModelInfo | None = None,
endpoint_context: EndpointContext | None = None,
extra_headers: Mapping[str, str] | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
"""Stream response in Anthropic SSE format."""
prepared_request, wire_reasoning = self._prepare_messages_reasoning(
@@ -828,6 +831,7 @@ class OpenAIChatTransport:
endpoint_context=endpoint_context,
extra_headers=extra_headers or {},
reasoning_correction=correction,
+ continuation=continuation,
)
return runner.run()
@@ -841,6 +845,7 @@ class OpenAIChatTransport:
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
endpoint_context: EndpointContext | None = None,
extra_headers: Mapping[str, str] | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
"""Stream a Chat upstream directly as OpenAI Responses SSE."""
translated = self._build_responses_request_body(request, reasoning=reasoning)
@@ -866,6 +871,7 @@ class OpenAIChatTransport:
reasoning=reasoning,
endpoint_context=endpoint_context,
extra_headers=extra_headers or {},
+ continuation=continuation,
)
return runner.run()
@@ -889,9 +895,11 @@ class _OpenAIChatStreamRunner:
endpoint_context: EndpointContext | None = None,
extra_headers: Mapping[str, str] | None = None,
reasoning_correction: ReasoningCorrection | None = None,
+ continuation: ContinuationSeed | None = None,
) -> None:
self._transport = transport
self._body = body
+ self._continuation = continuation
self._tool_argument_aliases = transport._behavior.tool_argument_aliases(body)
self._tool_names = tool_names
self._tool_schemas = tool_schemas
@@ -957,6 +965,11 @@ class _OpenAIChatStreamRunner:
body = self._body
continuation_request = ContinuationRequest("chat")
operation_kind = ProviderOperationKind.GENERATION
+ if self._continuation is not None:
+ body = continuation_request.build(
+ body, self._continuation.text, self._continuation.thinking
+ )
+ operation_kind = ProviderOperationKind.CONTINUATION
request_stream_usage(body)
output_reasoning = self._reasoning.output_enabled
corrections = RequestCorrections("chat", self._reasoning_correction)
@@ -974,9 +987,10 @@ class _OpenAIChatStreamRunner:
tool_count=len(body.get("tools", [])),
)
+ source: SourceRecoveryState | None = None
while True:
assembler = self._new_stream_assembler(output_reasoning=output_reasoning)
- source = SourceRecoveryState(execution)
+ source = SourceRecoveryState(execution, previous=source)
def observe_chunk(
chunk: Any,
@@ -1112,6 +1126,7 @@ class _OpenAIChatStreamRunner:
error=error,
scope=scope,
assembler=assembler,
+ source=source,
body=body,
request_recovery=request_recovery,
recovery=recovery,
@@ -1195,6 +1210,7 @@ class _OpenAIChatStreamRunner:
error: Exception,
scope: ProviderAttemptScope | None,
assembler: _OpenAIChatStreamAssembler,
+ source: SourceRecoveryState,
body: dict[str, Any],
request_recovery: RequestRecovery,
recovery: RecoveryController,
@@ -1343,6 +1359,20 @@ class _OpenAIChatStreamRunner:
error_trace["error_message"] = failure.message
trace_event(**error_trace)
+ if execution.delivery is not None:
+ recovery.discard()
+ return _OpenAIChatFailureResolution(
+ outcome=_OpenAIChatFailureOutcome.RAISE,
+ failure=public_stream_failure(
+ failure,
+ source=source,
+ body=body,
+ protocol="chat",
+ normal_stop_seen=assembler.normal_stop_seen,
+ responses_failure_payload=assembler.output.failure_payload(failure),
+ ),
+ )
+
failure_events: list[str] = []
if (
not decision.committed
diff --git a/src/free_claude_code/providers/openai_codex/provider.py b/src/free_claude_code/providers/openai_codex/provider.py
index f99f6a43..fc9df346 100644
--- a/src/free_claude_code/providers/openai_codex/provider.py
+++ b/src/free_claude_code/providers/openai_codex/provider.py
@@ -15,6 +15,7 @@ from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.openai_responses import OpenAIResponsesRequest
from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
+from free_claude_code.core.stream_recovery import ContinuationSeed
from free_claude_code.providers.admission import (
ProviderAdmissionController,
ProviderOperationKind,
@@ -170,6 +171,7 @@ class OpenAICodexProvider(BaseProvider):
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
return self._responses.stream_messages(
request,
@@ -179,6 +181,7 @@ class OpenAICodexProvider(BaseProvider):
reasoning=reasoning,
endpoint_context=self._endpoint(session_id=str(uuid.uuid4())),
model_info=model_info,
+ continuation=continuation,
)
def stream_responses(
@@ -191,6 +194,7 @@ class OpenAICodexProvider(BaseProvider):
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
return self._responses.stream_responses(
request,
@@ -199,6 +203,7 @@ class OpenAICodexProvider(BaseProvider):
response_model=response_model or request.model,
reasoning=reasoning,
endpoint_context=self._endpoint(session_id=str(uuid.uuid4())),
+ continuation=continuation,
)
diff --git a/src/free_claude_code/providers/openai_responses/presentation.py b/src/free_claude_code/providers/openai_responses/presentation.py
index 64343b07..b0be1788 100644
--- a/src/free_claude_code/providers/openai_responses/presentation.py
+++ b/src/free_claude_code/providers/openai_responses/presentation.py
@@ -11,6 +11,7 @@ from free_claude_code.core.openai_responses import (
ResponsesProviderStream,
ResponsesStreamFailure,
ResponsesToolEventAdapter,
+ format_response_sse_event,
)
@@ -33,6 +34,10 @@ class ResponsesStreamPresenter(Protocol):
failure: ExecutionFailure,
) -> Iterable[str]: ...
+ def failure_payload(
+ self, raw_error: Exception, failure: ExecutionFailure
+ ) -> JsonObject | None: ...
+
class MessagesResponsesPresenter:
"""Translate one Responses attempt into Anthropic Messages SSE."""
@@ -62,6 +67,9 @@ class MessagesResponsesPresenter:
del raw_error, failure
return self._stream.ledger.close_unclosed_blocks()
+ def failure_payload(self, raw_error: Exception, failure: ExecutionFailure) -> None:
+ return None
+
class NativeResponsesPresenter:
"""Relay one Responses attempt as native Responses SSE."""
@@ -96,13 +104,25 @@ class NativeResponsesPresenter:
raw_error: Exception,
failure: ExecutionFailure,
) -> Iterable[str]:
+ return (
+ format_response_sse_event(
+ "response.failed", self.failure_payload(raw_error, failure)
+ ),
+ )
+
+ def failure_payload(
+ self, raw_error: Exception, failure: ExecutionFailure
+ ) -> JsonObject:
if (
isinstance(raw_error, ResponsesStreamFailure)
and raw_error.event_type == "response.failed"
and raw_error.payload is not None
):
- return self.feed(raw_error.event_type, raw_error.payload)
- return (self._relay.synthesize_failure(failure),)
+ payload = raw_error.payload
+ if self._tool_events is not None:
+ ((_, payload),) = self._tool_events.feed("response.failed", payload)
+ return self._relay.project("response.failed", payload)
+ return self._relay.failure_payload(failure)
@dataclass(slots=True)
diff --git a/src/free_claude_code/providers/openai_responses/transport.py b/src/free_claude_code/providers/openai_responses/transport.py
index 5687d0da..bbcd21fe 100644
--- a/src/free_claude_code/providers/openai_responses/transport.py
+++ b/src/free_claude_code/providers/openai_responses/transport.py
@@ -36,6 +36,7 @@ from free_claude_code.core.openai_responses import (
)
from free_claude_code.core.openai_tool_names import OpenAIToolNameCodec
from free_claude_code.core.reasoning import ReasoningControl, ReasoningPolicy
+from free_claude_code.core.stream_recovery import ContinuationSeed
from free_claude_code.core.trace import trace_event
from free_claude_code.providers.admission import (
ProviderAdmissionController,
@@ -46,6 +47,7 @@ from free_claude_code.providers.continuation import (
ContinuationRequest,
SourceRecoveryState,
public_recovery,
+ public_stream_failure,
)
from free_claude_code.providers.endpoint import RequestEndpoint
from free_claude_code.providers.endpoint_types import EndpointContext
@@ -136,6 +138,7 @@ class OpenAIResponsesTransport:
extra_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
can_disable_reasoning: bool = True,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
prepared, wire_reasoning = prepare_messages_reasoning(
request,
@@ -170,6 +173,7 @@ class OpenAIResponsesTransport:
pad_empty=pad_empty,
)
),
+ continuation=continuation,
)
def stream_responses(
@@ -182,6 +186,7 @@ class OpenAIResponsesTransport:
reasoning: ReasoningPolicy,
endpoint_context: EndpointContext | None = None,
extra_headers: Mapping[str, str] | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
del input_tokens
body, tools = self._build_native_body(request, reasoning=reasoning)
@@ -194,6 +199,7 @@ class OpenAIResponsesTransport:
presenter_factory=lambda _pad_empty: NativeResponsesPresenter(
public_model=response_model, tool_events=tools.event_adapter()
),
+ continuation=continuation,
)
def _build_messages_body(
@@ -264,6 +270,7 @@ class OpenAIResponsesTransport:
endpoint_context: EndpointContext | None = None,
extra_headers: Mapping[str, str] | None = None,
reasoning_correction: ReasoningCorrection | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
execution = self._admission.start_execution(request_id=request_id)
outcome = ResponsesExecutionOutcome()
@@ -282,6 +289,7 @@ class OpenAIResponsesTransport:
endpoint=endpoint,
request_client=request_client,
extra_headers=extra_headers,
+ continuation=continuation,
)
try:
async for event in provider_stream:
@@ -318,6 +326,7 @@ class OpenAIResponsesTransport:
request_client: OpenAIRequestClient,
extra_headers: Mapping[str, str] | None = None,
reasoning_correction: ReasoningCorrection | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
recovery = RecoveryController(execution.delivery)
request_recovery = RequestRecovery(
@@ -326,6 +335,11 @@ class OpenAIResponsesTransport:
corrections = RequestCorrections("responses", reasoning_correction)
continuation_request = ContinuationRequest("responses")
operation_kind = ProviderOperationKind.GENERATION
+ if continuation is not None:
+ body = continuation_request.build(
+ body, continuation.text, continuation.thinking
+ )
+ operation_kind = ProviderOperationKind.CONTINUATION
trace_event(
stage="provider",
event="provider.request.sent",
@@ -338,9 +352,10 @@ class OpenAIResponsesTransport:
transport="responses",
)
+ source: SourceRecoveryState | None = None
while execution.can_attempt:
normal_stop_seen = False
- source = SourceRecoveryState(execution)
+ source = SourceRecoveryState(execution, previous=source)
presenter = presenter_factory(
operation_kind is ProviderOperationKind.GENERATION
)
@@ -561,6 +576,18 @@ class OpenAIResponsesTransport:
status_code=failure.status_code,
provider_retryable=failure.retryable,
)
+ if execution.delivery is not None:
+ recovery.discard()
+ raise public_stream_failure(
+ failure,
+ source=source,
+ body=body,
+ protocol="responses",
+ normal_stop_seen=normal_stop_seen,
+ responses_failure_payload=presenter.failure_payload(
+ raw_error, failure
+ ),
+ ) from raw_error
if not decision.committed:
recovery.discard()
raise failure from raw_error
diff --git a/src/free_claude_code/providers/opencode/provider.py b/src/free_claude_code/providers/opencode/provider.py
index fdad1993..04509b79 100644
--- a/src/free_claude_code/providers/opencode/provider.py
+++ b/src/free_claude_code/providers/opencode/provider.py
@@ -15,6 +15,7 @@ from free_claude_code.core.openai_responses import (
ResponsesToolPolicy,
)
from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
+from free_claude_code.core.stream_recovery import ContinuationSeed
from free_claude_code.providers.admission import ProviderAdmissionController
from free_claude_code.providers.base import BaseProvider, ProviderConfig
from free_claude_code.providers.endpoint_types import EndpointContext
@@ -178,6 +179,7 @@ class OpenCodeProvider(BaseProvider):
endpoint_context: EndpointContext | None = None,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
return self._dispatch_stream(
request,
@@ -187,6 +189,7 @@ class OpenCodeProvider(BaseProvider):
reasoning=reasoning,
endpoint_context=endpoint_context,
request_headers=request_headers,
+ continuation=continuation,
)
async def _dispatch_stream(
@@ -199,6 +202,7 @@ class OpenCodeProvider(BaseProvider):
reasoning: ReasoningPolicy,
endpoint_context: EndpointContext | None = None,
request_headers: Mapping[str, str] | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
snapshot = await self._catalog.snapshot(request_id=request_id)
route = self._require_route(snapshot, request.model)
@@ -215,6 +219,7 @@ class OpenCodeProvider(BaseProvider):
endpoint_context=endpoint_context,
extra_headers=self._upstream_headers(request_headers or {}),
model_info=route.model_info,
+ continuation=continuation,
)
else:
selected_stream = self._chat.stream_messages(
@@ -226,6 +231,7 @@ class OpenCodeProvider(BaseProvider):
endpoint_context=endpoint_context,
extra_headers=self._upstream_headers(request_headers or {}),
model_info=route.model_info,
+ continuation=continuation,
)
async for event in selected_stream:
yield event
@@ -249,6 +255,7 @@ class OpenCodeProvider(BaseProvider):
endpoint_context: EndpointContext | None = None,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
return self._dispatch_responses_stream(
request,
@@ -258,6 +265,7 @@ class OpenCodeProvider(BaseProvider):
reasoning=reasoning,
endpoint_context=endpoint_context,
request_headers=request_headers,
+ continuation=continuation,
)
async def _dispatch_responses_stream(
@@ -270,6 +278,7 @@ class OpenCodeProvider(BaseProvider):
reasoning: ReasoningPolicy,
endpoint_context: EndpointContext | None = None,
request_headers: Mapping[str, str] | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
snapshot = await self._catalog.snapshot(request_id=request_id)
route = self._require_route(snapshot, request.model)
@@ -285,6 +294,7 @@ class OpenCodeProvider(BaseProvider):
reasoning=reasoning,
endpoint_context=endpoint_context,
extra_headers=self._upstream_headers(request_headers or {}),
+ continuation=continuation,
)
else:
selected_stream = self._chat.stream_responses(
@@ -295,6 +305,7 @@ class OpenCodeProvider(BaseProvider):
reasoning=reasoning,
endpoint_context=endpoint_context,
extra_headers=self._upstream_headers(request_headers or {}),
+ continuation=continuation,
)
async for event in selected_stream:
yield event
diff --git a/tests/api/model_fallback_support.py b/tests/api/model_fallback_support.py
index 16bcb3e0..b02b1c93 100644
--- a/tests/api/model_fallback_support.py
+++ b/tests/api/model_fallback_support.py
@@ -16,6 +16,7 @@ from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.core.json_types import JsonObject
from free_claude_code.core.openai_responses import OpenAIResponsesRequest
from free_claude_code.core.reasoning import ReasoningPolicy
+from free_claude_code.core.stream_recovery import ContinuationSeed
from tests.api.support import create_test_app
@@ -211,6 +212,7 @@ class ControlledFallbackProvider:
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
del input_tokens, request_id, reasoning
if self._validation_error is not None:
@@ -239,6 +241,7 @@ class ControlledFallbackProvider:
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
del input_tokens, request_id, reasoning
if self._validation_error is not None:
diff --git a/tests/api/test_api_handlers.py b/tests/api/test_api_handlers.py
index 836eb715..6f6cffe8 100644
--- a/tests/api/test_api_handlers.py
+++ b/tests/api/test_api_handlers.py
@@ -23,6 +23,7 @@ from free_claude_code.core.anthropic.streaming import format_sse_event
from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.core.openai_responses import OpenAIResponsesRequest
from free_claude_code.core.reasoning import ReasoningPolicy
+from free_claude_code.core.stream_recovery import ContinuationSeed
from tests.web_tools_support import StubWebToolsClient
_LEGACY_CLASSIFIER_SYSTEM = (
@@ -64,6 +65,7 @@ class FakeProvider:
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
self.requests.append(request)
self.stream_kwargs.append(
@@ -87,6 +89,7 @@ class FakeProvider:
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
self.responses_requests.append(request)
self.stream_kwargs.append(
@@ -398,6 +401,7 @@ async def test_messages_handler_stream_false_provider_exception_keeps_status() -
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
self.requests.append(request)
self.stream_kwargs.append(
diff --git a/tests/api/test_execution_failure_contract.py b/tests/api/test_execution_failure_contract.py
index 871d5926..a35cc387 100644
--- a/tests/api/test_execution_failure_contract.py
+++ b/tests/api/test_execution_failure_contract.py
@@ -21,6 +21,7 @@ from free_claude_code.core.openai_responses import (
openai_error_from_failure,
)
from free_claude_code.core.reasoning import ReasoningPolicy
+from free_claude_code.core.stream_recovery import ContinuationSeed
from tests.api.support import create_test_app
_PARTIAL_CONTENT = "PARTIAL_ASSISTANT_CONTENT"
@@ -110,6 +111,7 @@ class StalledProvider:
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
del input_tokens, request_id, response_model, reasoning
try:
@@ -128,6 +130,7 @@ class StalledProvider:
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
del input_tokens, request_id, response_model, reasoning
try:
diff --git a/tests/api/test_hidden_stream_retries.py b/tests/api/test_hidden_stream_retries.py
index 332563a3..bbcfcb99 100644
--- a/tests/api/test_hidden_stream_retries.py
+++ b/tests/api/test_hidden_stream_retries.py
@@ -59,7 +59,7 @@ def partial_tool(protocol):
def executed(body, wire):
- async def open_candidate(_index, _target):
+ async def open_candidate(_index, _target, _continuation):
return body
return ProviderExecutor(
diff --git a/tests/api/test_midstream_model_fallback.py b/tests/api/test_midstream_model_fallback.py
new file mode 100644
index 00000000..edeb956d
--- /dev/null
+++ b/tests/api/test_midstream_model_fallback.py
@@ -0,0 +1,498 @@
+"""Model fallback continues the public response through real provider transports."""
+
+from unittest.mock import AsyncMock
+
+import pytest
+
+from free_claude_code.application.execution import ProviderExecutor
+from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
+from free_claude_code.core.reasoning import ReasoningPolicy
+from free_claude_code.providers.admission import ProviderAdmissionController
+from free_claude_code.providers.open_router import OpenRouterProvider
+from free_claude_code.providers.stream_recovery import RecoveryHoldbackBuffer
+from tests.api.test_delivered_stream_recovery import (
+ after_text,
+ assert_completed,
+ public_text,
+ text_events,
+)
+from tests.api.test_hidden_stream_retries import partial_tool
+from tests.api.test_response_streams import _serve
+from tests.api.test_tool_call_buffer import _response
+from tests.api.test_tool_call_buffer_transports import _tools
+from tests.application.test_execution import _routed_request, _target
+from tests.providers.support import make_provider_config
+from tests.providers.test_history_transports import _events_for, _harness
+from tests.providers.test_native_tool_arguments import tool_events
+
+
[email protected](autouse=True)
+def release_provider_events(monkeypatch):
+ monkeypatch.setattr(
+ "free_claude_code.providers.stream_recovery.RecoveryHoldbackBuffer",
+ lambda: RecoveryHoldbackBuffer(max_bytes=1),
+ )
+
+
+async def delivered_candidates(senders, wire, *, tools=None, progress_timeout=10):
+ history = [{"role": "user", "content": "greet"}]
+
+ async def open_candidate(index, target, continuation=None):
+ return senders[index](
+ wire,
+ history,
+ tools=tools,
+ model=target.provider_model,
+ continuation=continuation,
+ )
+
+ routed = _routed_request(
+ *(
+ _target(f"fallback-{index}", f"model-{index}")
+ for index in range(1, len(senders))
+ )
+ )
+ body = ProviderExecutor(
+ AsyncMock(), progress_timeout_seconds=progress_timeout
+ )._stream_candidates(
+ resolved=routed.resolved,
+ reasoning=ReasoningPolicy.provider_default(),
+ wire_api=wire,
+ raw_log_label="MIDSTREAM_FALLBACK",
+ raw_log_payload=dict,
+ request_snapshot=dict,
+ ingress_count_name="message_count",
+ ingress_count=1,
+ request_id="midstream-fallback",
+ open_candidate=open_candidate,
+ )
+ response = await _response(wire, body)
+ messages = await _serve(response)
+ return b"".join(message.get("body", b"") for message in messages).decode()
+
+
[email protected]("source", ["chat", "messages", "responses"])
[email protected]("target", ["chat", "messages", "responses"])
[email protected]("wire", ["messages", "responses"])
+async def test_exhausted_model_continues_on_next_candidate(source, target, wire):
+ async with (
+ _harness(
+ source,
+ lambda bodies: (
+ 200,
+ text_events(
+ source, ["Hello ", "there. "][len(bodies) - 1], complete=False
+ ),
+ ),
+ max_attempts=2,
+ ) as (first, first_bodies, _),
+ _harness(
+ target, lambda _: (200, text_events(target, "Hello there. Done."))
+ ) as (second, second_bodies, _),
+ ):
+ raw = await delivered_candidates([first, second], wire, tools=_tools(wire))
+
+ assert len(first_bodies) == 2
+ assert len(second_bodies) == 1
+ events = parse_sse_text(raw)
+ assert_completed(events, wire)
+ assert public_text(events, wire) == "Hello there. Done."
+ body = second_bodies[0]
+ history = body.get("messages", body.get("input"))
+ assert len(history) == 3
+ assert "Hello there. " in str(history[-2])
+ assert body["tools"]
+ if wire == "responses":
+ assert (
+ "".join(
+ part.get("text", "")
+ for item in events[-1].data["response"]["output"]
+ for part in item.get("content", [])
+ )
+ == "Hello there. Done."
+ )
+
+
[email protected]("protocol", ["chat", "messages", "responses"])
[email protected]("wire", ["messages", "responses"])
+async def test_normal_completion_never_opens_another_candidate(protocol, wire):
+ async with (
+ _harness(protocol, lambda _: (200, text_events(protocol, "Done."))) as (
+ first,
+ first_bodies,
+ _,
+ ),
+ _harness("chat", lambda _: (200, text_events("chat", "Unexpected"))) as (
+ second,
+ second_bodies,
+ _,
+ ),
+ ):
+ raw = await delivered_candidates([first, second], wire)
+
+ assert len(first_bodies) == 1
+ assert not second_bodies
+ events = parse_sse_text(raw)
+ assert_completed(events, wire)
+ assert public_text(events, wire) == "Done."
+
+
[email protected]("wire", ["messages", "responses"])
+async def test_each_model_receives_the_latest_prefix_and_its_own_budget(wire):
+ async with (
+ _harness(
+ "chat",
+ lambda _: (200, text_events("chat", "One ", complete=False)),
+ max_attempts=1,
+ ) as (first, first_bodies, _),
+ _harness(
+ "messages",
+ lambda bodies: (
+ 200,
+ text_events(
+ "messages", ["two ", "three "][len(bodies) - 1], complete=False
+ ),
+ ),
+ max_attempts=2,
+ ) as (second, second_bodies, _),
+ _harness(
+ "responses",
+ lambda _: (200, text_events("responses", "One two three four.")),
+ max_attempts=1,
+ ) as (third, third_bodies, _),
+ ):
+ raw = await delivered_candidates([first, second, third], wire)
+ assert [len(first_bodies), len(second_bodies), len(third_bodies)] == [1, 2, 1]
+ for body, expected in [
+ (second_bodies[0], "One "),
+ (second_bodies[1], "One two "),
+ (third_bodies[0], "One two three "),
+ ]:
+ history = body.get("messages", body.get("input"))
+ assert len(history) == 3
+ assert expected in str(history[-2])
+ events = parse_sse_text(raw)
+ assert_completed(events, wire)
+ assert public_text(events, wire) == "One two three four."
+
+
[email protected]("wire", ["messages", "responses"])
+ "status,error",
+ [
+ (401, {"type": "authentication_error", "message": "Bad credentials"}),
+ (
+ 400,
+ {
+ "type": "invalid_request_error",
+ "code": "context_length_exceeded",
+ "message": "Context full",
+ },
+ ),
+ ],
+)
+async def test_permanent_rejection_advances_without_erasing_incoming_prefix(
+ wire, status, error
+):
+ async with (
+ _harness(
+ "chat",
+ lambda _: (200, text_events("chat", "Hello ", complete=False)),
+ max_attempts=1,
+ ) as (first, first_bodies, _),
+ _harness("responses", lambda _: (status, error), max_attempts=5) as (
+ second,
+ second_bodies,
+ _,
+ ),
+ _harness(
+ "messages",
+ lambda _: (200, text_events("messages", "world.")),
+ max_attempts=1,
+ ) as (third, third_bodies, _),
+ ):
+ raw = await delivered_candidates([first, second, third], wire)
+ assert [len(first_bodies), len(second_bodies), len(third_bodies)] == [1, 1, 1]
+ assert "Hello " in str(third_bodies[0]["messages"][-2])
+ assert_completed(parse_sse_text(raw), wire)
+ assert public_text(parse_sse_text(raw), wire) == "Hello world."
+
+
[email protected]("protocol", ["chat", "messages", "responses"])
[email protected]("wire", ["messages", "responses"])
[email protected]("visible", [False, True])
+async def test_abandoned_calls_never_cross_model_boundary(protocol, wire, visible):
+ failed_events = partial_tool(protocol)
+ if visible:
+ failed_events = after_text(protocol, failed_events)
+ async with (
+ _harness(protocol, lambda _: (200, failed_events), max_attempts=1) as (
+ first,
+ first_bodies,
+ _,
+ ),
+ _harness(
+ "messages",
+ lambda _: (200, tool_events("messages", '{"path":"winning"}')),
+ max_attempts=1,
+ ) as (second, second_bodies, _),
+ ):
+ raw = await delivered_candidates([first, second], wire, tools=_tools(wire))
+ assert len(first_bodies) == len(second_bodies) == 1
+ assert "call_abandoned" not in raw and "abandoned" not in str(second_bodies[0])
+ assert len(second_bodies[0]["messages"]) == (3 if visible else 1)
+ events = parse_sse_text(raw)
+ assert_completed(events, wire)
+ assert public_text(events, wire) == ("Before. " if visible else "")
+ if wire == "messages":
+ assert (
+ "".join(
+ event.data.get("delta", {}).get("partial_json", "") for event in events
+ )
+ == '{"path":"winning"}'
+ )
+ else:
+ calls = [
+ item
+ for item in events[-1].data["response"]["output"]
+ if item["type"] == "function_call"
+ ]
+ assert len(calls) == 1 and calls[0]["arguments"] == '{"path":"winning"}'
+
+
[email protected]("protocol", ["chat", "messages", "responses"])
[email protected]("wire", ["messages", "responses"])
+async def test_first_fallback_call_rejects_native_state_without_trying_next_model(
+ protocol, wire
+):
+ async with (
+ _harness(
+ "chat",
+ lambda _: (200, text_events("chat", "Hello ", complete=False)),
+ max_attempts=1,
+ ) as (first, _, _),
+ _harness(protocol, lambda _: (200, _events_for(protocol)), max_attempts=3) as (
+ second,
+ second_bodies,
+ _,
+ ),
+ _harness("chat", lambda _: (200, text_events("chat", "Unexpected"))) as (
+ third,
+ third_bodies,
+ _,
+ ),
+ ):
+ raw = await delivered_candidates([first, second, third], wire)
+ assert len(second_bodies) == 1 and not third_bodies
+ events = parse_sse_text(raw)
+ assert events[-1].event == ("error" if wire == "messages" else "response.failed")
+ assert public_text(events, wire) == "Hello "
+ assert "opaque-original" not in raw
+
+
[email protected]("protocol", ["chat", "messages", "responses"])
[email protected]("wire", ["messages", "responses"])
[email protected]("text", ["", "Hello "])
+async def test_first_fallback_call_cannot_complete_without_new_output(
+ protocol, wire, text
+):
+ async with (
+ _harness(
+ "chat",
+ lambda _: (200, text_events("chat", "Hello ", complete=False)),
+ max_attempts=1,
+ ) as (first, _, _),
+ _harness(
+ protocol, lambda _: (200, text_events(protocol, text)), max_attempts=3
+ ) as (second, second_bodies, _),
+ _harness("chat", lambda _: (200, text_events("chat", "Unexpected"))) as (
+ third,
+ third_bodies,
+ _,
+ ),
+ ):
+ raw = await delivered_candidates([first, second, third], wire)
+ assert len(second_bodies) == 1 and not third_bodies
+ events = parse_sse_text(raw)
+ assert events[-1].event == ("error" if wire == "messages" else "response.failed")
+ assert public_text(events, wire) == "Hello "
+
+
[email protected]("protocol", ["messages", "responses"])
[email protected]("wire", ["messages", "responses"])
[email protected]("permanent", [False, True])
+async def test_released_calls_handoff_only_for_retryable_failure(
+ protocol, wire, permanent
+):
+ completed = tool_events(protocol, '{"path":"kept"}')
+ failed_events = completed[:-2] if protocol == "messages" else completed[:-1]
+ if permanent:
+ error = {
+ "type": "invalid_request_error",
+ "code": "context_length_exceeded",
+ "message": "Context full",
+ }
+ failed_events.append(
+ {"type": "error", "error": error}
+ if protocol == "messages"
+ else {
+ **completed[-1],
+ "type": "response.failed",
+ "response": {
+ **completed[-1]["response"],
+ "status": "failed",
+ "error": error,
+ },
+ }
+ )
+ async with (
+ _harness(protocol, lambda _: (200, failed_events), max_attempts=1) as (
+ first,
+ first_bodies,
+ _,
+ ),
+ _harness("chat", lambda _: (200, text_events("chat", "Unexpected"))) as (
+ second,
+ second_bodies,
+ _,
+ ),
+ ):
+ raw = await delivered_candidates([first, second], wire, tools=_tools(wire))
+ assert len(first_bodies) == 1 and not second_bodies
+ events = parse_sse_text(raw)
+ if permanent:
+ assert events[-1].event == (
+ "error" if wire == "messages" else "response.failed"
+ )
+ else:
+ assert_completed(events, wire)
+
+
[email protected]("protocol", ["chat", "messages", "responses"])
[email protected]("wire", ["messages", "responses"])
+async def test_source_native_state_prevents_model_fallback(protocol, wire):
+ async with (
+ _harness(
+ protocol, lambda _: (200, _events_for(protocol)[:-1]), max_attempts=1
+ ) as (first, first_bodies, _),
+ _harness("chat", lambda _: (200, text_events("chat", "Unexpected"))) as (
+ second,
+ second_bodies,
+ _,
+ ),
+ ):
+ raw = await delivered_candidates([first, second], wire)
+ assert len(first_bodies) == 1 and not second_bodies
+ assert parse_sse_text(raw)[-1].event == (
+ "error" if wire == "messages" else "response.failed"
+ )
+
+
[email protected]("wire", ["messages", "responses"])
[email protected]("later_failure", [False, True])
+async def test_hidden_hosted_activity_remains_a_model_boundary_after_local_retry(
+ wire, later_failure
+):
+ hidden = [
+ *partial_tool("responses"),
+ {
+ "type": "response.output_item.added",
+ "sequence_number": 3,
+ "output_index": 1,
+ "item": {
+ "type": "web_search_call",
+ "id": "ws_hidden",
+ "status": "in_progress",
+ },
+ },
+ ]
+
+ def reply(bodies):
+ if len(bodies) == 1:
+ return 200, hidden
+ if later_failure:
+ return 401, {
+ "type": "authentication_error",
+ "message": "Credentials expired",
+ }
+ return 200, text_events("responses", "Done.")
+
+ async with (
+ _harness("responses", reply, max_attempts=2) as (first, first_bodies, _),
+ _harness("chat", lambda _: (200, text_events("chat", "Unexpected"))) as (
+ second,
+ second_bodies,
+ _,
+ ),
+ ):
+ raw = await delivered_candidates([first, second], wire, tools=_tools(wire))
+ assert len(first_bodies) == 2
+ assert not second_bodies
+ events = parse_sse_text(raw)
+ if later_failure:
+ assert events[-1].event == (
+ "error" if wire == "messages" else "response.failed"
+ )
+ else:
+ assert_completed(events, wire)
+
+
[email protected]("wire", ["messages", "responses"])
+async def test_shared_cooldown_skips_candidate_with_zero_calls_and_keeps_seed(
+ monkeypatch, wire
+):
+ shared = ProviderAdmissionController(
+ provider_name="shared",
+ rate_limit=1000,
+ max_attempts=2,
+ base_delay=60,
+ max_delay=60,
+ jitter=0,
+ )
+ executions = []
+ start = shared.start_execution
+
+ def capture(**kwargs):
+ execution = start(**kwargs)
+ executions.append(execution)
+ return execution
+
+ monkeypatch.setattr(shared, "start_execution", capture)
+
+ def reply(bodies):
+ if len(bodies) == 1:
+ return 200, text_events("chat", "Hello ", complete=False)
+ return 503, {"type": "server_error", "message": "Unavailable"}
+
+ async with (
+ _harness(
+ "chat",
+ reply,
+ chat_provider_factory=lambda: OpenRouterProvider(
+ make_provider_config("fixture", "https://provider.invalid/v1"),
+ admission=shared,
+ ),
+ ) as (first, shared_bodies, _),
+ _harness("messages", lambda _: (200, text_events("messages", "world."))) as (
+ third,
+ third_bodies,
+ _,
+ ),
+ ):
+ raw = await delivered_candidates([first, first, third], wire)
+ assert [execution.attempts_started for execution in executions] == [2, 0]
+ assert len(shared_bodies) == 2 and len(third_bodies) == 1
+ assert "Hello " in str(third_bodies[0]["messages"][-2])
+ assert_completed(parse_sse_text(raw), wire)
+ assert public_text(parse_sse_text(raw), wire) == "Hello world."
diff --git a/tests/api/test_model_fallback_clients.py b/tests/api/test_model_fallback_clients.py
new file mode 100644
index 00000000..660996ee
--- /dev/null
+++ b/tests/api/test_model_fallback_clients.py
@@ -0,0 +1,153 @@
+"""Native routing and official client consumption across a model transition."""
+
+import json
+
+import httpx
+import httpx2
+import pytest
+from fastapi.testclient import TestClient
+from openai import AsyncOpenAI
+
+from free_claude_code.config.settings import Settings
+from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
+from free_claude_code.providers.stream_recovery import RecoveryHoldbackBuffer
+from tests.api.support import create_test_app, provider_manager_for_app
+from tests.api.test_delivered_stream_recovery import (
+ assert_completed,
+ public_text,
+ text_events,
+)
+from tests.api.test_hidden_stream_retries import delivered
+from tests.api.test_midstream_model_fallback import delivered_candidates
+from tests.api.test_tool_call_buffer_transports import _tools
+from tests.providers.test_anthropic_messages_transport import Wire, _sse
+from tests.providers.test_anthropic_provider import native_body, provider
+from tests.providers.test_history_transports import _harness
+from tests.providers.test_native_tool_arguments import tool_events
+
+
[email protected](autouse=True)
+def release_events(monkeypatch):
+ monkeypatch.setattr(
+ "free_claude_code.providers.stream_recovery.RecoveryHoldbackBuffer",
+ lambda: RecoveryHoldbackBuffer(max_bytes=1),
+ )
+
+
+def test_native_fallback_closes_source_preserves_options_and_filters_candidates():
+ bodies = []
+ wires = []
+
+ def reply(request):
+ body = json.loads(request.content)
+ bodies.append(body)
+ if len(bodies) > 1:
+ assert wires[-1].closed
+ wire = Wire(
+ [
+ _sse(
+ *text_events(
+ "messages",
+ "Hello " if len(bodies) == 1 else "world.",
+ complete=len(bodies) > 1,
+ )
+ )
+ ]
+ )
+ wires.append(wire)
+ return httpx.Response(
+ 200, headers={"content-type": "text/event-stream"}, stream=wire
+ )
+
+ app = create_test_app(
+ Settings(
+ MODEL="anthropic/primary",
+ MODEL_FALLBACKS=["nvidia_nim/excluded", "anthropic/backup"],
+ ),
+ providers={"anthropic": provider(reply, max_attempts=1)},
+ )
+ request = native_body(True)
+ with TestClient(app) as client:
+ response = client.post("/v1/messages", json=request)
+ assert response.status_code == 200
+ assert [body["model"] for body in bodies] == ["primary", "backup"]
+ assert bodies[1]["messages"][:-2] == request["messages"]
+ assert bodies[1]["messages"][-2] == {"role": "assistant", "content": "Hello "}
+ for key in ("tools", "thinking", "max_tokens", "future_option"):
+ assert bodies[1][key] == request[key]
+ assert all(wire.closed for wire in wires)
+ events = parse_sse_text(response.text)
+ assert_completed(events, "messages")
+ assert public_text(events, "messages") == "Hello world."
+ assert events[0].data["message"]["model"] == request["model"]
+ assert provider_manager_for_app(app)._current.active_leases == 0
+
+
[email protected]("target", ["chat", "messages", "responses"])
+async def test_responses_sdk_consumes_fallback_and_replays_only_real_tool_history(
+ target,
+):
+ async with (
+ _harness(
+ "chat",
+ lambda _: (200, text_events("chat", "Before. ", complete=False)),
+ max_attempts=1,
+ ) as (first, _, _),
+ _harness(
+ target,
+ lambda bodies: (
+ 200,
+ tool_events(target, '{"path":"winning"}')
+ if len(bodies) == 1
+ else text_events(target, "Result."),
+ ),
+ ) as (second, second_bodies, _),
+ ):
+ raw = await delivered_candidates(
+ [first, second], "responses", tools=_tools("responses")
+ )
+ http = httpx2.AsyncClient(
+ transport=httpx2.MockTransport(
+ lambda _: httpx2.Response(
+ 200,
+ headers={"content-type": "text/event-stream"},
+ content=raw.encode(),
+ )
+ )
+ )
+ async with (
+ AsyncOpenAI(api_key="fixture", max_retries=0, http_client=http) as client,
+ client.responses.stream(model="fixture", input="greet") as stream,
+ ):
+ seen = [event async for event in stream]
+ final = await stream.get_final_response()
+ assert seen[-1].type == "response.completed"
+ items = [
+ item.model_dump(mode="json", exclude_none=True) for item in final.output
+ ]
+ call = next(item for item in items if item["type"] == "function_call")
+ assert call["call_id"] == "call_probe"
+ assert call["arguments"] == '{"path":"winning"}'
+ assert (
+ "".join(part["text"] for item in items for part in item.get("content", []))
+ == "Before. "
+ )
+ history = [
+ {"role": "user", "content": "greet"},
+ *items,
+ {
+ "type": "function_call_output",
+ "call_id": call["call_id"],
+ "output": "file-data",
+ },
+ ]
+ following = await delivered(
+ second("responses", history, tools=_tools("responses")), "responses"
+ )
+ assert_completed(parse_sse_text(following), "responses")
+ assert "file-data" in str(second_bodies[-1])
+ assert "The previous provider stream was interrupted" not in str(
+ second_bodies[-1]
+ )
+ assert len(second_bodies) == 2
diff --git a/tests/api/test_model_fallback_failure_payloads.py b/tests/api/test_model_fallback_failure_payloads.py
new file mode 100644
index 00000000..5cabbeda
--- /dev/null
+++ b/tests/api/test_model_fallback_failure_payloads.py
@@ -0,0 +1,336 @@
+"""Only the final candidate failure reaches the public Responses lifecycle."""
+
+import asyncio
+from copy import deepcopy
+from itertools import pairwise
+
+import pytest
+
+from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
+from free_claude_code.core.failures import ExecutionFailure
+from free_claude_code.providers.admission import ProviderAdmissionController
+from free_claude_code.providers.stream_recovery import RecoveryHoldbackBuffer
+from tests.api.test_delivered_stream_recovery import (
+ after_text,
+ public_text,
+ text_events,
+)
+from tests.api.test_hidden_stream_retries import partial_tool
+from tests.api.test_midstream_model_fallback import delivered_candidates
+from tests.api.test_tool_call_buffer_transports import _tools
+from tests.providers.test_history_transports import _harness
+from tests.providers.test_native_tool_arguments import tool_events
+
+
[email protected](autouse=True)
+def release_events(monkeypatch):
+ monkeypatch.setattr(
+ "free_claude_code.providers.stream_recovery.RecoveryHoldbackBuffer",
+ lambda: RecoveryHoldbackBuffer(max_bytes=1),
+ )
+
+
+def failed_response(text, label):
+ events = text_events("responses", text)
+ for event in events:
+ if "response" in event:
+ event["response"]["id"] = f"resp_{label}"
+ final = events[-1]
+ final["type"] = "response.failed"
+ final["extension"] = {"candidate": label}
+ final["response"].update(
+ status="failed",
+ created_at=12.0,
+ completed_at=34.0,
+ metadata={"candidate": label},
+ error={
+ "type": "invalid_request_error",
+ "code": "context_length_exceeded",
+ "message": f"{label} rejected continuation",
+ "param": None,
+ "provider_extension": {"keep": True},
+ },
+ )
+ return events
+
+
+async def test_final_native_failure_preserves_projected_error_output_usage_and_extensions():
+ source = failed_response("Partial text", "only")
+ expected = deepcopy(source[-1])
+ async with _harness("responses", lambda _: (200, source), max_attempts=1) as (
+ send,
+ bodies,
+ _,
+ ):
+ raw = await delivered_candidates([send], "responses")
+ assert len(bodies) == 1
+ events = parse_sse_text(raw)
+ final = events[-1].data
+ assert events[-1].event == "response.failed"
+ assert sum(event.event == "response.failed" for event in events) == 1
+ assert final["extension"] == expected["extension"]
+ for field in ("id", "output", "usage", "error", "metadata", "status"):
+ assert final["response"][field] == expected["response"][field]
+ assert final["response"]["model"] == "public-alias"
+ assert type(final["response"]["created_at"]) is int
+ assert type(final["response"]["completed_at"]) is int
+ assert source[-1] == expected
+
+
+async def test_final_native_snapshot_cannot_release_a_withheld_call():
+ source = after_text("responses", partial_tool("responses"))
+ final = failed_response("Before. ", "only")[-1]
+ call = tool_events("responses", '{"path":"unreleased"}')[-1]["response"]["output"][
+ 0
+ ]
+ call["call_id"] = "call_abandoned"
+ final["response"]["output"].append(call)
+ final["sequence_number"] = len(source)
+ source.append(final)
+ async with _harness("responses", lambda _: (200, source), max_attempts=1) as (
+ send,
+ _,
+ _,
+ ):
+ raw = await delivered_candidates([send], "responses", tools=_tools("responses"))
+ events = parse_sse_text(raw)
+ assert "call_abandoned" not in raw and "unreleased" not in raw
+ assert events[-1].data["response"]["error"] == final["response"]["error"]
+ assert [item["type"] for item in events[-1].data["response"]["output"]] == [
+ "message"
+ ]
+ assert public_text(events, "responses") == "Before. "
+
+
[email protected]("protocol", ["chat", "messages", "responses"])
+async def test_zero_call_final_candidate_keeps_published_response_identity(protocol):
+ admission = ProviderAdmissionController(
+ provider_name="cooled",
+ rate_limit=1000,
+ max_attempts=1,
+ base_delay=60,
+ max_delay=60,
+ jitter=0,
+ )
+ async with (
+ _harness(
+ "responses",
+ lambda _: (200, text_events("responses", "")[:1]),
+ max_attempts=1,
+ ) as (first, first_bodies, _),
+ _harness(
+ protocol,
+ lambda _: (503, {"type": "server_error", "message": "Unavailable"}),
+ max_attempts=1,
+ ) as (last, last_bodies, provider),
+ ):
+ transport = provider._chat if protocol == "chat" else provider
+ transport._admission = admission
+ warmup = last("responses", [{"role": "user", "content": "earlier request"}])
+ try:
+ with pytest.raises(ExecutionFailure):
+ await anext(warmup)
+ finally:
+ await warmup.aclose()
+ prior_calls = len(last_bodies)
+ raw = await delivered_candidates([first, last], "responses")
+ assert len(last_bodies) == prior_calls == 1
+ assert len(first_bodies) == 1
+ events = parse_sse_text(raw)
+ assert [event.event for event in events] == ["response.created", "response.failed"]
+ first_event, final = (event.data for event in events)
+ assert final["response"]["id"] == first_event["response"]["id"]
+ assert final["response"]["created_at"] == first_event["response"]["created_at"]
+ assert final["sequence_number"] > first_event["sequence_number"]
+
+
+def failed_overlapping_calls():
+ template = tool_events("responses", '{"path":"finished"}')
+ response = deepcopy(template[-1]["response"])
+ finished = {
+ **response["output"][0],
+ "id": "fc_finished",
+ "call_id": "call_finished",
+ "status": "completed",
+ }
+ unfinished = {
+ **finished,
+ "id": "fc_unfinished",
+ "call_id": "call_unfinished",
+ "arguments": '{"path":',
+ "status": "incomplete",
+ }
+ events = [
+ {
+ **template[0],
+ "response": {**response, "status": "in_progress", "output": []},
+ },
+ *(
+ {
+ "type": "response.output_item.added",
+ "output_index": index,
+ "item": {**item, "status": "in_progress", "arguments": ""},
+ }
+ for index, item in enumerate([finished, unfinished])
+ ),
+ {"type": "response.output_item.done", "output_index": 0, "item": finished},
+ {
+ "type": "response.function_call_arguments.delta",
+ "output_index": 1,
+ "item_id": "fc_unfinished",
+ "delta": unfinished["arguments"],
+ },
+ {
+ "type": "response.failed",
+ "response": {
+ **response,
+ "output": [finished, unfinished],
+ "status": "failed",
+ "error": {"code": "server_error", "message": "cut"},
+ },
+ },
+ ]
+ return [{**event, "sequence_number": index} for index, event in enumerate(events)]
+
+
[email protected]("same_candidate", [False, True])
[email protected]("hold_final_attempt", [False, True])
+async def test_failed_snapshot_cannot_release_an_overlapping_group_hidden_by_provider(
+ monkeypatch, same_candidate, hold_final_attempt
+):
+ buffers = []
+
+ def buffer():
+ value = RecoveryHoldbackBuffer(
+ max_bytes=1_000_000 if buffers and hold_final_attempt else 1,
+ holdback_seconds=60,
+ )
+ buffers.append(value)
+ return value
+
+ monkeypatch.setattr(
+ "free_claude_code.providers.stream_recovery.RecoveryHoldbackBuffer", buffer
+ )
+ async with (
+ _harness(
+ "responses",
+ lambda bodies: (
+ 200,
+ failed_overlapping_calls()
+ if same_candidate and len(bodies) > 1
+ else text_events("responses", "")[:1],
+ ),
+ max_attempts=2 if same_candidate else 1,
+ ) as (first, first_bodies, _),
+ _harness(
+ "responses", lambda _: (200, failed_overlapping_calls()), max_attempts=1
+ ) as (last, last_bodies, _),
+ ):
+ raw = await delivered_candidates(
+ [first] if same_candidate else [first, last],
+ "responses",
+ tools=_tools("responses"),
+ )
+ assert len(first_bodies) == (2 if same_candidate else 1)
+ assert len(last_bodies) == (0 if same_candidate else 1)
+ events = parse_sse_text(raw)
+ assert [event.event for event in events] == ["response.created", "response.failed"]
+ assert events[-1].data["response"]["output"] == []
+ assert "call_finished" not in raw and "call_unfinished" not in raw
+
+
+async def test_last_model_error_keeps_combined_output_with_public_item_ids():
+ first_events = failed_response("One ", "first")
+ last_events = failed_response("two", "last")
+ async with (
+ _harness("responses", lambda _: (200, first_events), max_attempts=5) as (
+ first,
+ first_bodies,
+ _,
+ ),
+ _harness("responses", lambda _: (200, last_events), max_attempts=5) as (
+ last,
+ last_bodies,
+ _,
+ ),
+ ):
+ raw = await delivered_candidates([first, last], "responses")
+ assert len(first_bodies) == len(last_bodies) == 1
+ events = parse_sse_text(raw)
+ assert sum(event.event == "response.failed" for event in events) == 1
+ assert sum(event.event == "response.created" for event in events) == 1
+ final = events[-1].data
+ assert final["response"]["id"] == "resp_first"
+ assert final["response"]["created_at"] == events[0].data["response"]["created_at"]
+ assert final["response"]["error"] == last_events[-1]["response"]["error"]
+ assert final["response"]["metadata"] == {"candidate": "last"}
+ assert final["extension"] == {"candidate": "last"}
+ assert public_text(events, "responses") == "One two"
+ assert (
+ "".join(
+ part["text"]
+ for item in final["response"]["output"]
+ for part in item.get("content", [])
+ )
+ == "One two"
+ )
+ assert {item["id"] for item in final["response"]["output"]} == {
+ event.data["item_id"]
+ for event in events
+ if event.event == "response.output_text.delta"
+ }
+ assert all(
+ a.data["sequence_number"] < b.data["sequence_number"]
+ for a, b in pairwise(events)
+ )
+ assert final["response"]["usage"]["output_tokens"] > 0
+
+
[email protected]("wire", ["messages", "responses"])
+async def test_fallback_timeout_before_its_first_frame_retains_prefix_and_closes(wire):
+ opened = []
+ closed = []
+
+ async def waiting(*args, **kwargs):
+ opened.append(kwargs["continuation"])
+ try:
+ await asyncio.Event().wait()
+ yield "unreachable"
+ finally:
+ closed.append(True)
+
+ async def forbidden(*args, **kwargs):
+ raise AssertionError("The application deadline cannot select another candidate")
+ yield "unreachable"
+
+ async with _harness(
+ "chat",
+ lambda _: (200, text_events("chat", "Before. ", complete=False)),
+ max_attempts=1,
+ ) as (first, _, _):
+ raw = await delivered_candidates(
+ [first, waiting, forbidden], wire, progress_timeout=0.1
+ )
+ assert len(opened) == 1 and opened[0].text == "Before. "
+ assert closed == [True]
+ events = parse_sse_text(raw)
+ assert public_text(events, wire) == "Before. "
+ assert events[-1].event == ("error" if wire == "messages" else "response.failed")
+ if wire == "responses":
+ final = events[-1].data["response"]
+ assert final["id"] == events[0].data["response"]["id"]
+ assert (
+ "".join(
+ part["text"]
+ for item in final["output"]
+ for part in item.get("content", [])
+ )
+ == "Before. "
+ )
+ assert final["error"]["type"] == "timeout_error"
diff --git a/tests/api/test_model_fallback_tool_projection.py b/tests/api/test_model_fallback_tool_projection.py
new file mode 100644
index 00000000..1af52f5d
--- /dev/null
+++ b/tests/api/test_model_fallback_tool_projection.py
@@ -0,0 +1,176 @@
+"""A failed native tool snapshot must preserve routing and the provider error."""
+
+from copy import deepcopy
+
+import pytest
+
+from free_claude_code.api.response_streams import (
+ openai_responses_sse_streaming_response,
+)
+from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
+from free_claude_code.core.openai_responses import ResponsesToolPolicy
+from free_claude_code.providers.stream_recovery import RecoveryHoldbackBuffer
+from tests.api.test_delivered_stream_recovery import public_text, text_events
+from tests.api.test_midstream_model_fallback import delivered_candidates
+from tests.api.test_response_streams import _json_error
+from tests.core.openai_responses.test_client_tool_discovery import SEARCH
+from tests.providers.test_history_transports import _harness
+
+
[email protected](autouse=True)
+def public_responses(monkeypatch):
+ async def response(wire, body):
+ assert wire == "responses"
+ return await openai_responses_sse_streaming_response(
+ body,
+ headers={},
+ pre_start_error_response=_json_error,
+ request_id="failed-tool-projection",
+ )
+
+ monkeypatch.setattr("tests.api.test_midstream_model_fallback._response", response)
+
+
+def interrupted_search(bodies, status, *, text="", terminal="failed"):
+ events = text_events("responses", text, complete=False)
+ if not text:
+ events = events[:1]
+ response = deepcopy(text_events("responses", text)[-1]["response"])
+ if not text:
+ response["output"] = []
+ call = {
+ "type": "function_call",
+ "id": "fc_abandoned",
+ "call_id": "call_abandoned",
+ "name": bodies[-1]["tools"][0]["name"],
+ "arguments": '{"query":',
+ }
+ if status is not None:
+ call["status"] = status
+ events.extend(
+ [
+ {
+ "type": "response.output_item.added",
+ "output_index": 1,
+ "item": {**call, "status": "in_progress", "arguments": ""},
+ },
+ {
+ "type": "response.function_call_arguments.delta",
+ "output_index": 1,
+ "item_id": call["id"],
+ "delta": call["arguments"],
+ },
+ {
+ "type": f"response.{terminal}",
+ "extension": {"keep": "envelope"},
+ "response": {
+ **response,
+ "status": terminal,
+ "metadata": {"keep": "metadata"},
+ "output": [*response["output"], call],
+ "error": {
+ "code": "server_error",
+ "message": "Native failure during client search",
+ "param": None,
+ "provider_extension": {"keep": True},
+ }
+ if terminal == "failed"
+ else None,
+ },
+ },
+ ]
+ )
+ return [{**event, "sequence_number": index} for index, event in enumerate(events)]
+
+
[email protected]("release", [False, True])
[email protected]("status", [None, "completed", "incomplete"])
+async def test_failed_client_search_projection_preserves_model_fallback(
+ monkeypatch, release, status
+):
+ monkeypatch.setattr(
+ "free_claude_code.providers.stream_recovery.RecoveryHoldbackBuffer",
+ lambda: RecoveryHoldbackBuffer(
+ max_bytes=1 if release else 1_000_000, holdback_seconds=60
+ ),
+ )
+ async with (
+ _harness(
+ "responses",
+ lambda bodies: (200, interrupted_search(bodies, status)),
+ max_attempts=1,
+ ) as (first, first_bodies, native),
+ _harness(
+ "chat", lambda _: (200, text_events("chat", "Recovered")), max_attempts=1
+ ) as (second, second_bodies, _),
+ ):
+ native._tool_policy = ResponsesToolPolicy(client_tool_search=True)
+ raw = await delivered_candidates([first, second], "responses", tools=[SEARCH])
+ assert len(first_bodies) == len(second_bodies) == 1
+ events = parse_sse_text(raw)
+ assert public_text(events, "responses") == "Recovered"
+ assert events[-1].event == "response.completed"
+ assert "call_abandoned" not in raw
+
+
[email protected]("status", [None, "completed", "incomplete"])
+async def test_final_search_failure_keeps_native_error_metadata_and_valid_output(
+ monkeypatch, status
+):
+ monkeypatch.setattr(
+ "free_claude_code.providers.stream_recovery.RecoveryHoldbackBuffer",
+ lambda: RecoveryHoldbackBuffer(max_bytes=1),
+ )
+ source = []
+
+ def failed(bodies):
+ source.extend(interrupted_search(bodies, status, text="Saved text"))
+ return 200, source
+
+ async with _harness("responses", failed, max_attempts=1) as (send, bodies, native):
+ native._tool_policy = ResponsesToolPolicy(client_tool_search=True)
+ raw = await delivered_candidates([send], "responses", tools=[SEARCH])
+ assert len(bodies) == 1
+ events = parse_sse_text(raw)
+ assert public_text(events, "responses") == "Saved text"
+ final = events[-1]
+ assert final.event == "response.failed"
+ assert final.data["extension"] == source[-1]["extension"]
+ for field in ("error", "metadata", "usage"):
+ assert final.data["response"][field] == source[-1]["response"][field]
+ assert final.data["response"]["output"] == source[-1]["response"]["output"][:1]
+ assert "call_abandoned" not in raw
+
+
[email protected]("terminal", ["completed", "incomplete"])
+async def test_invalid_successful_search_snapshot_still_fails_without_fallback(
+ monkeypatch,
+ terminal,
+):
+ monkeypatch.setattr(
+ "free_claude_code.providers.stream_recovery.RecoveryHoldbackBuffer",
+ lambda: RecoveryHoldbackBuffer(max_bytes=1),
+ )
+ async with (
+ _harness(
+ "responses",
+ lambda bodies: (
+ 200,
+ interrupted_search(bodies, "completed", terminal=terminal),
+ ),
+ max_attempts=1,
+ ) as (first, first_bodies, native),
+ _harness("chat") as (second, second_bodies, _),
+ ):
+ native._tool_policy = ResponsesToolPolicy(client_tool_search=True)
+ raw = await delivered_candidates([first, second], "responses", tools=[SEARCH])
+ assert len(first_bodies) == 1 and not second_bodies
+ final = parse_sse_text(raw)[-1]
+ assert final.event == "response.failed"
+ assert (
+ "Invalid client search arguments" in final.data["response"]["error"]["message"]
+ )
+ assert "call_abandoned" not in raw
diff --git a/tests/api/test_native_anthropic.py b/tests/api/test_native_anthropic.py
index bf0b9310..3f0a92ce 100644
--- a/tests/api/test_native_anthropic.py
+++ b/tests/api/test_native_anthropic.py
@@ -144,7 +144,7 @@ def test_leading_pings_allow_exhausted_primary_to_reach_native_fallback():
assert all(wire.closed for wire in wires)
-def test_stream_failure_after_metadata_retries_same_provider_without_fallback():
+def test_stream_failure_after_metadata_exhausts_then_uses_fallback():
from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
from tests.providers.test_anthropic_messages_transport import _events, _sse
@@ -177,11 +177,15 @@ def test_stream_failure_after_metadata_retries_same_provider_without_fallback():
events = parse_sse_text(response.text)
assert [event.event for event in events] == ["error"]
assert "anthropic-req-evidence" in response.text
- assert len(requests) == 2
+ assert len(requests) == 4
assert json.loads(requests[0].content) == json.loads(requests[1].content)
- assert all(
- json.loads(request.content)["model"] == "primary" for request in requests
- )
+ assert json.loads(requests[2].content) == json.loads(requests[3].content)
+ assert [json.loads(request.content)["model"] for request in requests] == [
+ "primary",
+ "primary",
+ "backup",
+ "backup",
+ ]
@pytest.mark.parametrize("view", ["claude", "claude-desktop", "messages"])
diff --git a/tests/api/test_request_lifetime.py b/tests/api/test_request_lifetime.py
index 31023983..6c3bd17a 100644
--- a/tests/api/test_request_lifetime.py
+++ b/tests/api/test_request_lifetime.py
@@ -25,6 +25,7 @@ from free_claude_code.core.anthropic import MessagesRequest
from free_claude_code.core.anthropic.streaming import format_sse_event
from free_claude_code.core.openai_responses import OpenAIResponsesRequest
from free_claude_code.core.reasoning import ReasoningPolicy
+from free_claude_code.core.stream_recovery import ContinuationSeed
from tests.web_tools_support import StubWebToolsClient
@@ -410,6 +411,7 @@ class _ControlledProvider:
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
del input_tokens, response_model, reasoning
self.request_ids.append(request_id)
@@ -431,6 +433,7 @@ class _ControlledProvider:
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
del input_tokens, response_model, reasoning
self.request_ids.append(request_id)
diff --git a/tests/api/test_tool_call_buffer.py b/tests/api/test_tool_call_buffer.py
index 85914edd..361c24c6 100644
--- a/tests/api/test_tool_call_buffer.py
+++ b/tests/api/test_tool_call_buffer.py
@@ -322,6 +322,28 @@ async def test_completed_call_survives_later_incomplete_call_and_generated_error
assert events[-1].event == ("error" if wire == "messages" else "response.failed")
[email protected]("response_status", [None, "failed", "completed"])
+async def test_failed_snapshot_retains_only_previously_released_client_calls(
+ response_status,
+):
+ terminal = _end("responses", failed=True, output=[_item(0), _item(1)])[0]
+ terminal[1]["response"]["status"] = response_status
+ frames = _frames("responses", [_start("responses"), *_call("responses"), terminal])
+
+ async def body():
+ for frame in frames:
+ yield frame
+
+ response = await _response("responses", body())
+ result = "".join([str(chunk) async for chunk in response.body_iterator])
+ await response.aclose()
+ final = parse_sse_text(result)[-1]
+ assert final.event == "response.failed"
+ assert final.data["response"]["output"] == [_item(0)]
+ assert "call_1" not in result
+
+
@pytest.mark.asyncio
@pytest.mark.parametrize("wire", ["messages", "responses"])
async def test_unfinished_call_is_discarded_at_eof(wire):
diff --git a/tests/api/test_web_server_tools.py b/tests/api/test_web_server_tools.py
index 65b5510c..621dbc1a 100644
--- a/tests/api/test_web_server_tools.py
+++ b/tests/api/test_web_server_tools.py
@@ -57,6 +57,7 @@ from free_claude_code.core.openai_responses.provider_input import (
build_responses_provider_request,
)
from free_claude_code.core.reasoning import ReasoningPolicy
+from free_claude_code.core.stream_recovery import ContinuationSeed
from free_claude_code.core.version import package_version
from free_claude_code.core.web_tools import WebFetchResult, WebSearchResult
from free_claude_code.messaging.event_parser import parse_cli_event
@@ -185,6 +186,7 @@ class ScriptedSelectionProvider:
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
raise AssertionError("Web-search selection received a Responses request")
yield ""
@@ -199,6 +201,7 @@ class ScriptedSelectionProvider:
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
self.requests.append(request)
self.stream_kwargs.append(
diff --git a/tests/application/test_execution.py b/tests/application/test_execution.py
index 570662df..66b42934 100644
--- a/tests/application/test_execution.py
+++ b/tests/application/test_execution.py
@@ -22,6 +22,7 @@ from free_claude_code.core.async_iterators import AsyncCloseable
from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.core.openai_responses import OpenAIResponsesRequest
from free_claude_code.core.reasoning import ReasoningCapability, ReasoningPolicy
+from free_claude_code.core.stream_recovery import ContinuationSeed
class FakeProvider:
@@ -36,6 +37,7 @@ class FakeProvider:
request_id: str,
response_model: str,
request_headers: Mapping[str, str] | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
raise AssertionError("Compatibility test provider received a native request")
@@ -49,6 +51,7 @@ class FakeProvider:
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
self._record_stream_call(
request,
@@ -72,6 +75,7 @@ class FakeProvider:
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
raise AssertionError("Messages test provider received a Responses request")
yield ""
@@ -111,6 +115,7 @@ class ResponsesFakeProvider:
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
raise AssertionError("Responses test provider received a Messages request")
yield ""
@@ -125,6 +130,7 @@ class ResponsesFakeProvider:
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
self.stream_calls.append(
{
@@ -177,6 +183,7 @@ class ControlledProvider(FakeProvider):
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
self._record_stream_call(
request,
@@ -244,6 +251,7 @@ class FailingStreamConstructionProvider(FakeProvider):
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
raise RuntimeError("stream construction failed")
@@ -263,6 +271,7 @@ class ExecutionFailureStreamConstructionProvider(FakeProvider):
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
del request, input_tokens, request_id, response_model, reasoning
raise self._failure
@@ -292,6 +301,7 @@ class CloseControlledProvider(FakeProvider):
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
self._record_stream_call(
request,
@@ -615,6 +625,8 @@ async def test_retryable_preframe_failure_selects_fallback_after_closing_primary
"failure_kind": "overloaded",
"status_code": 529,
"provider_retryable": True,
+ "recovery_action": "restart",
+ "recovery_reason": "no_candidate_output",
"generation_id": 7,
}
selected = next(
@@ -906,6 +918,7 @@ async def test_candidate_requests_are_isolated_from_provider_mutation() -> None:
reasoning: ReasoningPolicy,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
request.messages[0].content = "mutated"
async for chunk in super().stream_messages(
diff --git a/tests/core/test_failures.py b/tests/core/test_failures.py
index 00a4a580..d0898ce7 100644
--- a/tests/core/test_failures.py
+++ b/tests/core/test_failures.py
@@ -1,6 +1,6 @@
"""Canonical, protocol-neutral execution failure contracts."""
-from dataclasses import FrozenInstanceError, fields, is_dataclass
+from dataclasses import FrozenInstanceError, fields, is_dataclass, replace
import pytest
@@ -9,6 +9,11 @@ from free_claude_code.core.failures import (
FailureKind,
find_execution_failure,
)
+from free_claude_code.core.json_types import JsonObject
+from free_claude_code.core.stream_recovery import (
+ SourceRecoverySnapshot,
+ StreamFailureContext,
+)
def test_failure_kind_has_only_protocol_neutral_semantics() -> None:
@@ -50,12 +55,14 @@ def test_execution_failure_is_the_direct_frozen_slotted_exception() -> None:
"status_code",
"message",
"retryable",
+ "stream_context",
)
assert ExecutionFailure.__slots__ == (
"kind",
"status_code",
"message",
"retryable",
+ "stream_context",
)
assert str(failure) == "Provider rate limit reached."
assert failure.args == ("Provider rate limit reached.",)
@@ -112,3 +119,27 @@ def test_find_execution_failure_leaves_unrelated_groups_unclassified() -> None:
)
assert find_execution_failure(grouped) is None
+
+
+def test_failure_context_survives_replacement_and_group_lookup_without_aliasing() -> (
+ None
+):
+ error: JsonObject = {"param": None}
+ payload: JsonObject = {"type": "response.failed", "response": {"error": error}}
+ context = StreamFailureContext(
+ SourceRecoverySnapshot(unsafe_reason="native_content", can_handoff=False),
+ payload,
+ )
+ original = ExecutionFailure(FailureKind.UPSTREAM, 502, "cut", True, context)
+ changed = replace(original, message="upstream cut")
+ found = find_execution_failure(ExceptionGroup("wrapped", [changed]))
+ assert found is changed and found.stream_context is context
+ error["param"] = "changed"
+ assert context.responses_failure_payload == {
+ "type": "response.failed",
+ "response": {"error": {"param": None}},
+ }
+ assert changed.kind is FailureKind.UPSTREAM and changed.status_code == 502
+ assert str(original) == "cut" and str(changed) == "upstream cut"
+ with pytest.raises(FrozenInstanceError):
+ changed.stream_context = None
diff --git a/tests/providers/test_custom_provider.py b/tests/providers/test_custom_provider.py
index 78ba6c94..abebde99 100644
--- a/tests/providers/test_custom_provider.py
+++ b/tests/providers/test_custom_provider.py
@@ -13,6 +13,7 @@ from free_claude_code.core.anthropic import MessagesRequest
from free_claude_code.core.model_capabilities import ModelInputModality
from free_claude_code.core.openai_responses import OpenAIResponsesRequest
from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
+from free_claude_code.core.stream_recovery import ContinuationSeed
from free_claude_code.providers.admission import ProviderAdmissionController
from free_claude_code.providers.custom import CustomProvider
from free_claude_code.providers.runtime.config import build_custom_provider_config
@@ -393,8 +394,9 @@ def completion(api_format):
)
@pytest.mark.parametrize("ingress", ["messages", "responses"])
@pytest.mark.parametrize("key", [None, "custom-key"])
[email protected]("seeded", [False, True])
async def test_six_paths_use_exact_endpoint_and_credentials(
- api_format, path, ingress, key, monkeypatch
+ api_format, path, ingress, key, seeded, monkeypatch
):
monkeypatch.setenv("OPENAI_API_KEY", "unrelated-key")
monkeypatch.setenv("OPENAI_ORG_ID", "unrelated-org")
@@ -417,18 +419,25 @@ async def test_six_paths_use_exact_endpoint_and_credentials(
)
try:
policy = ReasoningPolicy.on(effort=ReasoningEffort.MEDIUM)
+ continuation = (
+ ContinuationSeed("Prefix text", "Prior reasoning") if seeded else None
+ )
if ingress == "messages":
request = MessagesRequest(
model="m",
max_tokens=100,
messages=[{"role": "user", "content": "Hello"}],
)
- stream = instance.stream_messages(request, reasoning=policy)
+ stream = instance.stream_messages(
+ request, reasoning=policy, continuation=continuation
+ )
else:
request = OpenAIResponsesRequest(
model="m", input="Hello", reasoning={"effort": "medium"}
)
- stream = instance.stream_responses(request, reasoning=policy)
+ stream = instance.stream_responses(
+ request, reasoning=policy, continuation=continuation
+ )
output = "".join([chunk async for chunk in stream])
assert "Hello" in output
assert len(requests) == 1
@@ -443,6 +452,11 @@ async def test_six_paths_use_exact_endpoint_and_credentials(
assert "openai-organization" not in sent.headers
assert "openai-project" not in sent.headers
body = json.loads(sent.content)
+ if seeded:
+ history = body.get("messages", body.get("input"))
+ assert "Prefix text" in str(history[-2])
+ assert "Prior reasoning" in str(history[-1])
+ assert "Prefix text" not in str(request.model_dump())
if ingress == "responses" and api_format == "openai_responses":
assert body["reasoning"]["effort"] == "medium"
else:
diff --git a/tests/providers/test_github_copilot_provider.py b/tests/providers/test_github_copilot_provider.py
index 6eff5591..c274d7a6 100644
--- a/tests/providers/test_github_copilot_provider.py
+++ b/tests/providers/test_github_copilot_provider.py
@@ -35,6 +35,7 @@ from free_claude_code.core.reasoning import (
ReasoningEffort,
ReasoningPolicy,
)
+from free_claude_code.core.stream_recovery import ContinuationSeed
from free_claude_code.providers.anthropic_messages.request_policy import (
MessagesModelCapabilities,
)
@@ -69,8 +70,9 @@ from tests.providers.test_openai_responses_transport import (
@pytest.mark.asyncio
@pytest.mark.parametrize("egress", list(CopilotEgress))
@pytest.mark.parametrize("responses", [False, True])
[email protected]("seeded", [False, True])
async def test_conversion_runs_once_under_current_account_lease(
- tmp_path, egress, responses
+ tmp_path, egress, responses, seeded
):
harness = Harness(tmp_path, egress)
cls, name = {
@@ -101,8 +103,20 @@ async def test_conversion_runs_once_under_current_account_lease(
try:
with patch.object(cls, name, autospec=True, side_effect=build) as conversion:
- assert "ok" in await collect(harness.stream(responses))
+ assert "ok" in await collect(
+ harness.stream(
+ responses,
+ continuation=ContinuationSeed("Prefix text", "Prior reasoning")
+ if seeded
+ else None,
+ )
+ )
assert conversion.call_count == len(harness.seen) == 1
+ if seeded:
+ body = json.loads(harness.seen[0].content)
+ history = body.get("messages", body.get("input"))
+ assert "Prefix text" in str(history[-2])
+ assert "Prior reasoning" in str(history[-1])
assert harness.provider._active == 0
finally:
await harness.close()
@@ -283,14 +297,21 @@ class Harness:
*,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
history: bool = False,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
request = _request(responses, self.runtime.name, history=history)
if isinstance(request, MessagesRequest):
return self.provider.stream_messages(
- request, response_model="public-alias", reasoning=reasoning
+ request,
+ response_model="public-alias",
+ reasoning=reasoning,
+ continuation=continuation,
)
return self.provider.stream_responses(
- request, response_model="public-alias", reasoning=reasoning
+ request,
+ response_model="public-alias",
+ reasoning=reasoning,
+ continuation=continuation,
)
async def close(self) -> None:
diff --git a/tests/providers/test_history_transports.py b/tests/providers/test_history_transports.py
index 22b4b919..c5a18df4 100644
--- a/tests/providers/test_history_transports.py
+++ b/tests/providers/test_history_transports.py
@@ -186,7 +186,7 @@ async def _harness(
)
extras = {}
- def stream(wire, history, *, tools=None):
+ def stream(wire, history, *, tools=None, model="requested", continuation=None):
options: dict[str, Any] = dict(
input_tokens=0,
request_id="history-test",
@@ -197,16 +197,18 @@ async def _harness(
if protocol == "messages":
options.pop("input_tokens")
options["reasoning"] = ReasoningPolicy.provider_default()
+ if continuation is not None:
+ options["continuation"] = continuation
if wire == "responses":
return provider.stream_responses(
OpenAIResponsesRequest.model_validate(
- {"model": "requested", "input": history, "tools": tools}
+ {"model": model, "input": history, "tools": tools}
),
**options,
)
return provider.stream_messages(
MessagesRequest.model_validate(
- {"model": "requested", "messages": history, "tools": tools}
+ {"model": model, "messages": history, "tools": tools}
),
**options,
)
diff --git a/tests/providers/test_lmstudio.py b/tests/providers/test_lmstudio.py
index cbdf16ce..9184cf9d 100644
--- a/tests/providers/test_lmstudio.py
+++ b/tests/providers/test_lmstudio.py
@@ -21,6 +21,7 @@ from free_claude_code.core.openai_responses import (
estimate_responses_input_tokens,
)
from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
+from free_claude_code.core.stream_recovery import ContinuationSeed
from free_claude_code.providers.admission import ProviderAdmissionController
from free_claude_code.providers.lmstudio import LMStudioProvider
from tests.application.test_execution import (
@@ -377,6 +378,43 @@ async def test_context_rejection_never_starts_admission_or_generation(
generation.assert_not_called()
[email protected]("wire", ["messages", "responses"])
+async def test_continuation_prefix_counts_before_context_admission(
+ lmstudio_provider, wire
+):
+ request = (
+ make_request()
+ if wire == "messages"
+ else OpenAIResponsesRequest(model="model", input="hello")
+ )
+ original = request.model_dump(mode="json")
+ with (
+ patch.object(
+ lmstudio_provider,
+ "_loaded_context_length",
+ new=AsyncMock(return_value=2000),
+ ),
+ patch.object(
+ lmstudio_provider._chat._admission, "start_execution"
+ ) as admission,
+ patch.object(
+ lmstudio_provider._client.chat.completions, "create"
+ ) as generation,
+ pytest.raises(ExecutionFailure) as error,
+ ):
+ await anext(
+ getattr(lmstudio_provider, f"stream_{wire}")(
+ request,
+ continuation=ContinuationSeed("large " * 10000, "consider this"),
+ )
+ )
+ assert error.value.kind is FailureKind.CONTEXT_WINDOW_EXCEEDED
+ assert request.model_dump(mode="json") == original
+ admission.assert_not_called()
+ generation.assert_not_called()
+
+
@pytest.mark.asyncio
@pytest.mark.parametrize("wire", ["messages", "responses"])
async def test_primary_context_validation_counts_toward_progress_timeout(
diff --git a/tests/providers/test_model_discovery.py b/tests/providers/test_model_discovery.py
index 087d47c0..92f3d792 100644
--- a/tests/providers/test_model_discovery.py
+++ b/tests/providers/test_model_discovery.py
@@ -16,6 +16,7 @@ from free_claude_code.config.provider_catalog import (
)
from free_claude_code.config.settings import Settings
from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
+from free_claude_code.core.stream_recovery import ContinuationSeed
from free_claude_code.providers.base import BaseProvider
from free_claude_code.providers.deepseek import DeepSeekProvider
from free_claude_code.providers.model_listing import ModelListResponseError
@@ -382,6 +383,7 @@ class FakeProvider(BaseProvider):
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
if False:
yield ""
@@ -396,6 +398,7 @@ class FakeProvider(BaseProvider):
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
if False:
yield ""
diff --git a/tests/providers/test_opencode.py b/tests/providers/test_opencode.py
index a6dae670..443d361d 100644
--- a/tests/providers/test_opencode.py
+++ b/tests/providers/test_opencode.py
@@ -46,6 +46,9 @@ from free_claude_code.providers.opencode.catalog import (
OpenCodeUpstreamTransport,
parse_open_code_catalog,
)
+from free_claude_code.providers.stream_recovery import RecoveryHoldbackBuffer
+from tests.api.test_response_streams import _serve
+from tests.api.test_tool_call_buffer import _response
from tests.providers.support import (
capture_openai_chat_wire_body,
immediate_admission,
@@ -1047,6 +1050,7 @@ async def test_discovered_custom_tools_survive_sdk_calls_and_replay(
),
)
@pytest.mark.asyncio
[email protected]("midstream", [False, True])
async def test_candidate_fallback_resolves_each_opencode_transport(
wire_api: str,
primary_model: str,
@@ -1054,9 +1058,28 @@ async def test_candidate_fallback_resolves_each_opencode_transport(
failed_path: str,
fallback_path: str,
fallback_text: str,
+ midstream: bool,
+ monkeypatch,
) -> None:
+ from tests.api.test_delivered_stream_recovery import text_events
+
+ monkeypatch.setattr(
+ "free_claude_code.providers.stream_recovery.RecoveryHoldbackBuffer",
+ lambda: RecoveryHoldbackBuffer(max_bytes=1),
+ )
+
def generation_response(request: httpx2.Request) -> httpx2.Response:
if request.url.path == failed_path:
+ if midstream:
+ protocol = "responses" if failed_path.endswith("/responses") else "chat"
+ return httpx2.Response(
+ 200,
+ headers={"content-type": "text/event-stream"},
+ text="".join(
+ f"data: {json.dumps(event)}\n\n"
+ for event in text_events(protocol, "Before. ", complete=False)
+ ),
+ )
return httpx2.Response(503, json={"error": "temporary overload"})
if request.url.path == "/zen/v1/responses":
body = _responses_event_stream(fallback_text)
@@ -1120,7 +1143,12 @@ async def test_candidate_fallback_resolves_each_opencode_transport(
raw_log_payload=dict,
request_id="req_opencode_cross_transport_messages",
)
- body = "".join([chunk async for chunk in stream])
+ if midstream:
+ response = await _response(wire_api, stream)
+ messages = await _serve(response)
+ body = b"".join(message.get("body", b"") for message in messages).decode()
+ else:
+ body = "".join([chunk async for chunk in stream])
finally:
await provider.cleanup()
@@ -1131,6 +1159,9 @@ async def test_candidate_fallback_resolves_each_opencode_transport(
fallback_path,
]
payloads = [json.loads(request.content) for request in generation_requests]
+ if midstream:
+ history = payloads[-1].get("messages", payloads[-1].get("input"))
+ assert "Before. " in str(history[-2])
assert [payload["model"] for payload in payloads] == [
upstream_id(primary_model),
upstream_id(primary_model),
@@ -1141,15 +1172,18 @@ async def test_candidate_fallback_resolves_each_opencode_transport(
assert [event.event for event in events].count("response.created") == 1
assert [event.event for event in events].count("response.completed") == 1
assert events[-1].data["response"]["model"] == "public-model"
- assert [
- event.data["delta"]
- for event in events
- if event.event == "response.output_text.delta"
- ] == [fallback_text]
+ assert (
+ "".join(
+ event.data["delta"]
+ for event in events
+ if event.event == "response.output_text.delta"
+ )
+ == ("Before. " if midstream else "") + fallback_text
+ )
else:
assert_anthropic_stream_contract(events)
assert events[0].data["message"]["model"] == "public-model"
- assert text_content(events) == fallback_text
+ assert text_content(events) == ("Before. " if midstream else "") + fallback_text
assert "temporary overload" not in body
diff --git a/tests/runtime/test_application_runtime.py b/tests/runtime/test_application_runtime.py
index 7106564b..509ec0e0 100644
--- a/tests/runtime/test_application_runtime.py
+++ b/tests/runtime/test_application_runtime.py
@@ -18,6 +18,7 @@ from free_claude_code.config.settings import Settings
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.openai_responses import OpenAIResponsesRequest
from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
+from free_claude_code.core.stream_recovery import ContinuationSeed
from free_claude_code.messaging.command_context import StopOutcome
from free_claude_code.messaging.platforms.ports import (
InboundMessageHandler,
@@ -80,6 +81,7 @@ class AdminModelProvider(BaseProvider):
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
if False:
yield ""
@@ -94,6 +96,7 @@ class AdminModelProvider(BaseProvider):
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
request_headers: Mapping[str, str] | None = None,
model_info: ProviderModelInfo | None = None,
+ continuation: ContinuationSeed | None = None,
) -> AsyncIterator[str]:
if False:
yield ""