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
Bound stalled provider execution below harness timeouts (#1424)
Ali Khokhar323dbd8ea8a7
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.mdindex f2f9d49e..c5fa87b2 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -418,7 +418,16 @@ consumer-owned `ProviderPort`, synchronously preflights the upstream request,emits trace events, counts input tokens, and returns an Anthropic SSE iterator.It receives only a provider resolver and the few scalar collaborators it needs;it does not depend on FastAPI, provider implementations, or the full settings-object.+object. The executor also owns FCC's provider-progress deadline: every wait for+the next non-empty provider chunk is limited to 240 seconds, leaving one minute+below the five-minute idle watchdog shared by the first-party Claude, Codex, and+Pi harnesses. Admission, retries, backoff, and recovery before a chunk all consume+that same wait; a non-empty emitted chunk renews the next window. The timeout+context ends before the executor yields, so downstream response backpressure is+not mistaken for stalled provider work and cannot receive cancellation from the+generator's timer. Expiry becomes a protocol-neutral, non-retryable 504+`ExecutionFailure`; cancellation and provider-originated timeouts retain their+existing meanings.[api/response_streams.py](src/free_claude_code/api/response_streams.py) owns public streaming egresscommit timing. It waits for the first protocol chunk before returning asuccessful FCC-owned `StreamingResponse`. Its explicit replay iterator owns the@@ -955,7 +964,11 @@ nested retry counters. Deterministic corrections retry immediately; transientfailures use exponential backoff with jitter and honor `Retry-After` as aminimum. When partial output exists, the last available attempt is reserved forcontinuation or repair instead of replaying the full request again. Completed-tool calls can be salvaged without an upstream attempt.+tool calls can be salvaged without an upstream attempt. The application-owned+progress window is an outer no-progress bound, not another retry counter: opening+a new attempt never resets it, while a real emitted provider chunk does. Fast+transient failures can therefore still use all five attempts, but repeated+fully-stalled operations cannot outlive the downstream harness.For streams, upstream acceptance is the first received chunk. Retryable failurebefore that point participates in provider-wide coordinated recovery. Failurediff --git a/pyproject.toml b/pyproject.tomlindex fbb31204..be0cf876 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "free-claude-code"-version = "5.1.0"+version = "5.1.1"description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"readme = "README.md"requires-python = ">=3.14.0"diff --git a/src/free_claude_code/application/execution.py b/src/free_claude_code/application/execution.pyindex aaf8c07f..e601273a 100644--- a/src/free_claude_code/application/execution.py+++ b/src/free_claude_code/application/execution.py@@ -1,5 +1,7 @@"""Provider execution shared by inbound API adapters."""+import asyncio+import mathimport sysfrom collections.abc import AsyncIterator, Callablefrom typing import Literal@@ -13,6 +15,7 @@ from free_claude_code.core.anthropic import (anthropic_request_snapshot,get_token_count,)+from free_claude_code.core.failures import ExecutionFailure, FailureKindfrom free_claude_code.core.trace import (close_stream_input,trace_event,@@ -27,6 +30,7 @@ TokenCounter = Callable[int,]WireApi = Literal["messages", "responses"]+PROVIDER_PROGRESS_TIMEOUT_SECONDS = 240.0class ProviderExecutor:@@ -39,11 +43,40 @@ class ProviderExecutor:token_counter: TokenCounter = get_token_count,generation_id: int | None = None,log_raw_payloads: bool = False,+ progress_timeout_seconds: float = PROVIDER_PROGRESS_TIMEOUT_SECONDS,) -> None:+ if not math.isfinite(progress_timeout_seconds) or progress_timeout_seconds <= 0:+ raise ValueError("progress_timeout_seconds must be finite and positive")self._provider_resolver = provider_resolverself._token_counter = token_counterself._generation_id = generation_idself._log_raw_payloads = log_raw_payloads+ self._progress_timeout_seconds = float(progress_timeout_seconds)++ def _progress_timeout_failure(+ self,+ *,+ request_id: str,+ provider_id: str,+ ) -> ExecutionFailure:+ trace_event(+ stage="execution",+ event="free_claude_code.provider.progress_timeout",+ source="application",+ request_id=request_id,+ provider_id=provider_id,+ timeout_seconds=self._progress_timeout_seconds,+ )+ timeout_text = f"{self._progress_timeout_seconds:g}"+ return ExecutionFailure(+ kind=FailureKind.TIMEOUT,+ status_code=504,+ message=(+ f"Provider execution made no progress for {timeout_text} seconds.\n\n"+ f"Request ID: {request_id}"+ ),+ retryable=False,+ )def stream(self,@@ -119,8 +152,32 @@ class ProviderExecutor:response_model=gateway_model,reasoning=routed.reasoning,)- async for chunk in provider_stream:+ loop = asyncio.get_running_loop()+ progress_deadline = loop.time() + self._progress_timeout_seconds+ while True:+ if loop.time() >= progress_deadline:+ raise self._progress_timeout_failure(+ request_id=request_id,+ provider_id=routed.resolved.provider_id,+ )+ progress_timeout = asyncio.timeout_at(progress_deadline)+ try:+ async with progress_timeout:+ chunk = await anext(provider_stream)+ except StopAsyncIteration:+ break+ except TimeoutError as exc:+ if not progress_timeout.expired():+ raise+ raise self._progress_timeout_failure(+ request_id=request_id,+ provider_id=routed.resolved.provider_id,+ ) from exc+ if not chunk:+ await asyncio.sleep(0)+ continueyield chunk+ progress_deadline = loop.time() + self._progress_timeout_secondsfinally:if provider_stream is not None:await close_stream_input(diff --git a/tests/api/test_execution_failure_contract.py b/tests/api/test_execution_failure_contract.pyindex f502b672..e3d422c1 100644--- a/tests/api/test_execution_failure_contract.py+++ b/tests/api/test_execution_failure_contract.py@@ -140,6 +140,16 @@ def _grouped_rate_limit_provider(chunks: list[str]) -> CanonicalFailureProvider:)+def _timeout_provider(chunks: list[str]) -> CanonicalFailureProvider:+ return CanonicalFailureProvider(+ chunks,+ kind=FailureKind.TIMEOUT,+ status_code=504,+ message="Provider execution made no progress for 240 seconds.",+ retryable=False,+ )++@pytest.mark.parametrize(("path", "payload", "expected_type"),[@@ -503,3 +513,110 @@ def test_messages_stream_false_discards_partial_content_on_execution_failure() -"message": f"upstream is busy\n\nRequest ID: {request_id}",}assert _PARTIAL_CONTENT not in response.text+++ ("path", "payload"),+ [+ ("/v1/messages", _messages_payload(stream=True)),+ ("/v1/responses", _responses_payload()),+ ],+)+def test_pre_start_progress_timeout_is_terminal_504(+ path: str,+ payload: dict[str, object],+) -> None:+ provider = _timeout_provider([])+ resolver_patch, client = _client_for(provider)++ with (+ resolver_patch,+ patch("free_claude_code.api.response_streams.trace_event") as trace_mock,+ client,+ ):+ response = client.post(path, json=payload)++ request_id = response.headers["request-id"]+ assert response.status_code == 504+ assert response.headers["content-type"].startswith("application/json")+ assert response.headers["x-should-retry"] == "false"+ assert response.json()["error"] == {+ "type": "timeout_error",+ "message": (+ "Provider execution made no progress for 240 seconds.\n\n"+ f"Request ID: {request_id}"+ ),+ **({} if path == "/v1/messages" else {"param": None, "code": None}),+ }+ if path == "/v1/messages":+ assert response.json()["request_id"] == request_id+ assert "x-request-id" not in response.headers+ else:+ assert response.headers["x-request-id"] == request_id+ trace = _terminal_trace(trace_mock)+ assert trace["status_code"] == 504+ assert trace["error_type"] == "timeout_error"+ assert trace["failure_kind"] == "timeout"+ assert trace["provider_retryable"] is False+ assert trace["client_should_retry"] is False++[email protected]("path", ["/v1/messages", "/v1/responses"])+def test_post_start_progress_timeout_is_terminal_protocol_event(path: str) -> None:+ provider = _timeout_provider(_partial_anthropic_stream(close_block=True))+ payload = (+ _messages_payload(stream=True)+ if path == "/v1/messages"+ else _responses_payload()+ )+ resolver_patch, client = _client_for(provider)++ with (+ resolver_patch,+ patch("free_claude_code.api.response_streams.trace_event") as trace_mock,+ client,+ ):+ response = client.post(path, json=payload)++ request_id = response.headers["request-id"]+ events = parse_sse_text(response.text)+ assert response.status_code == 200+ assert "x-should-retry" not in response.headers+ if path == "/v1/messages":+ assert events[-1].event == "error"+ error = events[-1].data["error"]+ assert "message_stop" not in response.text+ else:+ assert events[0].event == "response.created"+ assert events[-1].event == "response.failed"+ assert events[-1].data["response"]["id"] == events[0].data["response"]["id"]+ error = events[-1].data["response"]["error"]+ assert error["type"] == "timeout_error"+ assert error["message"] == (+ "Provider execution made no progress for 240 seconds.\n\n"+ f"Request ID: {request_id}"+ )+ trace = _terminal_trace(trace_mock)+ assert trace["failure_kind"] == "timeout"+ assert trace["provider_retryable"] is False+ assert trace["client_should_retry"] is False+++def test_stream_false_progress_timeout_discards_partial_content() -> None:+ provider = _timeout_provider(_partial_anthropic_stream(close_block=False))+ resolver_patch, client = _client_for(provider)++ with resolver_patch, client:+ response = client.post("/v1/messages", json=_messages_payload(stream=False))++ request_id = response.headers["request-id"]+ assert response.status_code == 504+ assert response.headers["x-should-retry"] == "false"+ assert response.json()["error"] == {+ "type": "timeout_error",+ "message": (+ "Provider execution made no progress for 240 seconds.\n\n"+ f"Request ID: {request_id}"+ ),+ }+ assert _PARTIAL_CONTENT not in response.textdiff --git a/tests/application/test_execution.py b/tests/application/test_execution.pyindex d0491ffa..307c9150 100644--- a/tests/application/test_execution.py+++ b/tests/application/test_execution.py@@ -1,7 +1,8 @@"""Application-owned provider execution contracts."""+import asynciofrom collections.abc import AsyncIterator-from unittest.mock import MagicMock+from unittest.mock import MagicMock, patchimport pytest@@ -10,6 +11,7 @@ from free_claude_code.application.routing import ResolvedModel, RoutedMessagesRefrom free_claude_code.config.reasoning import ReasoningPreferencefrom free_claude_code.core.anthropic.models import Message, MessagesRequestfrom free_claude_code.core.async_iterators import AsyncCloseable+from free_claude_code.core.failures import ExecutionFailure, FailureKindfrom free_claude_code.core.reasoning import ReasoningPolicy@@ -36,6 +38,27 @@ class FakeProvider:response_model: str | None = None,reasoning: ReasoningPolicy,) -> AsyncIterator[str]:+ self._record_stream_call(+ request,+ input_tokens=input_tokens,+ request_id=request_id,+ response_model=response_model,+ reasoning=reasoning,+ )+ try:+ yield "event: message_stop\ndata: {}\n\n"+ finally:+ self.stream_close_calls += 1++ def _record_stream_call(+ self,+ request: MessagesRequest,+ *,+ input_tokens: int,+ request_id: str | None,+ response_model: str | None,+ reasoning: ReasoningPolicy,+ ) -> None:self.stream_calls.append({"request": request,@@ -45,8 +68,55 @@ class FakeProvider:"reasoning": reasoning,})+++class WaitStep:+ def __init__(self) -> None:+ self.started = asyncio.Event()+ self.release = asyncio.Event()+++class EmptyForever:+ pass+++EMPTY_FOREVER = EmptyForever()+type StreamStep = str | WaitStep | EmptyForever | BaseException+++class ControlledProvider(FakeProvider):+ def __init__(self, steps: list[StreamStep]) -> None:+ super().__init__()+ self._steps = steps++ async def stream_response(+ self,+ request: MessagesRequest,+ input_tokens: int = 0,+ *,+ request_id: str | None = None,+ response_model: str | None = None,+ reasoning: ReasoningPolicy,+ ) -> AsyncIterator[str]:+ self._record_stream_call(+ request,+ input_tokens=input_tokens,+ request_id=request_id,+ response_model=response_model,+ reasoning=reasoning,+ )try:- yield "event: message_stop\ndata: {}\n\n"+ for step in self._steps:+ if isinstance(step, str):+ yield step+ elif isinstance(step, WaitStep):+ step.started.set()+ await step.release.wait()+ elif isinstance(step, EmptyForever):+ while True:+ yield ""+ else:+ raise stepfinally:self.stream_close_calls += 1@@ -92,6 +162,26 @@ def _routed_request() -> RoutedMessagesRequest:)+def _executor_stream(+ provider: FakeProvider,+ *,+ timeout_seconds: float,+ request_id: str,+) -> AsyncIterator[str]:+ executor = ProviderExecutor(+ lambda _provider_id: provider,+ token_counter=lambda _messages, _system, _tools: 17,+ progress_timeout_seconds=timeout_seconds,+ )+ return executor.stream(+ _routed_request(),+ wire_api="messages",+ raw_log_label="FULL_PAYLOAD",+ raw_log_payload={},+ request_id=request_id,+ )++@pytest.mark.asyncioasync def test_executor_uses_structural_provider_port_and_preflights_eagerly() -> None:provider = FakeProvider()@@ -186,3 +276,131 @@ def test_executor_preflight_failure_stays_before_token_count_and_stream() -> Nontoken_counter.assert_not_called()assert provider.stream_calls == []+++ "timeout_seconds",+ [0.0, -1.0, float("inf"), float("nan")],+)+def test_executor_rejects_invalid_progress_timeout(timeout_seconds: float) -> None:+ with pytest.raises(ValueError, match="finite and positive"):+ ProviderExecutor(+ lambda _provider_id: FakeProvider(),+ progress_timeout_seconds=timeout_seconds,+ )+++async def test_progress_timeout_before_first_chunk_is_canonical_and_correlated() -> (+ None+):+ provider = ControlledProvider([WaitStep()])+ request_id = "req_progress_timeout"++ with patch("free_claude_code.application.execution.trace_event") as trace_mock:+ stream = _executor_stream(+ provider,+ timeout_seconds=0.02,+ request_id=request_id,+ )+ with pytest.raises(ExecutionFailure) as exc_info:+ await anext(stream)++ failure = exc_info.value+ assert failure.kind == FailureKind.TIMEOUT+ assert failure.status_code == 504+ assert failure.retryable is False+ assert failure.message == (+ "Provider execution made no progress for 0.02 seconds.\n\n"+ f"Request ID: {request_id}"+ )+ assert provider.stream_close_calls == 1+ timeout_traces = [+ call.kwargs+ for call in trace_mock.call_args_list+ if call.kwargs.get("event") == "free_claude_code.provider.progress_timeout"+ ]+ assert timeout_traces == [+ {+ "stage": "execution",+ "event": "free_claude_code.provider.progress_timeout",+ "source": "application",+ "request_id": request_id,+ "provider_id": "provider",+ "timeout_seconds": 0.02,+ }+ ]+++async def test_progress_timeout_renews_after_output_without_crossing_yield() -> None:+ second_wait = WaitStep()+ third_wait = WaitStep()+ provider = ControlledProvider(["first", second_wait, "second", third_wait, "third"])+ stream = _executor_stream(+ provider,+ timeout_seconds=0.02,+ request_id="req_progress_renewal",+ )++ assert await anext(stream) == "first"+ await asyncio.sleep(0.05)+ second_wait.release.set()+ assert await anext(stream) == "second"++ with pytest.raises(ExecutionFailure) as exc_info:+ await anext(stream)++ assert third_wait.started.is_set()+ assert exc_info.value.kind == FailureKind.TIMEOUT+ assert provider.stream_close_calls == 1+++async def test_empty_chunks_do_not_renew_provider_progress() -> None:+ provider = ControlledProvider([EMPTY_FOREVER])+ stream = _executor_stream(+ provider,+ timeout_seconds=0.02,+ request_id="req_empty_progress",+ )++ with pytest.raises(ExecutionFailure) as exc_info:+ await anext(stream)++ assert exc_info.value.kind == FailureKind.TIMEOUT+ assert provider.stream_close_calls == 1+++async def test_provider_owned_timeout_is_not_reclassified() -> None:+ provider = ControlledProvider([TimeoutError("provider-owned timeout")])+ stream = _executor_stream(+ provider,+ timeout_seconds=1.0,+ request_id="req_provider_timeout",+ )++ with pytest.raises(TimeoutError, match="provider-owned timeout"):+ await anext(stream)++ assert provider.stream_close_calls == 1+++async def test_cancelling_progress_wait_remains_cancellation() -> None:+ wait = WaitStep()+ provider = ControlledProvider([wait])+ stream = _executor_stream(+ provider,+ timeout_seconds=1.0,+ request_id="req_cancelled_progress",+ )+ task = asyncio.ensure_future(anext(stream))+ await wait.started.wait()++ task.cancel()+ with pytest.raises(asyncio.CancelledError):+ await task++ assert provider.stream_close_calls == 1diff --git a/uv.lock b/uv.lockindex d1a6e520..2854a387 100644--- a/uv.lock+++ b/uv.lock@@ -620,7 +620,7 @@ wheels = [[[package]]name = "free-claude-code"-version = "5.1.0"+version = "5.1.1"source = { editable = "." }dependencies = [{ name = "aiohttp" },