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

Bound stalled provider execution below harness timeouts (#1424)

Ali Khokhar323dbd8ea8a7
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 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 egress
commit timing. It waits for the first protocol chunk before returning a
successful FCC-owned `StreamingResponse`. Its explicit replay iterator owns the
@@ -955,7 +964,11 @@ nested retry counters. Deterministic corrections retry immediately; transient
failures use exponential backoff with jitter and honor `Retry-After` as a
minimum. When partial output exists, the last available attempt is reserved for
continuation 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 failure
before that point participates in provider-wide coordinated recovery. Failure
diff --git a/pyproject.toml b/pyproject.toml
index 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.py
index 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 math
import sys
from collections.abc import AsyncIterator, Callable
from 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, FailureKind
from 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.0
class 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_resolver
self._token_counter = token_counter
self._generation_id = generation_id
self._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)
+ continue
yield chunk
+ progress_deadline = loop.time() + self._progress_timeout_seconds
finally:
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.py
index 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.text
diff --git a/tests/application/test_execution.py b/tests/application/test_execution.py
index 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 asyncio
from collections.abc import AsyncIterator
-from unittest.mock import MagicMock
+from unittest.mock import MagicMock, patch
import pytest
@@ -10,6 +11,7 @@ from free_claude_code.application.routing import ResolvedModel, RoutedMessagesRe
from free_claude_code.config.reasoning import ReasoningPreference
from free_claude_code.core.anthropic.models import Message, MessagesRequest
from free_claude_code.core.async_iterators import AsyncCloseable
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
from 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 step
finally:
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.asyncio
async 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() -> Non
token_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 == 1
diff --git a/uv.lock b/uv.lock
index 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" },