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

Canonicalize provider failure and retry ownership (#1046)

Ali Khokhare22a38b2c26f
diff --git a/AGENTS.md b/AGENTS.md
index 90390629..164e80d2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -31,6 +31,7 @@
## ARCHITECTURE PRINCIPLES
- **Shared utilities**: Put shared Anthropic protocol logic in neutral `src/free_claude_code/core/anthropic/` modules. Do not have one provider import from another provider's utils.
+- **Failure ownership**: Keep canonical failure semantics and redaction SDK-free in `core/`; providers alone classify SDK/HTTP failures and own retries; protocol/API adapters alone choose wire error types and commit-boundary serialization.
- **DRY**: Extract shared base classes to eliminate duplication. Prefer composition over copy-paste.
- **Encapsulation**: Use accessor methods for internal state (e.g. `set_current_task()`), not direct `_attribute` assignment from outside.
- **Provider-specific config**: Keep provider-specific fields (e.g. `nim_settings`) in provider constructors, not in the base `ProviderConfig`.
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index d09be798..38ef7c5c 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -48,7 +48,8 @@ The installable wheel packages are declared in [pyproject.toml](pyproject.toml):
- [src/free_claude_code/application/](src/free_claude_code/application/) is the dependency-leaf application boundary. It
owns immutable routing/model-metadata values, model routing, shared provider
execution, the consumer-facing `ProviderPort`, request-runtime lease ports,
- and task control. It depends only on configuration and core protocol logic.
+ task control, and deterministic request/readiness errors. It depends only on
+ configuration and core protocol-neutral logic.
- [src/free_claude_code/api/](src/free_claude_code/api/) is the HTTP adapter. It owns the FastAPI app, routes, API product
handlers, local optimizations, model-catalog responses, HTTP error mapping,
response commit timing, and Admin-specific ports. It consumes application and
@@ -59,13 +60,15 @@ The installable wheel packages are declared in [pyproject.toml](pyproject.toml):
logging setup, constants, and provider ID catalogs.
- [src/free_claude_code/core/](src/free_claude_code/core/) owns provider-neutral protocol logic: wire request and response
models, Anthropic conversion, SSE construction, OpenAI Responses conversion,
- stream recovery, token counting, and structured trace helpers.
+ canonical execution-failure semantics, credential-safe diagnostics, token
+ counting, and structured trace helpers. It never classifies provider SDK or
+ HTTP client exceptions.
- [src/free_claude_code/messaging/](src/free_claude_code/messaging/) owns optional platform adapters, incoming message
handling, tree queues, transcript rendering, persistence, commands, and voice
support.
- [src/free_claude_code/providers/](src/free_claude_code/providers/) owns provider construction, shared provider base
- classes, upstream transports, rate limiting, model listing, and concrete
- provider adapters.
+ classes, upstream transports, SDK/HTTP failure classification, retry and
+ recovery policy, rate limiting, model listing, and concrete provider adapters.
- [src/free_claude_code/runtime/](src/free_claude_code/runtime/) is the process composition root. It owns application
startup and shutdown, provider generations, Admin runtime operations, and the
concrete wiring between API, providers, messaging, and managed CLI sessions.
@@ -318,7 +321,10 @@ discarding incomplete content rather than presenting a partial success.
Ingress authentication, request validation, model routing, and deterministic
preflight failures remain ordinary HTTP errors and do not receive the terminal
-provider-execution retry header.
+provider-execution retry header. Missing provider configuration and a shutting
+down request runtime are application-readiness errors: Messages serializes them
+as Anthropic JSON, Responses serializes them as OpenAI JSON, and neither is
+misclassified as an already-finalized provider execution failure.
```mermaid
sequenceDiagram
@@ -478,8 +484,10 @@ downgrade: if an upstream NIM deployment rejects explicit budget control, FCC
retries without the budget while preserving thinking enablement.
Shared provider responsibilities include upstream rate limiting, model listing,
-safe error mapping, transport cleanup, thinking/tool handling, retry or recovery
-where supported, and returning Anthropic SSE strings to the service layer.
+SDK/HTTP failure classification, safe diagnostic construction, transport
+cleanup, thinking/tool handling, retry or recovery where supported, and
+returning successful Anthropic SSE strings to the service layer. Final failures
+cross that boundary as `ExecutionFailure`, not as provider-authored wire events.
Every provider and both transport families receive the same concrete
`MessagesRequest` owned by the Anthropic protocol package. Known wire fields are
accessed through that model; `Any` and dynamic attribute lookup are reserved for
@@ -531,34 +539,54 @@ usage quirks such as DeepSeek prompt-cache counters.
- tool schema and tool-result handling;
- thinking block handling;
- stream lifecycle through `src/free_claude_code/core/anthropic/streaming`, including the neutral
- stream ledger, Anthropic SSE emitter, native event normalization, retry
- holdback, continuation, and tool repair;
+ stream ledger, Anthropic SSE emitter, native event normalization,
+ continuation-body construction, and tool repair;
- native Anthropic stream policy;
-- token counting and user-facing error formatting.
+- token counting and Anthropic-owned failure-kind-to-wire mapping.
Shared stream behavior lives under
[src/free_claude_code/core/anthropic/streaming/](src/free_claude_code/core/anthropic/streaming/). The shared layer owns the
-Anthropic content-block ledger, SSE serialization, early retry classification,
-holdback buffering, retry attempt counting, common flush/discard behavior,
-midstream continuation, tool JSON repair, and final success/error tails. Provider
-transport packages are upstream adapters: OpenAI-chat providers convert chat
-chunks into ledger operations, and native Anthropic providers parse upstream SSE,
-apply native block policy, and re-emit normalized Anthropic SSE from the shared
-ledger. Transport bases stay focused on provider hooks, client setup, request
-construction, rate limiting, and model listing. Status-less upstream transient
-classification also lives in this shared layer so stream recovery, provider
-backoff, and provider error mapping agree on retryable overload/rate-limit
-signals.
-
-Provider transports raise typed provider errors for final stream failures before
-any downstream-visible SSE chunk has escaped the recovery holdback. Once output
-has committed, transports keep ownership of midstream recovery, continuation,
-tool salvage, and protocol-specific success/error tails.
-The public streaming API boundary owns the final downstream error shape: provider
-errors remain visible to clients, but after FCC exhausts provider retry/recovery
-they are returned as typed HTTP errors with explicit retry suppression when the
-HTTP response is still uncommitted. Only already-committed streams use terminal
-protocol events.
+Anthropic content-block ledger, SSE serialization, continuation request
+transformations, and tool JSON repair. It does not import `httpx` or the OpenAI
+SDK and does not decide whether an upstream failure is retryable.
+
+[core/failures.py](src/free_claude_code/core/failures.py) defines the immutable,
+protocol-neutral `FailureKind` and `ExecutionFailure`. The exception is the
+value propagated through async iterators; its semantic fields are immutable,
+while Python remains free to attach traceback/cause metadata during unwinding.
+[core/diagnostics.py](src/free_claude_code/core/diagnostics.py) owns bounded error
+body/cause extraction, credential redaction, safe traceback formatting, and
+copyable request-ID diagnostics. Anthropic and Responses packages independently
+map the canonical kind and status to their wire error types.
+
+[providers/failure_policy.py](src/free_claude_code/providers/failure_policy.py)
+is the only owner of raw OpenAI SDK and `httpx` exception classification,
+transient status/body inference, stable provider wording, and final diagnostic
+construction for those failures. Native Anthropic wire errors are instead
+mapped to canonical failures by the Anthropic protocol package, then consumed
+by provider retry/recovery policy.
+[providers/stream_recovery.py](src/free_claude_code/providers/stream_recovery.py)
+owns the 0.75-second/65,536-byte holdback, four transparent early retries after
+the first attempt, and five midstream recovery attempts. Provider opening keeps
+its existing five-attempt exponential-backoff budget. `ExecutionFailure.retryable`
+records provider-policy eligibility; it never tells the client to retry after FCC
+has finalized the failure.
+
+Provider transport packages remain upstream adapters: OpenAI-chat providers
+convert chat chunks into ledger operations, and native Anthropic providers parse
+upstream SSE and canonicalize upstream error events. After retry, continuation,
+and tool salvage are exhausted, a transport discards uncommitted output or
+flushes committed output, closes any open content blocks, and raises
+`ExecutionFailure`. It never synthesizes a terminal Anthropic error event.
+
+The public HTTP commit boundary solely decides whether a final failure can use
+non-2xx JSON or must use a terminal protocol event; the protocol packages own
+envelope and event serialization. Before the first public frame the boundary
+returns typed non-2xx JSON with `x-should-retry: false`; after the first frame
+Messages appends one Anthropic `event: error`, while Responses emits
+`response.failed` with the original response ID. Non-streaming Messages catches
+the same failure and discards its partial aggregate. Unexpected failures use the
+same commit-state split but do not acquire provider retry semantics.
[src/free_claude_code/core/openai_responses/](src/free_claude_code/core/openai_responses/) owns OpenAI Responses support:
@@ -585,8 +613,9 @@ block-indexed Responses stream assembler. The package separates Anthropic SSE
dispatch, block state, output ledger ordering, block completion, SSE event
builders, and error mapping. API code should depend on the adapter, not on
those internal module owners directly. Responses output payloads stay
-OpenAI-shaped; Anthropic terminal metadata is used internally only when it
-affects streamed behavior.
+OpenAI-shaped. Canonical execution failures enter the assembler directly, so
+Responses does not infer provider failure semantics by parsing an Anthropic
+terminal error.
Post-start Responses failures are assembler-owned: the active
`ResponsesStreamAssembler` emits `response.failed` so the terminal event keeps
the same `response.id`, output ledger, and usage state as the earlier
diff --git a/CLAUDE.md b/CLAUDE.md
index 90390629..164e80d2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -31,6 +31,7 @@
## ARCHITECTURE PRINCIPLES
- **Shared utilities**: Put shared Anthropic protocol logic in neutral `src/free_claude_code/core/anthropic/` modules. Do not have one provider import from another provider's utils.
+- **Failure ownership**: Keep canonical failure semantics and redaction SDK-free in `core/`; providers alone classify SDK/HTTP failures and own retries; protocol/API adapters alone choose wire error types and commit-boundary serialization.
- **DRY**: Extract shared base classes to eliminate duplication. Prefer composition over copy-paste.
- **Encapsulation**: Use accessor methods for internal state (e.g. `set_current_task()`), not direct `_attribute` assignment from outside.
- **Provider-specific config**: Keep provider-specific fields (e.g. `nim_settings`) in provider constructors, not in the base `ProviderConfig`.
diff --git a/pyproject.toml b/pyproject.toml
index c85c9cff..93879682 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "3.4.20"
+version = "3.4.21"
description = "Middleware between Claude Code CLI (Anthropic API) and NVIDIA NIM"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/smoke/capabilities.py b/smoke/capabilities.py
index 6b4279d5..f78968bd 100644
--- a/smoke/capabilities.py
+++ b/smoke/capabilities.py
@@ -173,13 +173,16 @@ CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = (
"streaming_conversion",
"anthropic_sse_lifecycle",
"streaming_error_mapping",
- "free_claude_code.core.anthropic.streaming.AnthropicStreamLedger",
- "provider stream chunks or native SSE events",
- "Anthropic message/content/error SSE lifecycle",
- "Anthropic-compatible error event",
+ "free_claude_code.core.failures.ExecutionFailure",
+ "provider stream failures before or after the HTTP commit boundary",
+ "protocol-specific JSON failure or terminal stream event",
+ "ordinary request failures remain distinct from terminal execution",
(
- "tests/contracts/test_stream_contracts.py",
- "tests/providers/test_streaming_errors.py",
+ "tests/api/test_execution_failure_contract.py",
+ "tests/api/test_ordinary_error_phases.py",
+ "tests/core/test_failure_protocol_mapping.py",
+ "tests/providers/test_execution_failure_boundary.py",
+ "tests/providers/test_failure_policy.py",
),
),
CapabilityContract(
diff --git a/smoke/features.py b/smoke/features.py
index aa213386..85318aea 100644
--- a/smoke/features.py
+++ b/smoke/features.py
@@ -509,11 +509,13 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
),
FeatureCoverage(
"streaming_error_mapping",
- "Provider and validation errors map to Anthropic-compatible payloads",
+ "Canonical execution failures map to protocol-correct terminal output",
"public_surface",
(
- "tests/providers/test_streaming_errors.py",
- "tests/providers/test_error_mapping.py",
+ "tests/api/test_execution_failure_contract.py",
+ "tests/core/test_failure_protocol_mapping.py",
+ "tests/providers/test_execution_failure_boundary.py",
+ "tests/providers/test_failure_policy.py",
),
(),
(
diff --git a/src/free_claude_code/api/app.py b/src/free_claude_code/api/app.py
index a315f3a4..914ac951 100644
--- a/src/free_claude_code/api/app.py
+++ b/src/free_claude_code/api/app.py
@@ -1,6 +1,5 @@
"""Pure FastAPI application factory."""
-import traceback
from typing import Any
from fastapi import FastAPI, Request
@@ -9,18 +8,21 @@ from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from loguru import logger
-from free_claude_code.core.anthropic import (
- anthropic_error_payload,
- get_user_facing_error_message,
+from free_claude_code.application.errors import ApplicationError
+from free_claude_code.core.anthropic import anthropic_error_payload
+from free_claude_code.core.diagnostics import (
+ redacted_exception_traceback,
+ safe_exception_message,
)
+from free_claude_code.core.openai_responses import openai_error_payload
from free_claude_code.core.trace import (
extract_claude_session_id_from_headers,
trace_event,
)
-from free_claude_code.providers.exceptions import ProviderError
from .admin_routes import router as admin_router
from .ports import ApiServices
+from .request_errors import ordinary_application_error_response
from .request_ids import (
attach_request_id_headers,
get_request_id,
@@ -82,30 +84,15 @@ def create_app(services: ApiServices) -> FastAPI:
)
return await request_validation_exception_handler(request, exc)
- @app.exception_handler(ProviderError)
- async def provider_error_handler(request: Request, exc: ProviderError):
- """Handle provider-specific errors and return Anthropic format."""
- settings = services.requests.current_settings()
- if settings.log_api_error_tracebacks:
- logger.error(
- "Provider Error: error_type={} status_code={} message={}",
- exc.error_type,
- exc.status_code,
- exc.message,
- )
- else:
- logger.error(
- "Provider Error: error_type={} status_code={}",
- exc.error_type,
- exc.status_code,
- )
- return JSONResponse(
- status_code=exc.status_code,
- content=anthropic_error_payload(
- error_type=exc.error_type,
- message=exc.message,
- request_id=get_request_id(request),
+ @app.exception_handler(ApplicationError)
+ async def application_error_handler(request: Request, exc: ApplicationError):
+ """Serialize defensive application failures in the selected wire protocol."""
+ return ordinary_application_error_response(
+ exc,
+ wire_api=(
+ "responses" if request.url.path == "/v1/responses" else "messages"
),
+ request_id=get_request_id(request),
)
@app.exception_handler(Exception)
@@ -121,8 +108,8 @@ def create_app(services: ApiServices) -> FastAPI:
request_id=request_id,
):
if settings.log_api_error_tracebacks:
- logger.error("General Error: {}", exc)
- logger.error(traceback.format_exc())
+ logger.error("General Error: {}", safe_exception_message(exc))
+ logger.error(redacted_exception_traceback(exc))
else:
logger.error(
"General Error: path={} method={} exc_type={}",
@@ -130,14 +117,16 @@ def create_app(services: ApiServices) -> FastAPI:
request.method,
type(exc).__name__,
)
- response = JSONResponse(
- status_code=500,
- content=anthropic_error_payload(
+ message = safe_exception_message(exc)
+ if request.url.path == "/v1/responses":
+ content = openai_error_payload(message=message, error_type="api_error")
+ else:
+ content = anthropic_error_payload(
error_type="api_error",
- message=get_user_facing_error_message(exc),
+ message=message,
request_id=request_id,
- ),
- )
+ )
+ response = JSONResponse(status_code=500, content=content)
attach_request_id_headers(
response,
request_id=request_id,
diff --git a/src/free_claude_code/api/dependencies.py b/src/free_claude_code/api/dependencies.py
index 9cc39863..3557c60b 100644
--- a/src/free_claude_code/api/dependencies.py
+++ b/src/free_claude_code/api/dependencies.py
@@ -5,14 +5,10 @@ import secrets
from fastapi import Depends, HTTPException, Request
from loguru import logger
+from free_claude_code.application.errors import UnknownProviderError
from free_claude_code.application.ports import ProviderPort, RequestRuntimeLease
from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
from free_claude_code.config.settings import Settings
-from free_claude_code.core.anthropic import get_user_facing_error_message
-from free_claude_code.providers.exceptions import (
- AuthenticationError,
- UnknownProviderTypeError,
-)
from .ports import ApiServices
@@ -36,10 +32,7 @@ def resolve_provider(
should_log_init = not lease.is_provider_cached(provider_type)
try:
provider = lease.resolve_provider(provider_type)
- except AuthenticationError as exc:
- detail = str(exc).strip() or get_user_facing_error_message(exc)
- raise HTTPException(status_code=503, detail=detail) from exc
- except UnknownProviderTypeError:
+ except UnknownProviderError:
logger.error(
"Unknown provider_type: '{}'. Supported: {}",
provider_type,
diff --git a/src/free_claude_code/api/handlers/messages.py b/src/free_claude_code/api/handlers/messages.py
index 31b7c0f8..210de22f 100644
--- a/src/free_claude_code/api/handlers/messages.py
+++ b/src/free_claude_code/api/handlers/messages.py
@@ -20,6 +20,7 @@ from free_claude_code.api.response_streams import (
EmptyStreamError,
anthropic_sse_streaming_response,
terminal_execution_error_response,
+ trace_terminal_execution_error,
)
from free_claude_code.api.web_tools.egress import (
WebFetchEgressPolicy,
@@ -30,6 +31,7 @@ from free_claude_code.api.web_tools.request import (
openai_chat_upstream_server_tool_error,
)
from free_claude_code.api.web_tools.streaming import stream_web_server_tool_response
+from free_claude_code.application.errors import ApplicationError, InvalidRequestError
from free_claude_code.application.execution import ProviderExecutor, TokenCounter
from free_claude_code.application.ports import ProviderResolver
from free_claude_code.application.routing import ModelRouter, RoutedMessagesRequest
@@ -39,12 +41,14 @@ from free_claude_code.core.anthropic import (
MessagesRequest,
aggregate_anthropic_sse_to_message,
anthropic_error_payload,
+ anthropic_error_type_for_failure,
+ anthropic_failure_payload,
anthropic_status_for_error_type,
get_token_count,
- get_user_facing_error_message,
)
+from free_claude_code.core.diagnostics import safe_exception_message
+from free_claude_code.core.failures import ExecutionFailure, find_execution_failure
from free_claude_code.core.trace import trace_event
-from free_claude_code.providers.exceptions import InvalidRequestError, ProviderError
_OPENAI_CHAT_UPSTREAM_IDS = frozenset(
provider_id
@@ -122,9 +126,14 @@ class MessagesHandler:
stream=request_data.stream,
request_id=request_id,
)
- except ProviderError:
+ except ApplicationError:
raise
+ except ExecutionFailure as exc:
+ return self._execution_failure_response(exc, request_id=request_id)
except Exception as exc:
+ failure = find_execution_failure(exc)
+ if failure is not None:
+ return self._execution_failure_response(failure, request_id=request_id)
raise unexpected_http_exception(
self._settings, exc, context="CREATE_MESSAGE_ERROR"
) from exc
@@ -148,11 +157,14 @@ class MessagesHandler:
raise
except asyncio.CancelledError:
raise
- except ProviderError as exc:
- return self._provider_execution_error_response(
- exc, request_id=request_id
- )
+ except ExecutionFailure as exc:
+ return self._execution_failure_response(exc, request_id=request_id)
except BaseExceptionGroup as exc:
+ failure = find_execution_failure(exc)
+ if failure is not None:
+ return self._execution_failure_response(
+ failure, request_id=request_id
+ )
return self._unexpected_execution_error_response(
exc,
request_id=request_id,
@@ -167,7 +179,8 @@ class MessagesHandler:
if error is not None:
error_type, message_text = _stream_error_fields(error)
status_code = anthropic_status_for_error_type(error_type)
- self._trace_terminal_execution_error(
+ trace_terminal_execution_error(
+ wire_api="messages",
request_id=request_id,
status_code=status_code,
error_type=error_type,
@@ -186,13 +199,15 @@ class MessagesHandler:
pre_start_error_response=lambda exc: self._pre_start_error_response(
exc, request_id=request_id
),
+ request_id=request_id,
)
def _pre_start_error_response(
self, exc: BaseException, *, request_id: str
) -> Response:
- if isinstance(exc, ProviderError):
- return self._provider_execution_error_response(exc, request_id=request_id)
+ failure = find_execution_failure(exc)
+ if failure is not None:
+ return self._execution_failure_response(failure, request_id=request_id)
context = (
"CREATE_MESSAGE_EMPTY_STREAM"
if isinstance(exc, EmptyStreamError)
@@ -204,21 +219,20 @@ class MessagesHandler:
context=context,
)
- def _provider_execution_error_response(
- self, exc: ProviderError, *, request_id: str
+ def _execution_failure_response(
+ self, failure: ExecutionFailure, *, request_id: str
) -> JSONResponse:
- self._trace_terminal_execution_error(
+ error_type = anthropic_error_type_for_failure(failure)
+ trace_terminal_execution_error(
+ wire_api="messages",
request_id=request_id,
- status_code=exc.status_code,
- error_type=exc.error_type,
+ status_code=failure.status_code,
+ error_type=error_type,
+ error=failure,
)
return terminal_execution_error_response(
- status_code=exc.status_code,
- content=anthropic_error_payload(
- error_type=exc.error_type,
- message=exc.message,
- request_id=request_id,
- ),
+ status_code=failure.status_code,
+ content=anthropic_failure_payload(failure, request_id=request_id),
)
def _unexpected_execution_error_response(
@@ -235,43 +249,22 @@ class MessagesHandler:
request_id=request_id,
)
status_code = http_status_for_unexpected_api_exception(exc)
- self._trace_terminal_execution_error(
+ trace_terminal_execution_error(
+ wire_api="messages",
request_id=request_id,
status_code=status_code,
error_type="api_error",
- exc_type=type(exc).__name__,
+ error=exc,
)
return terminal_execution_error_response(
status_code=status_code,
content=anthropic_error_payload(
error_type="api_error",
- message=get_user_facing_error_message(exc),
+ message=safe_exception_message(exc),
request_id=request_id,
),
)
- @staticmethod
- def _trace_terminal_execution_error(
- *,
- request_id: str,
- status_code: int,
- error_type: str,
- exc_type: str | None = None,
- ) -> None:
- fields: dict[str, object] = {
- "stage": "egress",
- "event": "free_claude_code.api.response.terminal_execution_error",
- "source": "api",
- "wire_api": "messages",
- "request_id": request_id,
- "status_code": status_code,
- "error_type": error_type,
- "client_should_retry": False,
- }
- if exc_type is not None:
- fields["exc_type"] = exc_type
- trace_event(**fields)
-
def _reject_unsupported_server_tools(self, routed: RoutedMessagesRequest) -> None:
if routed.resolved.provider_id not in _OPENAI_CHAT_UPSTREAM_IDS:
return
diff --git a/src/free_claude_code/api/handlers/responses.py b/src/free_claude_code/api/handlers/responses.py
index 662f29d1..b2ffcef8 100644
--- a/src/free_claude_code/api/handlers/responses.py
+++ b/src/free_claude_code/api/handlers/responses.py
@@ -11,21 +11,22 @@ from free_claude_code.api.request_ids import new_request_id
from free_claude_code.api.response_streams import (
openai_responses_sse_streaming_response,
terminal_execution_error_response,
+ trace_terminal_execution_error,
)
+from free_claude_code.application.errors import ApplicationError, InvalidRequestError
from free_claude_code.application.execution import ProviderExecutor
from free_claude_code.application.ports import ProviderResolver
from free_claude_code.application.routing import ModelRouter
from free_claude_code.config.settings import Settings
-from free_claude_code.core.anthropic import (
- MessagesRequest,
- get_user_facing_error_message,
-)
+from free_claude_code.core.anthropic import MessagesRequest
+from free_claude_code.core.diagnostics import safe_exception_message
+from free_claude_code.core.failures import ExecutionFailure, find_execution_failure
from free_claude_code.core.openai_responses import (
OpenAIResponsesAdapter,
OpenAIResponsesRequest,
+ openai_error_type_for_failure,
+ openai_failure_payload,
)
-from free_claude_code.core.trace import trace_event
-from free_claude_code.providers.exceptions import InvalidRequestError, ProviderError
class ResponsesHandler:
@@ -57,16 +58,9 @@ class ResponsesHandler:
request_id = request_id or new_request_id()
request_payload = request_data.model_dump(mode="json", exclude_none=True)
if request_data.stream is False:
- invalid_request = InvalidRequestError(
+ raise InvalidRequestError(
"FCC /v1/responses supports streaming only; omit stream or set stream=true."
)
- return JSONResponse(
- status_code=invalid_request.status_code,
- content=self._responses_adapter.error_payload(
- message=invalid_request.message,
- error_type=invalid_request.error_type,
- ),
- )
try:
anthropic_payload = self._responses_adapter.to_anthropic_payload(
@@ -87,6 +81,12 @@ class ResponsesHandler:
self._responses_adapter.iter_sse_from_anthropic(
streamed,
request_data,
+ on_post_start_terminal_failure=lambda exc: (
+ self._trace_post_start_terminal_failure(
+ exc,
+ request_id=request_id,
+ )
+ ),
),
headers=self._responses_adapter.sse_headers,
pre_start_error_response=lambda exc: self._pre_start_error_response(
@@ -94,23 +94,15 @@ class ResponsesHandler:
),
)
except OpenAIResponsesAdapter.ConversionError as exc:
- invalid_request = InvalidRequestError(str(exc))
- return JSONResponse(
- status_code=invalid_request.status_code,
- content=self._responses_adapter.error_payload(
- message=invalid_request.message,
- error_type=invalid_request.error_type,
- ),
- )
- except ProviderError as exc:
- return JSONResponse(
- status_code=exc.status_code,
- content=self._responses_adapter.error_payload(
- message=exc.message,
- error_type=exc.error_type,
- ),
- )
+ raise InvalidRequestError(str(exc)) from exc
+ except ApplicationError:
+ raise
+ except ExecutionFailure as exc:
+ return self._execution_failure_response(exc, request_id=request_id)
except Exception as exc:
+ failure = find_execution_failure(exc)
+ if failure is not None:
+ return self._execution_failure_response(failure, request_id=request_id)
log_unexpected_api_exception(
self._settings,
exc,
@@ -119,7 +111,7 @@ class ResponsesHandler:
return JSONResponse(
status_code=http_status_for_unexpected_api_exception(exc),
content=self._responses_adapter.error_payload(
- message=get_user_facing_error_message(exc),
+ message=safe_exception_message(exc),
error_type="api_error",
),
)
@@ -127,19 +119,9 @@ class ResponsesHandler:
def _pre_start_error_response(
self, exc: BaseException, *, request_id: str
) -> JSONResponse:
- if isinstance(exc, ProviderError):
- self._trace_terminal_execution_error(
- request_id=request_id,
- status_code=exc.status_code,
- error_type=exc.error_type,
- )
- return terminal_execution_error_response(
- status_code=exc.status_code,
- content=self._responses_adapter.error_payload(
- message=exc.message,
- error_type=exc.error_type,
- ),
- )
+ failure = find_execution_failure(exc)
+ if failure is not None:
+ return self._execution_failure_response(failure, request_id=request_id)
log_unexpected_api_exception(
self._settings,
exc,
@@ -147,40 +129,55 @@ class ResponsesHandler:
request_id=request_id,
)
status_code = http_status_for_unexpected_api_exception(exc)
- self._trace_terminal_execution_error(
+ trace_terminal_execution_error(
+ wire_api="responses",
request_id=request_id,
status_code=status_code,
error_type="api_error",
- exc_type=type(exc).__name__,
+ error=exc,
)
return terminal_execution_error_response(
status_code=status_code,
content=self._responses_adapter.error_payload(
- message=get_user_facing_error_message(exc),
+ message=safe_exception_message(exc),
error_type="api_error",
),
)
+ def _execution_failure_response(
+ self,
+ failure: ExecutionFailure,
+ *,
+ request_id: str,
+ ) -> JSONResponse:
+ error_type = openai_error_type_for_failure(failure)
+ trace_terminal_execution_error(
+ wire_api="responses",
+ request_id=request_id,
+ status_code=failure.status_code,
+ error_type=error_type,
+ error=failure,
+ )
+ return terminal_execution_error_response(
+ status_code=failure.status_code,
+ content=openai_failure_payload(failure),
+ )
+
@staticmethod
- def _trace_terminal_execution_error(
+ def _trace_post_start_terminal_failure(
+ exc: BaseException,
*,
request_id: str,
- status_code: int,
- error_type: str,
- exc_type: str | None = None,
) -> None:
- fields: dict[str, object] = {
- "wire_api": "responses",
- "request_id": request_id,
- "status_code": status_code,
- "error_type": error_type,
- "client_should_retry": False,
- }
- if exc_type is not None:
- fields["exc_type"] = exc_type
- trace_event(
- stage="egress",
- event="free_claude_code.api.response.terminal_execution_error",
- source="api",
- **fields,
+ failure = find_execution_failure(exc)
+ trace_terminal_execution_error(
+ wire_api="responses",
+ request_id=request_id,
+ status_code=failure.status_code if failure is not None else 500,
+ error_type=(
+ openai_error_type_for_failure(failure)
+ if failure is not None
+ else "api_error"
+ ),
+ error=exc,
)
diff --git a/src/free_claude_code/api/handlers/token_count.py b/src/free_claude_code/api/handlers/token_count.py
index 81ebe1fe..3ee838d5 100644
--- a/src/free_claude_code/api/handlers/token_count.py
+++ b/src/free_claude_code/api/handlers/token_count.py
@@ -9,6 +9,7 @@ from free_claude_code.api.request_errors import (
require_non_empty_messages,
)
from free_claude_code.api.request_ids import new_request_id
+from free_claude_code.application.errors import ApplicationError
from free_claude_code.application.execution import TokenCounter
from free_claude_code.application.routing import ModelRouter
from free_claude_code.config.settings import Settings
@@ -17,10 +18,9 @@ from free_claude_code.core.anthropic import (
TokenCountResponse,
anthropic_request_snapshot,
get_token_count,
- get_user_facing_error_message,
)
+from free_claude_code.core.diagnostics import safe_exception_message
from free_claude_code.core.trace import trace_event
-from free_claude_code.providers.exceptions import ProviderError
class TokenCountHandler:
@@ -70,7 +70,7 @@ class TokenCountHandler:
snapshot=anthropic_request_snapshot(routed.request),
)
return TokenCountResponse(input_tokens=tokens)
- except ProviderError:
+ except ApplicationError:
raise
except Exception as exc:
log_unexpected_api_exception(
@@ -81,5 +81,5 @@ class TokenCountHandler:
)
raise HTTPException(
status_code=http_status_for_unexpected_api_exception(exc),
- detail=get_user_facing_error_message(exc),
+ detail=safe_exception_message(exc),
) from exc
diff --git a/src/free_claude_code/api/request_errors.py b/src/free_claude_code/api/request_errors.py
index 1fda17ab..4e67fa58 100644
--- a/src/free_claude_code/api/request_errors.py
+++ b/src/free_claude_code/api/request_errors.py
@@ -1,14 +1,27 @@
"""Shared API request validation and safe error logging."""
-import traceback
-from typing import Any
+from typing import Any, Literal
from fastapi import HTTPException
+from fastapi.responses import JSONResponse
from loguru import logger
+from free_claude_code.application.errors import ApplicationError, InvalidRequestError
from free_claude_code.config.settings import Settings
-from free_claude_code.core.anthropic import get_user_facing_error_message
-from free_claude_code.providers.exceptions import InvalidRequestError
+from free_claude_code.core.anthropic import (
+ anthropic_error_payload,
+ anthropic_error_type_for_failure,
+)
+from free_claude_code.core.diagnostics import (
+ redacted_exception_traceback,
+ safe_exception_message,
+)
+from free_claude_code.core.openai_responses import (
+ openai_error_payload,
+ openai_error_type_for_failure,
+)
+
+WireApi = Literal["messages", "responses"]
def require_non_empty_messages(messages: list[Any]) -> None:
@@ -16,6 +29,31 @@ def require_non_empty_messages(messages: list[Any]) -> None:
raise InvalidRequestError("messages cannot be empty")
+def ordinary_application_error_response(
+ error: ApplicationError,
+ *,
+ wire_api: WireApi,
+ request_id: str,
+) -> JSONResponse:
+ """Serialize a deterministic application error without terminal headers."""
+ if wire_api == "responses":
+ return JSONResponse(
+ status_code=error.status_code,
+ content=openai_error_payload(
+ message=error.message,
+ error_type=openai_error_type_for_failure(error.kind),
+ ),
+ )
+ return JSONResponse(
+ status_code=error.status_code,
+ content=anthropic_error_payload(
+ error_type=anthropic_error_type_for_failure(error.kind),
+ message=error.message,
+ request_id=request_id,
+ ),
+ )
+
+
def http_status_for_unexpected_api_exception(_exc: BaseException) -> int:
return 500
@@ -30,10 +68,15 @@ def log_unexpected_api_exception(
"""Log API failures without echoing exception text unless opted in."""
if settings.log_api_error_tracebacks:
if request_id is not None:
- logger.error("{} request_id={}: {}", context, request_id, exc)
+ logger.error(
+ "{} request_id={}: {}",
+ context,
+ request_id,
+ safe_exception_message(exc),
+ )
else:
- logger.error("{}: {}", context, exc)
- logger.error(traceback.format_exc())
+ logger.error("{}: {}", context, safe_exception_message(exc))
+ logger.error(redacted_exception_traceback(exc))
return
if request_id is not None:
logger.error(
@@ -52,5 +95,5 @@ def unexpected_http_exception(
log_unexpected_api_exception(settings, exc, context=context)
return HTTPException(
status_code=http_status_for_unexpected_api_exception(exc),
- detail=get_user_facing_error_message(exc),
+ detail=safe_exception_message(exc),
)
diff --git a/src/free_claude_code/api/response_streams.py b/src/free_claude_code/api/response_streams.py
index 109cdef9..94d26a27 100644
--- a/src/free_claude_code/api/response_streams.py
+++ b/src/free_claude_code/api/response_streams.py
@@ -9,22 +9,27 @@ from collections.abc import (
Callable,
Mapping,
)
-from typing import Any, Protocol, runtime_checkable
+from typing import Any, Literal, Protocol, runtime_checkable
from fastapi.responses import JSONResponse, Response, StreamingResponse
-from free_claude_code.core.anthropic import get_user_facing_error_message
+from free_claude_code.core.anthropic import anthropic_error_type_for_failure
from free_claude_code.core.anthropic.streaming import (
ANTHROPIC_SSE_RESPONSE_HEADERS,
anthropic_terminal_error_frame,
+ anthropic_terminal_failure_frame,
)
+from free_claude_code.core.diagnostics import safe_exception_message
+from free_claude_code.core.failures import find_execution_failure
from free_claude_code.core.trace import trace_event
TERMINAL_EXECUTION_ERROR_HEADERS = {"x-should-retry": "false"}
PreStartErrorResponse = Callable[[BaseException], Response]
TerminalFrameEmitter = Callable[[BaseException], str]
+TerminalFailureObserver = Callable[[BaseException], None]
ReleaseResponseResource = Callable[[], Awaitable[None]]
+WireApi = Literal["messages", "responses"]
@runtime_checkable
@@ -78,13 +83,32 @@ def terminal_execution_error_response(
)
-def _trace_egress_failure(exc: BaseException) -> None:
- trace_event(
- stage="egress",
- event="free_claude_code.api.response.egress_error_frame_emitted",
- source="api",
- exc_type=type(exc).__name__,
- )
+def trace_terminal_execution_error(
+ *,
+ wire_api: WireApi,
+ request_id: str,
+ status_code: int,
+ error_type: str,
+ error: BaseException | None = None,
+) -> None:
+ """Record one correlated terminal-execution decision at the HTTP boundary."""
+ fields: dict[str, object] = {
+ "stage": "egress",
+ "event": "free_claude_code.api.response.terminal_execution_error",
+ "source": "api",
+ "wire_api": wire_api,
+ "request_id": request_id,
+ "status_code": status_code,
+ "error_type": error_type,
+ "client_should_retry": False,
+ }
+ failure = find_execution_failure(error) if error is not None else None
+ if error is not None:
+ fields["exc_type"] = type(failure or error).__name__
+ if failure is not None:
+ fields["failure_kind"] = failure.kind.value
+ fields["provider_retryable"] = failure.retryable
+ trace_event(**fields)
async def _first_chunk_streaming_response(
@@ -93,6 +117,7 @@ async def _first_chunk_streaming_response(
headers: Mapping[str, str],
pre_start_error_response: PreStartErrorResponse,
terminal_frame: TerminalFrameEmitter | None,
+ terminal_failure_observer: TerminalFailureObserver | None,
) -> Response:
try:
first_chunk = await anext(body)
@@ -114,6 +139,7 @@ async def _first_chunk_streaming_response(
first_chunk,
body,
terminal_frame=terminal_frame,
+ terminal_failure_observer=terminal_failure_observer,
),
media_type="text/event-stream",
headers=dict(headers),
@@ -125,6 +151,7 @@ async def _replay_first_chunk_then_stream(
body: AsyncIterator[str],
*,
terminal_frame: TerminalFrameEmitter | None,
+ terminal_failure_observer: TerminalFailureObserver | None,
) -> AsyncGenerator[str]:
yield first_chunk
try:
@@ -137,12 +164,15 @@ async def _replay_first_chunk_then_stream(
except BaseExceptionGroup as exc:
if terminal_frame is None:
raise
- _trace_egress_failure(exc)
- yield terminal_frame(exc)
+ terminal_error = find_execution_failure(exc) or exc
+ if terminal_failure_observer is not None:
+ terminal_failure_observer(terminal_error)
+ yield terminal_frame(terminal_error)
except Exception as exc:
if terminal_frame is None:
raise
- _trace_egress_failure(exc)
+ if terminal_failure_observer is not None:
+ terminal_failure_observer(exc)
yield terminal_frame(exc)
@@ -150,15 +180,44 @@ async def anthropic_sse_streaming_response(
body: AsyncIterator[str],
*,
pre_start_error_response: PreStartErrorResponse,
+ request_id: str,
) -> Response:
"""Return a streaming response for Anthropic-style SSE streams."""
return await _first_chunk_streaming_response(
body,
headers=ANTHROPIC_SSE_RESPONSE_HEADERS,
pre_start_error_response=pre_start_error_response,
- terminal_frame=lambda exc: anthropic_terminal_error_frame(
- get_user_facing_error_message(exc)
+ terminal_frame=_anthropic_terminal_frame,
+ terminal_failure_observer=lambda exc: _trace_anthropic_terminal_failure(
+ exc,
+ request_id=request_id,
+ ),
+ )
+
+
+def _anthropic_terminal_frame(exc: BaseException) -> str:
+ failure = find_execution_failure(exc)
+ if failure is not None:
+ return anthropic_terminal_failure_frame(failure)
+ return anthropic_terminal_error_frame(safe_exception_message(exc))
+
+
+def _trace_anthropic_terminal_failure(
+ exc: BaseException,
+ *,
+ request_id: str,
+) -> None:
+ failure = find_execution_failure(exc)
+ trace_terminal_execution_error(
+ wire_api="messages",
+ request_id=request_id,
+ status_code=failure.status_code if failure is not None else 500,
+ error_type=(
+ anthropic_error_type_for_failure(failure)
+ if failure is not None
+ else "api_error"
),
+ error=exc,
)
@@ -174,4 +233,5 @@ async def openai_responses_sse_streaming_response(
headers=headers,
pre_start_error_response=pre_start_error_response,
terminal_frame=None,
+ terminal_failure_observer=None,
)
diff --git a/src/free_claude_code/api/routes.py b/src/free_claude_code/api/routes.py
index 94eb80e4..2ff1813d 100644
--- a/src/free_claude_code/api/routes.py
+++ b/src/free_claude_code/api/routes.py
@@ -3,6 +3,7 @@
from fastapi import APIRouter, Depends, HTTPException, Request, Response
from loguru import logger
+from free_claude_code.application.errors import ApplicationError
from free_claude_code.application.ports import ProviderResolver, RequestRuntimeLease
from free_claude_code.config.model_refs import parse_provider_type
from free_claude_code.config.settings import Settings
@@ -23,6 +24,7 @@ from .dependencies import (
from .handlers import MessagesHandler, ResponsesHandler, TokenCountHandler
from .model_catalog import ModelsListResponse, build_models_list_response
from .ports import ApiServices
+from .request_errors import ordinary_application_error_response
from .request_ids import get_request_id
from .response_streams import bind_response_lifetime
@@ -39,8 +41,9 @@ async def _create_messages_response(
*,
request_id: str,
) -> object:
- lease = await services.requests.acquire()
+ lease: RequestRuntimeLease | None = None
try:
+ lease = await services.requests.acquire()
handler = MessagesHandler(
lease.settings,
provider_resolver=_provider_resolver(lease),
@@ -48,9 +51,19 @@ async def _create_messages_response(
generation_id=lease.generation_id,
)
response = await handler.create(request_data, request_id=request_id)
+ except ApplicationError as exc:
+ if lease is not None:
+ await lease.release()
+ return ordinary_application_error_response(
+ exc,
+ wire_api="messages",
+ request_id=request_id,
+ )
except BaseException:
- await lease.release()
+ if lease is not None:
+ await lease.release()
raise
+ assert lease is not None
return await bind_response_lifetime(response, lease.release)
@@ -60,17 +73,28 @@ async def _create_responses_response(
*,
request_id: str,
) -> object:
- lease = await services.requests.acquire()
+ lease: RequestRuntimeLease | None = None
try:
+ lease = await services.requests.acquire()
handler = ResponsesHandler(
lease.settings,
provider_resolver=_provider_resolver(lease),
generation_id=lease.generation_id,
)
response = await handler.create(request_data, request_id=request_id)
+ except ApplicationError as exc:
+ if lease is not None:
+ await lease.release()
+ return ordinary_application_error_response(
+ exc,
+ wire_api="responses",
+ request_id=request_id,
+ )
except BaseException:
- await lease.release()
+ if lease is not None:
+ await lease.release()
raise
+ assert lease is not None
return await bind_response_lifetime(response, lease.release)
diff --git a/src/free_claude_code/application/errors.py b/src/free_claude_code/application/errors.py
new file mode 100644
index 00000000..c004388c
--- /dev/null
+++ b/src/free_claude_code/application/errors.py
@@ -0,0 +1,32 @@
+"""Deterministic application and readiness errors."""
+
+from free_claude_code.core.failures import FailureKind
+
+
+class ApplicationError(Exception):
+ """Base for request/readiness failures, not finalized upstream failures."""
+
+ kind: FailureKind
+ status_code: int
+
+ def __init__(self, message: str) -> None:
+ super().__init__(message)
+ self.message = message
+
+
+class InvalidRequestError(ApplicationError):
+ """The accepted request cannot be executed deterministically."""
+
+ kind = FailureKind.INVALID_REQUEST
+ status_code = 400
+
+
+class UnknownProviderError(InvalidRequestError):
+ """The configured provider identifier is not registered."""
+
+
+class ApplicationUnavailableError(ApplicationError):
+ """The application cannot currently provide a request runtime."""
+
+ kind = FailureKind.UNAVAILABLE
+ status_code = 503
diff --git a/src/free_claude_code/config/constants.py b/src/free_claude_code/config/constants.py
index c87425ec..987027ae 100644
--- a/src/free_claude_code/config/constants.py
+++ b/src/free_claude_code/config/constants.py
@@ -8,6 +8,3 @@ ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS = 81920
# Max bytes read from a non-200 native messages response when verbose error logging is on.
NATIVE_MESSAGES_ERROR_BODY_LOG_CAP_BYTES = 4096
-
-# Max upstream error bytes shown to users for copy/paste diagnostics.
-PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES = 16384
diff --git a/src/free_claude_code/core/anthropic/__init__.py b/src/free_claude_code/core/anthropic/__init__.py
index 68dfbbcf..ac17f878 100644
--- a/src/free_claude_code/core/anthropic/__init__.py
+++ b/src/free_claude_code/core/anthropic/__init__.py
@@ -9,11 +9,10 @@ from .conversion import (
)
from .errors import (
anthropic_error_payload,
+ anthropic_error_type_for_failure,
+ anthropic_failure_payload,
anthropic_status_for_error_type,
- append_request_id,
- format_user_error_preview,
- get_user_facing_error_message,
- redact_sensitive_error_text,
+ execution_failure_from_anthropic_error,
)
from .models import (
ContentBlockDocument,
@@ -86,19 +85,18 @@ __all__ = [
"Usage",
"aggregate_anthropic_sse_to_message",
"anthropic_error_payload",
+ "anthropic_error_type_for_failure",
+ "anthropic_failure_payload",
"anthropic_request_snapshot",
"anthropic_status_for_error_type",
- "append_request_id",
"build_base_request_body",
+ "execution_failure_from_anthropic_error",
"extract_text_from_content",
"format_sse_event",
- "format_user_error_preview",
"get_block_attr",
"get_block_type",
"get_token_count",
- "get_user_facing_error_message",
"map_stop_reason",
- "redact_sensitive_error_text",
"sanitize_native_messages_thinking_policy",
"serialize_tool_result_content",
"set_if_not_none",
diff --git a/src/free_claude_code/core/anthropic/errors.py b/src/free_claude_code/core/anthropic/errors.py
index 1f2a1008..e19d980b 100644
--- a/src/free_claude_code/core/anthropic/errors.py
+++ b/src/free_claude_code/core/anthropic/errors.py
@@ -1,41 +1,10 @@
-"""Anthropic error shaping shared by API, providers, and integrations."""
+"""Anthropic error types and envelopes."""
-import re
+from collections.abc import Mapping
from typing import Any
-import httpx
-import openai
-
-_SECRET_TEXT_REPLACEMENTS = (
- (
- re.compile(
- r"(?i)(?P<prefix>[\"']?authorization[\"']?\s*[:=]\s*)"
- r"(?P<quote>[\"']?)(?:(?:bearer|basic)\s+)?"
- r"[^\"'\s,;&}\]]+(?P=quote)"
- ),
- r"\g<prefix>\g<quote><redacted>\g<quote>",
- ),
- (
- re.compile(
- r"(?i)(?P<prefix>[\"']?(?:api[_-]?key|access[_-]?token|"
- r"refresh[_-]?token|token|client[_-]?secret|secret|password)"
- r"[\"']?\s*[:=]\s*)(?P<quote>[\"']?)"
- r"[^\"'\s,;&}\]]+(?P=quote)"
- ),
- r"\g<prefix>\g<quote><redacted>\g<quote>",
- ),
- (re.compile(r"(?i)(bearer\s+)[^\s,;]+"), r"\1<redacted>"),
- (
- re.compile(
- r"(?i)(?<![a-z0-9])(?:sk-[a-z0-9._-]{8,}|"
- r"nvapi-[a-z0-9._-]{8,}|hf_[a-z0-9_-]{8,}|"
- r"gsk_[a-z0-9_-]{8,}|github_pat_[a-z0-9_]{8,}|"
- r"gh[pousr]_[a-z0-9]{8,}|AIza[a-z0-9_-]{20,})"
- r"(?![a-z0-9])"
- ),
- "<redacted>",
- ),
-)
+from free_claude_code.core.diagnostics import redact_sensitive_error_text
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
_ANTHROPIC_ERROR_STATUS_CODES = {
"invalid_request_error": 400,
@@ -50,17 +19,56 @@ _ANTHROPIC_ERROR_STATUS_CODES = {
"overloaded_error": 529,
}
+_FAILURE_ERROR_TYPES = {
+ FailureKind.INVALID_REQUEST: "invalid_request_error",
+ FailureKind.AUTHENTICATION: "authentication_error",
+ FailureKind.PERMISSION: "permission_error",
+ FailureKind.RATE_LIMIT: "rate_limit_error",
+ FailureKind.OVERLOADED: "overloaded_error",
+ FailureKind.TIMEOUT: "api_error",
+ FailureKind.UPSTREAM: "api_error",
+ FailureKind.UNAVAILABLE: "api_error",
+}
+
+_ERROR_TYPE_FAILURE_KINDS = {
+ "invalid_request_error": FailureKind.INVALID_REQUEST,
+ "request_too_large": FailureKind.INVALID_REQUEST,
+ "authentication_error": FailureKind.AUTHENTICATION,
+ "billing_error": FailureKind.PERMISSION,
+ "permission_error": FailureKind.PERMISSION,
+ "not_found_error": FailureKind.INVALID_REQUEST,
+ "rate_limit_error": FailureKind.RATE_LIMIT,
+ "overloaded_error": FailureKind.OVERLOADED,
+ "timeout_error": FailureKind.TIMEOUT,
+ "api_error": FailureKind.UPSTREAM,
+}
+
-def redact_sensitive_error_text(text: str) -> str:
- """Redact recognizable credentials while preserving diagnostic context."""
- sanitized = text
- for pattern, replacement in _SECRET_TEXT_REPLACEMENTS:
- sanitized = pattern.sub(replacement, sanitized)
- return sanitized
+def anthropic_error_type_for_failure(
+ failure: FailureKind | ExecutionFailure,
+) -> str:
+ """Map neutral failure semantics to an Anthropic wire type."""
+ if isinstance(failure, ExecutionFailure):
+ if failure.kind == FailureKind.PERMISSION and failure.status_code == 402:
+ return "billing_error"
+ if failure.kind == FailureKind.INVALID_REQUEST:
+ if failure.status_code == 404:
+ return "not_found_error"
+ if failure.status_code == 413:
+ return "request_too_large"
+ if failure.kind == FailureKind.TIMEOUT and failure.status_code == 504:
+ return "timeout_error"
+ kind = failure.kind
+ else:
+ kind = failure
+ return _FAILURE_ERROR_TYPES[kind]
def anthropic_error_payload(
- *, error_type: str, message: str, request_id: str | None = None
+ *,
+ error_type: str,
+ message: str,
+ request_id: str | None = None,
) -> dict[str, Any]:
"""Return one Anthropic-compatible JSON error envelope."""
payload: dict[str, Any] = {
@@ -75,76 +83,54 @@ def anthropic_error_payload(
return payload
-def anthropic_status_for_error_type(error_type: str) -> int:
- """Return the standard HTTP status for an Anthropic error type."""
- return _ANTHROPIC_ERROR_STATUS_CODES.get(error_type, 500)
-
-
-def get_user_facing_error_message(
- e: BaseException,
+def anthropic_failure_payload(
+ failure: ExecutionFailure,
*,
- read_timeout_s: float | None = None,
-) -> str:
- """Return a readable, non-empty error message for users.
-
- Known transport and OpenAI SDK exception types are mapped to stable wording
- before falling back to ``str(e)``, so empty or noisy SDK messages do not skip
- the mapped path.
- """
- if isinstance(e, httpx.ReadTimeout):
- if read_timeout_s is not None:
- return f"Provider request timed out after {read_timeout_s:g}s."
- return "Provider request timed out."
- if isinstance(e, httpx.ConnectTimeout):
- return "Could not connect to provider."
- if isinstance(e, httpx.ConnectError):
- return "Could not connect to provider."
- if isinstance(e, httpx.RemoteProtocolError):
- return "Provider connection was interrupted before a response was received."
- if isinstance(e, TimeoutError):
- if read_timeout_s is not None:
- return f"Provider request timed out after {read_timeout_s:g}s."
- return "Request timed out."
-
- if isinstance(e, openai.RateLimitError):
- return "Provider rate limit reached. Please retry shortly."
- if isinstance(e, openai.AuthenticationError):
- return "Provider authentication failed. Check API key."
- if isinstance(e, openai.BadRequestError):
- return "Invalid request sent to provider."
-
- name = type(e).__name__
- status_code = getattr(e, "status_code", None)
- if name == "RateLimitError":
- return "Provider rate limit reached. Please retry shortly."
- if name == "AuthenticationError":
- return "Provider authentication failed. Check API key."
- if name == "InvalidRequestError":
- return "Invalid request sent to provider."
- if name == "OverloadedError":
- return "Provider is currently overloaded. Please retry."
- if name == "APIError":
- if status_code in (502, 503, 504):
- return "Provider is temporarily unavailable. Please retry."
- return "Provider API request failed."
- if name.endswith("ProviderError") or name == "ProviderError":
- return "Provider request failed."
-
- message = redact_sensitive_error_text(str(e).strip())
- if message:
- return message
-
- return "Provider request failed unexpectedly."
+ request_id: str | None = None,
+) -> dict[str, Any]:
+ """Serialize a canonical execution failure as an Anthropic JSON error."""
+ return anthropic_error_payload(
+ error_type=anthropic_error_type_for_failure(failure),
+ message=failure.message,
+ request_id=request_id,
+ )
-def format_user_error_preview(exc: Exception, *, max_len: int = 200) -> str:
- """Truncate a user-facing error string for short chat replies."""
- return get_user_facing_error_message(exc)[:max_len]
+def anthropic_status_for_error_type(error_type: str) -> int:
+ """Return the standard HTTP status for an Anthropic error type."""
+ return _ANTHROPIC_ERROR_STATUS_CODES.get(error_type, 500)
-def append_request_id(message: str, request_id: str | None) -> str:
- """Append request_id suffix when available."""
- base = message.strip() or "Provider request failed unexpectedly."
- if request_id:
- return f"{base} (request_id={request_id})"
- return base
+def execution_failure_from_anthropic_error(
+ data: Mapping[str, Any],
+) -> ExecutionFailure:
+ """Canonicalize one native upstream Anthropic error event."""
+ error = data.get("error")
+ if not isinstance(error, Mapping):
+ error = data
+ raw_type = error.get("type")
+ error_type = (
+ raw_type.strip()
+ if isinstance(raw_type, str) and raw_type.strip()
+ else "api_error"
+ )
+ raw_message = error.get("message")
+ message = (
+ redact_sensitive_error_text(raw_message.strip())
+ if isinstance(raw_message, str) and raw_message.strip()
+ else "Provider request failed unexpectedly."
+ )
+ kind = _ERROR_TYPE_FAILURE_KINDS.get(error_type, FailureKind.UPSTREAM)
+ return ExecutionFailure(
+ kind=kind,
+ status_code=anthropic_status_for_error_type(error_type),
+ message=message,
+ retryable=kind
+ in {
+ FailureKind.RATE_LIMIT,
+ FailureKind.OVERLOADED,
+ FailureKind.TIMEOUT,
+ FailureKind.UPSTREAM,
+ FailureKind.UNAVAILABLE,
+ },
+ )
diff --git a/src/free_claude_code/core/anthropic/streaming/__init__.py b/src/free_claude_code/core/anthropic/streaming/__init__.py
index 245a48cc..280ddab2 100644
--- a/src/free_claude_code/core/anthropic/streaming/__init__.py
+++ b/src/free_claude_code/core/anthropic/streaming/__init__.py
@@ -4,55 +4,36 @@ from .emitter import (
ANTHROPIC_SSE_RESPONSE_HEADERS,
AnthropicSseEmitter,
anthropic_terminal_error_frame,
+ anthropic_terminal_failure_frame,
format_sse_event,
map_stop_reason,
)
from .ledger import AnthropicStreamLedger, StreamBlockLedger, ToolBlockState
from .recovery import (
- EARLY_TRANSPARENT_MAX_RETRIES,
- EARLY_TRANSPARENT_TOTAL_ATTEMPTS,
- MIDSTREAM_RECOVERY_ATTEMPTS,
- RECOVERY_BUFFER_MAX_BYTES,
- RecoveryController,
- RecoveryFailureAction,
- RecoveryHoldbackBuffer,
ToolSchema,
- TruncatedProviderStreamError,
accept_tool_json_repair,
continuation_suffix,
- is_retryable_stream_error,
make_text_recovery_body,
make_tool_repair_body,
parse_complete_tool_input,
tool_schemas_by_name,
)
-from .transient_errors import is_transient_overload_error, retryable_transient_status
__all__ = [
"ANTHROPIC_SSE_RESPONSE_HEADERS",
- "EARLY_TRANSPARENT_MAX_RETRIES",
- "EARLY_TRANSPARENT_TOTAL_ATTEMPTS",
- "MIDSTREAM_RECOVERY_ATTEMPTS",
- "RECOVERY_BUFFER_MAX_BYTES",
"AnthropicSseEmitter",
"AnthropicStreamLedger",
- "RecoveryController",
- "RecoveryFailureAction",
- "RecoveryHoldbackBuffer",
"StreamBlockLedger",
"ToolBlockState",
"ToolSchema",
- "TruncatedProviderStreamError",
"accept_tool_json_repair",
"anthropic_terminal_error_frame",
+ "anthropic_terminal_failure_frame",
"continuation_suffix",
"format_sse_event",
- "is_retryable_stream_error",
- "is_transient_overload_error",
"make_text_recovery_body",
"make_tool_repair_body",
"map_stop_reason",
"parse_complete_tool_input",
- "retryable_transient_status",
"tool_schemas_by_name",
]
diff --git a/src/free_claude_code/core/anthropic/streaming/emitter.py b/src/free_claude_code/core/anthropic/streaming/emitter.py
index 8c403b42..3fab009c 100644
--- a/src/free_claude_code/core/anthropic/streaming/emitter.py
+++ b/src/free_claude_code/core/anthropic/streaming/emitter.py
@@ -5,7 +5,9 @@ from typing import Any
from loguru import logger
-from ..errors import anthropic_error_payload
+from free_claude_code.core.failures import ExecutionFailure
+
+from ..errors import anthropic_error_payload, anthropic_failure_payload
ANTHROPIC_SSE_RESPONSE_HEADERS: dict[str, str] = {
"X-Accel-Buffering": "no",
@@ -42,6 +44,11 @@ def anthropic_terminal_error_frame(
)
+def anthropic_terminal_failure_frame(failure: ExecutionFailure) -> str:
+ """Serialize a canonical execution failure as a terminal SSE event."""
+ return format_sse_event("error", anthropic_failure_payload(failure))
+
+
class AnthropicSseEmitter:
"""Serialize Anthropic SSE events and optionally log raw event bodies."""
diff --git a/src/free_claude_code/core/anthropic/streaming/ledger.py b/src/free_claude_code/core/anthropic/streaming/ledger.py
index 6bce2a04..d20370b4 100644
--- a/src/free_claude_code/core/anthropic/streaming/ledger.py
+++ b/src/free_claude_code/core/anthropic/streaming/ledger.py
@@ -10,7 +10,6 @@ from typing import Any
from loguru import logger
-from free_claude_code.core.anthropic.errors import anthropic_error_payload
from free_claude_code.core.anthropic.stream_contracts import SSEEvent
from .emitter import AnthropicSseEmitter
@@ -389,14 +388,6 @@ class AnthropicStreamLedger:
if state.started:
yield self.stop_tool_block(tool_index)
- def emit_top_level_error(
- self, error_message: str, *, error_type: str = "api_error"
- ) -> str:
- return self._emitter.event(
- "error",
- anthropic_error_payload(error_type=error_type, message=error_message),
- )
-
def ingest_native_event(self, event: SSEEvent) -> str | None:
"""Record a native Anthropic SSE event and re-emit its normalized shape."""
if event.event == "message_start":
@@ -498,15 +489,6 @@ class AnthropicStreamLedger:
if not self.message_stopped:
yield self.message_stop()
- def terminal_error_tail(
- self, error_message: str, *, error_type: str = "api_error"
- ) -> Iterator[str]:
- """Terminate an incomplete message with an error, never a success stop."""
- if self.message_stopped:
- return
- yield from self.close_unclosed_blocks()
- yield self.emit_top_level_error(error_message, error_type=error_type)
-
def can_salvage_tool_use(self, schemas: dict[str, ToolSchema]) -> bool:
tool_blocks = self.tool_blocks()
if not tool_blocks:
diff --git a/src/free_claude_code/core/anthropic/streaming/lifecycle.py b/src/free_claude_code/core/anthropic/streaming/lifecycle.py
deleted file mode 100644
index 3d51a00c..00000000
--- a/src/free_claude_code/core/anthropic/streaming/lifecycle.py
+++ /dev/null
@@ -1,13 +0,0 @@
-"""Shared stream lifecycle types."""
-
-from .recovery import (
- RecoveryController,
- RecoveryDecision,
- RecoveryFailureAction,
-)
-
-__all__ = [
- "RecoveryController",
- "RecoveryDecision",
- "RecoveryFailureAction",
-]
diff --git a/src/free_claude_code/core/anthropic/streaming/recovery.py b/src/free_claude_code/core/anthropic/streaming/recovery.py
index d6edb394..422bb47c 100644
--- a/src/free_claude_code/core/anthropic/streaming/recovery.py
+++ b/src/free_claude_code/core/anthropic/streaming/recovery.py
@@ -1,28 +1,14 @@
-"""Shared retry and recovery policy for Anthropic streams."""
+"""Pure Anthropic continuation and tool-repair transformations."""
import json
-import time
-from collections.abc import Callable
from copy import deepcopy
from dataclasses import dataclass
-from enum import StrEnum
from typing import Any
-import httpx
import jsonschema
-import openai
from loguru import logger
-from free_claude_code.core.trace import trace_event
-
from ..models import MessagesRequest
-from .transient_errors import retryable_transient_status
-
-EARLY_TRANSPARENT_TOTAL_ATTEMPTS = 5
-EARLY_TRANSPARENT_MAX_RETRIES = EARLY_TRANSPARENT_TOTAL_ATTEMPTS - 1
-MIDSTREAM_RECOVERY_ATTEMPTS = 5
-EARLY_HOLDBACK_SECONDS = 0.75
-RECOVERY_BUFFER_MAX_BYTES = 65_536
_RECOVERY_USER_PREFIX = (
"The previous provider stream was interrupted. Continue the assistant response "
@@ -33,30 +19,6 @@ _RECOVERY_THINKING_PREFIX = (
)
-class TruncatedProviderStreamError(RuntimeError):
- """Raised internally when an upstream stream ends without a terminal marker."""
-
-
-class RecoveryFailureAction(StrEnum):
- """How the stream lifecycle should respond to an upstream failure."""
-
- EARLY_RETRY = "early_retry"
- MIDSTREAM_RECOVERY = "midstream_recovery"
- FINAL_ERROR = "final_error"
-
-
-@dataclass(frozen=True, slots=True)
-class RecoveryDecision:
- """Failure classification result for one stream exception."""
-
- action: RecoveryFailureAction
- retryable: bool
- committed: bool
- has_buffered: bool
- early_retry_attempt: int | None = None
- midstream_recovery_attempt: int | None = None
-
-
@dataclass(frozen=True, slots=True)
class ToolSchema:
"""Tool schema resolved from the original Anthropic request."""
@@ -73,182 +35,6 @@ class ToolRepair:
parsed_input: dict[str, Any]
-class RecoveryHoldbackBuffer:
- """Briefly hold downstream SSE so early stream cutoffs can be retried invisibly."""
-
- def __init__(
- self,
- *,
- holdback_seconds: float = EARLY_HOLDBACK_SECONDS,
- max_bytes: int = RECOVERY_BUFFER_MAX_BYTES,
- now: Callable[[], float] | None = None,
- ) -> None:
- self._holdback_seconds = holdback_seconds
- self._max_bytes = max_bytes
- self._now = now or time.monotonic
- self._events: list[str] = []
- self._bytes = 0
- self._started_at: float | None = None
- self.committed = False
-
- def push(self, event: str) -> list[str]:
- if self.committed:
- return [event]
- if self._started_at is None:
- self._started_at = self._now()
- self._events.append(event)
- self._bytes += len(event.encode("utf-8", errors="replace"))
- if (
- self._bytes >= self._max_bytes
- or self._now() - self._started_at >= self._holdback_seconds
- ):
- return self.flush()
- return []
-
- def flush(self) -> list[str]:
- if self.committed:
- return []
- self.committed = True
- events = self._events
- self._events = []
- self._bytes = 0
- self._started_at = None
- return events
-
- def discard(self) -> None:
- self._events = []
- self._bytes = 0
- self._started_at = None
-
- @property
- def has_buffered(self) -> bool:
- return bool(self._events)
-
-
-class RecoveryController:
- """Own holdback and failure classification for one provider stream lifecycle."""
-
- def __init__(self, *, provider_name: str, request_id: str | None) -> None:
- self._provider_name = provider_name
- self._request_id = request_id
- self._holdback = RecoveryHoldbackBuffer()
- self._early_retry_count = 0
- self._midstream_recovery_count = 0
-
- @property
- def committed(self) -> bool:
- return self._holdback.committed
-
- @property
- def has_buffered(self) -> bool:
- return self._holdback.has_buffered
-
- @property
- def early_retries(self) -> int:
- return self._early_retry_count
-
- @property
- def midstream_recoveries(self) -> int:
- return self._midstream_recovery_count
-
- def push(self, event: str) -> list[str]:
- return self._holdback.push(event)
-
- def flush(self) -> list[str]:
- return self._holdback.flush()
-
- def discard(self) -> None:
- self._holdback.discard()
-
- def flush_uncommitted(self, decision: RecoveryDecision) -> list[str]:
- if not decision.committed and decision.has_buffered:
- return self.flush()
- return []
-
- def advance_failure(
- self,
- error: BaseException,
- *,
- stream_opened: bool,
- generated_output: bool,
- complete_tool_salvageable: bool,
- ) -> RecoveryDecision:
- retryable = is_retryable_stream_error(error)
- committed = self._holdback.committed
- has_buffered = self._holdback.has_buffered
-
- if (
- retryable
- and stream_opened
- and not committed
- and not complete_tool_salvageable
- and self._early_retry_count < EARLY_TRANSPARENT_MAX_RETRIES
- ):
- self._early_retry_count += 1
- self._holdback.discard()
- self._holdback = RecoveryHoldbackBuffer()
- trace_event(
- stage="provider",
- event="provider.recovery.early_retry",
- source="provider",
- provider=self._provider_name,
- request_id=self._request_id,
- retry_attempt=self._early_retry_count,
- retryable=True,
- )
- return RecoveryDecision(
- action=RecoveryFailureAction.EARLY_RETRY,
- retryable=True,
- committed=False,
- has_buffered=has_buffered,
- early_retry_attempt=self._early_retry_count,
- )
-
- if (
- retryable
- and generated_output
- and self._midstream_recovery_count < MIDSTREAM_RECOVERY_ATTEMPTS
- ):
- self._midstream_recovery_count += 1
- return RecoveryDecision(
- action=RecoveryFailureAction.MIDSTREAM_RECOVERY,
- retryable=True,
- committed=committed,
- has_buffered=has_buffered,
- midstream_recovery_attempt=self._midstream_recovery_count,
- )
-
- return RecoveryDecision(
- action=RecoveryFailureAction.FINAL_ERROR,
- retryable=retryable,
- committed=committed,
- has_buffered=has_buffered,
- )
-
-
-def is_retryable_stream_error(exc: BaseException) -> bool:
- """Return whether a provider stream error can be retried/recovered."""
- if isinstance(exc, TruncatedProviderStreamError):
- return True
- if isinstance(exc, openai.AuthenticationError | openai.BadRequestError):
- return False
- if retryable_transient_status(exc) is not None:
- return True
- return isinstance(
- exc,
- (
- TimeoutError,
- httpx.ReadTimeout,
- httpx.ReadError,
- httpx.RemoteProtocolError,
- httpx.ConnectError,
- httpx.NetworkError,
- openai.APITimeoutError,
- openai.APIConnectionError,
- ),
- )
-
-
def tool_schemas_by_name(request: MessagesRequest) -> dict[str, ToolSchema]:
"""Return Anthropic tool input schemas keyed by tool name."""
schemas: dict[str, ToolSchema] = {}
diff --git a/src/free_claude_code/core/anthropic/streaming/transient_errors.py b/src/free_claude_code/core/anthropic/streaming/transient_errors.py
deleted file mode 100644
index 93bae305..00000000
--- a/src/free_claude_code/core/anthropic/streaming/transient_errors.py
+++ /dev/null
@@ -1,154 +0,0 @@
-"""Provider-neutral transient upstream error classification."""
-
-import json
-from collections.abc import Mapping
-from contextlib import suppress
-from typing import Any
-
-import httpx
-import openai
-
-_RATE_LIMIT_MARKERS = frozenset(
- {
- "rate_limit",
- "rate limit",
- "too many requests",
- }
-)
-_OVERLOAD_MARKERS = frozenset(
- {
- "resourceexhausted",
- "resource exhausted",
- "limit reached",
- "overloaded",
- "capacity",
- }
-)
-_INTERNAL_ERROR_MARKERS = frozenset(
- {
- "internal_server_error",
- "internal server error",
- }
-)
-
-
-def retryable_transient_status(exc: BaseException) -> int | None:
- """Return an HTTP-like retryable status inferred from an upstream exception."""
- if isinstance(exc, openai.RateLimitError):
- return 429
- if isinstance(exc, httpx.HTTPStatusError):
- status = exc.response.status_code
- return status if _is_retryable_status(status) else None
-
- status = _status_from_exception(exc)
- if _is_retryable_status(status):
- return status
-
- body = getattr(exc, "body", None)
- body_status = _status_from_body(body)
- if _is_retryable_status(body_status):
- return body_status
-
- text = transient_error_text(exc)
- if _has_marker(text, _RATE_LIMIT_MARKERS):
- return 429
- if _has_marker(text, _OVERLOAD_MARKERS):
- return 503
- if _has_marker(text, _INTERNAL_ERROR_MARKERS):
- return 500
- return None
-
-
-def is_transient_overload_error(exc: BaseException) -> bool:
- """Return whether an upstream exception indicates overload/capacity pressure."""
- return _has_marker(transient_error_text(exc), _OVERLOAD_MARKERS)
-
-
-def transient_error_text(exc: BaseException) -> str:
- """Return normalized exception/body/response text for transient classifiers."""
- parts = [str(exc)]
- body = getattr(exc, "body", None)
- if body is not None:
- parts.append(_body_to_text(body))
- response = getattr(exc, "response", None)
- if response is not None:
- with suppress(Exception):
- parts.append(response.text)
- return " ".join(part for part in parts if part).lower()
-
-
-def _status_from_exception(exc: BaseException) -> int | None:
- status = getattr(exc, "status_code", None)
- return status if isinstance(status, int) else None
-
-
-def _status_from_body(body: Any) -> int | None:
- for item in _body_candidates(body):
- if not isinstance(item, Mapping):
- continue
- for key in ("status", "status_code", "code"):
- status = _coerce_status(item.get(key))
- if status is not None:
- return status
- type_status = _status_from_type_fields(item)
- if type_status is not None:
- return type_status
- return None
-
-
-def _body_candidates(body: Any) -> tuple[Any, ...]:
- if isinstance(body, str):
- try:
- parsed = json.loads(body)
- except ValueError:
- return (body,)
- return _body_candidates(parsed)
- if isinstance(body, bytes):
- return _body_candidates(body.decode("utf-8", errors="replace"))
- if isinstance(body, Mapping):
- nested = body.get("error")
- return (body, nested) if isinstance(nested, Mapping) else (body,)
- return (body,)
-
-
-def _coerce_status(value: Any) -> int | None:
- if isinstance(value, int):
- return value
- if isinstance(value, str) and value.isdigit():
- return int(value)
- return None
-
-
-def _status_from_type_fields(item: Mapping[str, Any]) -> int | None:
- values = []
- for key in ("type", "code"):
- value = item.get(key)
- if isinstance(value, str):
- values.append(value.lower())
- text = " ".join(values)
- if _has_marker(text, _RATE_LIMIT_MARKERS):
- return 429
- if _has_marker(text, _OVERLOAD_MARKERS):
- return 503
- if _has_marker(text, _INTERNAL_ERROR_MARKERS):
- return 500
- return None
-
-
-def _body_to_text(body: Any) -> str:
- if isinstance(body, bytes):
- return body.decode("utf-8", errors="replace")
- if isinstance(body, str):
- return body
- try:
- return json.dumps(body, ensure_ascii=False, separators=(",", ":"))
- except TypeError:
- return str(body)
-
-
-def _has_marker(text: str, markers: frozenset[str]) -> bool:
- return any(marker in text for marker in markers)
-
-
-def _is_retryable_status(status: int | None) -> bool:
- return isinstance(status, int) and (status == 429 or 500 <= status <= 599)
diff --git a/src/free_claude_code/core/diagnostics.py b/src/free_claude_code/core/diagnostics.py
new file mode 100644
index 00000000..1335dd76
--- /dev/null
+++ b/src/free_claude_code/core/diagnostics.py
@@ -0,0 +1,301 @@
+"""Credential-safe diagnostics shared across product boundaries."""
+
+import json
+import re
+import traceback
+from dataclasses import dataclass
+from typing import Any
+
+from .failures import ExecutionFailure
+
+ERROR_DETAIL_DISPLAY_CAP_BYTES = 16_384
+_MAX_CAUSE_CHAIN_DEPTH = 4
+_UPSTREAM_BODY_ATTR = "_fcc_upstream_error_body"
+_UPSTREAM_BODY_TRUNCATED_ATTR = "_fcc_upstream_error_body_truncated"
+
+_SECRET_TEXT_REPLACEMENTS = (
+ (
+ re.compile(
+ r"(?i)(?P<prefix>[\"']?authorization[\"']?\s*[:=]\s*)"
+ r"(?P<quote>[\"']?)(?:(?:bearer|basic)\s+)?"
+ r"[^\"'\s,;&}\]]+(?P=quote)"
+ ),
+ r"\g<prefix>\g<quote><redacted>\g<quote>",
+ ),
+ (
+ re.compile(
+ r"(?i)(?P<prefix>[\"']?(?:api[_-]?key|access[_-]?token|"
+ r"refresh[_-]?token|token|client[_-]?secret|secret|password)"
+ r"[\"']?\s*[:=]\s*)(?P<quote>[\"']?)"
+ r"[^\"'\s,;&}\]]+(?P=quote)"
+ ),
+ r"\g<prefix>\g<quote><redacted>\g<quote>",
+ ),
+ (re.compile(r"(?i)(bearer\s+)[^\s,;]+"), r"\1<redacted>"),
+ (
+ re.compile(
+ r"(?i)(?<![a-z0-9])(?:sk-[a-z0-9._-]{8,}|"
+ r"nvapi-[a-z0-9._-]{8,}|hf_[a-z0-9_-]{8,}|"
+ r"gsk_[a-z0-9_-]{8,}|github_pat_[a-z0-9_]{8,}|"
+ r"gh[pousr]_[a-z0-9]{8,}|AIza[a-z0-9_-]{20,})"
+ r"(?![a-z0-9])"
+ ),
+ "<redacted>",
+ ),
+)
+
+
+@dataclass(frozen=True, slots=True)
+class UpstreamErrorDetail:
+ """Sanitized diagnostic detail extracted from an upstream exception."""
+
+ status_code: int | None = None
+ body_text: str | None = None
+ exception_text: str | None = None
+ cause_chain_text: str | None = None
+ category_hint: str | None = None
+ body_truncated: bool = False
+
+
+def redact_sensitive_error_text(text: str) -> str:
+ """Redact recognizable credentials while preserving diagnostic context."""
+ sanitized = text
+ for pattern, replacement in _SECRET_TEXT_REPLACEMENTS:
+ sanitized = pattern.sub(replacement, sanitized)
+ return sanitized
+
+
+def safe_exception_message(
+ exc: BaseException,
+ *,
+ fallback: str = "Provider request failed unexpectedly.",
+) -> str:
+ """Return a redacted, non-empty exception message."""
+ message = redact_sensitive_error_text(str(exc).strip())
+ return message or fallback
+
+
+def format_user_error_preview(exc: BaseException, *, max_len: int = 200) -> str:
+ """Return a short redacted exception preview for chat surfaces."""
+ return safe_exception_message(exc)[:max_len]
+
+
+def attach_upstream_error_body(
+ exc: Exception,
+ body: bytes | str,
+ *,
+ truncated: bool = False,
+) -> None:
+ """Attach a bounded streamed response body for later safe formatting."""
+ setattr(exc, _UPSTREAM_BODY_ATTR, body)
+ setattr(exc, _UPSTREAM_BODY_TRUNCATED_ATTR, truncated)
+
+
+def exception_cause_types(exc: BaseException) -> tuple[str, ...]:
+ """Return exception cause type names without logging their contents."""
+ return tuple(type(cause).__name__ for cause in _exception_causes(exc))
+
+
+def redacted_exception_traceback(exc: BaseException) -> str:
+ """Format a traceback while redacting recognizable credentials."""
+ return redact_sensitive_error_text("".join(traceback.format_exception(exc)))
+
+
+def extract_upstream_error_detail(exc: Exception) -> UpstreamErrorDetail:
+ """Extract bounded, redacted body, exception, and cause-chain details."""
+ raw_body = getattr(exc, _UPSTREAM_BODY_ATTR, None)
+ body_truncated = bool(getattr(exc, _UPSTREAM_BODY_TRUNCATED_ATTR, False))
+ if raw_body is None:
+ raw_body = getattr(exc, "body", None)
+ if raw_body is None:
+ raw_body = _body_from_response(exc)
+
+ body_text = _normalize_body_text(raw_body)
+ if body_text is not None:
+ body_text = redact_sensitive_error_text(body_text)
+ body_text, capped = _cap_text_bytes(body_text)
+ body_truncated = body_truncated or capped
+
+ exception_text = str(exc).strip() or None
+ if exception_text is not None:
+ exception_text = redact_sensitive_error_text(exception_text)
+ exception_text, _ = _cap_text_bytes(exception_text)
+
+ return UpstreamErrorDetail(
+ status_code=_status_code_from_exception(exc),
+ body_text=body_text,
+ exception_text=exception_text,
+ cause_chain_text=_exception_cause_chain_text(exc),
+ category_hint=_category_hint_from_body(raw_body, body_text),
+ body_truncated=body_truncated,
+ )
+
+
+def format_execution_failure_message(
+ failure: ExecutionFailure,
+ detail: UpstreamErrorDetail,
+ *,
+ upstream_name: str,
+ request_id: str | None = None,
+) -> str:
+ """Build a copyable, redacted diagnostic for a finalized execution failure."""
+ stable_message = failure.message
+ has_upstream_detail = detail.status_code is not None or detail.body_text is not None
+ if not has_upstream_detail:
+ lines = [stable_message]
+ if detail.exception_text and detail.exception_text != stable_message:
+ lines.extend(("", "Provider exception:", detail.exception_text))
+ if detail.cause_chain_text:
+ lines.extend(("", "Caused by:", detail.cause_chain_text))
+ _append_request_id_lines(lines, request_id)
+ return "\n".join(lines)
+
+ if detail.status_code == 405:
+ lines = [
+ f"Upstream provider {upstream_name} rejected the request method "
+ "or endpoint (HTTP 405)."
+ ]
+ elif detail.status_code is not None:
+ lines = [
+ f"Upstream provider {upstream_name} returned HTTP {detail.status_code}."
+ ]
+ else:
+ lines = [f"Upstream provider {upstream_name} returned an error."]
+
+ lines.append(f"Category: {detail.category_hint or failure.kind.value}")
+ if stable_message and stable_message != lines[0]:
+ lines.append(f"Mapped message: {stable_message}")
+ lines.extend(("", "Upstream error:"))
+ lines.append(detail.body_text or "(empty upstream error body)")
+ if _body_truncation_line_needed(detail):
+ lines.append(f"... [truncated after {ERROR_DETAIL_DISPLAY_CAP_BYTES} bytes]")
+ _append_request_id_lines(lines, request_id)
+ return "\n".join(lines)
+
+
+def _body_truncation_line_needed(detail: UpstreamErrorDetail) -> bool:
+ """Return whether a separate truncation marker is needed."""
+ return detail.body_truncated and (
+ detail.body_text is None
+ or f"truncated after {ERROR_DETAIL_DISPLAY_CAP_BYTES} bytes"
+ not in detail.body_text
+ )
+
+
+def _status_code_from_exception(exc: Exception) -> int | None:
+ status = getattr(exc, "status_code", None)
+ if isinstance(status, int):
+ return status
+ response = getattr(exc, "response", None)
+ response_status = getattr(response, "status_code", None)
+ return response_status if isinstance(response_status, int) else None
+
+
+def _body_from_response(exc: Exception) -> Any:
+ response = getattr(exc, "response", None)
+ if response is None:
+ return None
+ try:
+ return response.json()
+ except Exception:
+ pass
+ try:
+ return response.text
+ except Exception:
+ return None
+
+
+def _normalize_body_text(body: Any) -> str | None:
+ if body is None:
+ return None
+ if isinstance(body, bytes):
+ text = body.decode("utf-8", errors="replace")
+ elif isinstance(body, str):
+ text = body
+ else:
+ try:
+ return json.dumps(body, ensure_ascii=False, separators=(",", ":"))
+ except TypeError:
+ text = str(body)
+ stripped = text.strip()
+ if not stripped:
+ return None
+ try:
+ parsed = json.loads(stripped)
+ except ValueError:
+ return stripped
+ return json.dumps(parsed, ensure_ascii=False, separators=(",", ":"))
+
+
+def _cap_text_bytes(text: str) -> tuple[str, bool]:
+ encoded = text.encode("utf-8", errors="replace")
+ if len(encoded) <= ERROR_DETAIL_DISPLAY_CAP_BYTES:
+ return text, False
+ capped = encoded[:ERROR_DETAIL_DISPLAY_CAP_BYTES].decode("utf-8", errors="replace")
+ return (
+ f"{capped}\n... [truncated after {ERROR_DETAIL_DISPLAY_CAP_BYTES} bytes]",
+ True,
+ )
+
+
+def _exception_causes(exc: BaseException) -> tuple[BaseException, ...]:
+ causes: list[BaseException] = []
+ seen = {id(exc)}
+ current: BaseException | None = exc
+ while current is not None and len(causes) < _MAX_CAUSE_CHAIN_DEPTH:
+ next_exc = current.__cause__ or current.__context__
+ if next_exc is None or id(next_exc) in seen:
+ break
+ seen.add(id(next_exc))
+ causes.append(next_exc)
+ current = next_exc
+ return tuple(causes)
+
+
+def _exception_cause_chain_text(exc: BaseException) -> str | None:
+ lines: list[str] = []
+ for cause in _exception_causes(exc):
+ raw_text = str(cause).strip()
+ lines.append(
+ f"{type(cause).__name__}: {redact_sensitive_error_text(raw_text)}"
+ if raw_text
+ else type(cause).__name__
+ )
+ if not lines:
+ return None
+ text, _ = _cap_text_bytes("\n".join(lines))
+ return text
+
+
+def _category_hint_from_body(body: Any, body_text: str | None) -> str | None:
+ parsed = body
+ if isinstance(parsed, bytes):
+ parsed = parsed.decode("utf-8", errors="replace")
+ if isinstance(parsed, str):
+ try:
+ parsed = json.loads(parsed)
+ except ValueError:
+ parsed = None
+ if isinstance(parsed, dict):
+ error = parsed.get("error")
+ if isinstance(error, dict):
+ for key in ("type", "code"):
+ value = error.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ for key in ("type", "code"):
+ value = parsed.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ if (
+ body_text
+ and "model" in body_text.lower()
+ and "unsupported" in body_text.lower()
+ ):
+ return "upstream_model_error"
+ return None
+
+
+def _append_request_id_lines(lines: list[str], request_id: str | None) -> None:
+ if request_id:
+ lines.extend(("", f"Request ID: {request_id}"))
diff --git a/src/free_claude_code/core/failures.py b/src/free_claude_code/core/failures.py
new file mode 100644
index 00000000..c2dacbf5
--- /dev/null
+++ b/src/free_claude_code/core/failures.py
@@ -0,0 +1,49 @@
+"""Protocol-neutral execution failure semantics."""
+
+from dataclasses import FrozenInstanceError, dataclass
+from enum import StrEnum
+
+
+class FailureKind(StrEnum):
+ """Stable failure categories shared across execution and wire adapters."""
+
+ INVALID_REQUEST = "invalid_request"
+ AUTHENTICATION = "authentication"
+ PERMISSION = "permission"
+ RATE_LIMIT = "rate_limit"
+ OVERLOADED = "overloaded"
+ TIMEOUT = "timeout"
+ UPSTREAM = "upstream"
+ UNAVAILABLE = "unavailable"
+
+
+@dataclass(slots=True, eq=False)
+class ExecutionFailure(Exception):
+ """A finalized provider-execution failure independent of any wire protocol."""
+
+ kind: FailureKind
+ status_code: int
+ message: str
+ retryable: bool
+
+ def __post_init__(self) -> None:
+ Exception.__init__(self, self.message)
+
+ def __setattr__(self, name: str, value: object) -> None:
+ # Exception machinery must be able to update __traceback__, __cause__,
+ # and __context__ while semantic failure fields remain immutable.
+ if name in self.__slots__ and hasattr(self, name):
+ raise FrozenInstanceError(f"cannot assign to field {name!r}")
+ super().__setattr__(name, value)
+
+
+def find_execution_failure(exc: BaseException) -> ExecutionFailure | None:
+ """Return the first canonical failure in an exception or nested group."""
+ pending = [exc]
+ while pending:
+ current = pending.pop()
+ if isinstance(current, ExecutionFailure):
+ return current
+ if isinstance(current, BaseExceptionGroup):
+ pending.extend(reversed(current.exceptions))
+ return None
diff --git a/src/free_claude_code/core/openai_responses/__init__.py b/src/free_claude_code/core/openai_responses/__init__.py
index 37c7b444..3835f8ce 100644
--- a/src/free_claude_code/core/openai_responses/__init__.py
+++ b/src/free_claude_code/core/openai_responses/__init__.py
@@ -1,6 +1,17 @@
"""OpenAI Responses protocol adapter."""
from .adapter import OpenAIResponsesAdapter
+from .errors import (
+ openai_error_payload,
+ openai_error_type_for_failure,
+ openai_failure_payload,
+)
from .models import OpenAIResponsesRequest
-__all__ = ["OpenAIResponsesAdapter", "OpenAIResponsesRequest"]
+__all__ = [
+ "OpenAIResponsesAdapter",
+ "OpenAIResponsesRequest",
+ "openai_error_payload",
+ "openai_error_type_for_failure",
+ "openai_failure_payload",
+]
diff --git a/src/free_claude_code/core/openai_responses/adapter.py b/src/free_claude_code/core/openai_responses/adapter.py
index 6fe414e1..bb0e2ac5 100644
--- a/src/free_claude_code/core/openai_responses/adapter.py
+++ b/src/free_claude_code/core/openai_responses/adapter.py
@@ -7,7 +7,10 @@ from .errors import ResponsesConversionError, openai_error_payload
from .events import OPENAI_RESPONSES_SSE_HEADERS
from .input import convert_request_to_anthropic_payload
from .models import OpenAIResponsesRequest
-from .stream import iter_responses_sse_from_anthropic
+from .stream import (
+ PostStartTerminalFailureObserver,
+ iter_responses_sse_from_anthropic,
+)
class OpenAIResponsesAdapter:
@@ -23,8 +26,14 @@ class OpenAIResponsesAdapter:
self,
chunks: AsyncIterable[Any],
request: OpenAIResponsesRequest,
+ *,
+ on_post_start_terminal_failure: PostStartTerminalFailureObserver | None = None,
) -> AsyncIterator[str]:
- return iter_responses_sse_from_anthropic(chunks, request)
+ return iter_responses_sse_from_anthropic(
+ chunks,
+ request,
+ on_post_start_terminal_failure=on_post_start_terminal_failure,
+ )
def error_payload(self, *, message: str, error_type: str) -> dict[str, Any]:
return openai_error_payload(message=message, error_type=error_type)
diff --git a/src/free_claude_code/core/openai_responses/errors.py b/src/free_claude_code/core/openai_responses/errors.py
index ec219fb7..1e288670 100644
--- a/src/free_claude_code/core/openai_responses/errors.py
+++ b/src/free_claude_code/core/openai_responses/errors.py
@@ -2,13 +2,45 @@
from typing import Any
-from free_claude_code.core.anthropic.errors import redact_sensitive_error_text
+from free_claude_code.core.diagnostics import redact_sensitive_error_text
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
+
+_FAILURE_ERROR_TYPES = {
+ FailureKind.INVALID_REQUEST: "invalid_request_error",
+ FailureKind.AUTHENTICATION: "authentication_error",
+ FailureKind.PERMISSION: "permission_error",
+ FailureKind.RATE_LIMIT: "rate_limit_error",
+ FailureKind.OVERLOADED: "overloaded_error",
+ FailureKind.TIMEOUT: "api_error",
+ FailureKind.UPSTREAM: "api_error",
+ FailureKind.UNAVAILABLE: "api_error",
+}
class ResponsesConversionError(ValueError):
"""Raised when a Responses request cannot be converted deterministically."""
+def openai_error_type_for_failure(
+ failure: FailureKind | ExecutionFailure,
+) -> str:
+ """Map neutral failure semantics to an OpenAI-compatible error type."""
+ if isinstance(failure, ExecutionFailure):
+ if failure.kind == FailureKind.PERMISSION and failure.status_code == 402:
+ return "billing_error"
+ if failure.kind == FailureKind.INVALID_REQUEST:
+ if failure.status_code == 404:
+ return "not_found_error"
+ if failure.status_code == 413:
+ return "request_too_large"
+ if failure.kind == FailureKind.TIMEOUT and failure.status_code == 504:
+ return "timeout_error"
+ kind = failure.kind
+ else:
+ kind = failure
+ return _FAILURE_ERROR_TYPES[kind]
+
+
def openai_error_payload(*, message: str, error_type: str) -> dict[str, Any]:
"""Return an OpenAI-compatible error envelope."""
@@ -20,3 +52,16 @@ def openai_error_payload(*, message: str, error_type: str) -> dict[str, Any]:
"code": None,
}
}
+
+
+def openai_error_from_failure(failure: ExecutionFailure) -> dict[str, Any]:
+ """Return the inner OpenAI error object for a canonical failure."""
+ return openai_error_payload(
+ message=failure.message,
+ error_type=openai_error_type_for_failure(failure),
+ )["error"]
+
+
+def openai_failure_payload(failure: ExecutionFailure) -> dict[str, Any]:
+ """Return an OpenAI-compatible envelope for a canonical failure."""
+ return {"error": openai_error_from_failure(failure)}
diff --git a/src/free_claude_code/core/openai_responses/stream.py b/src/free_claude_code/core/openai_responses/stream.py
index a71547d4..510764e8 100644
--- a/src/free_claude_code/core/openai_responses/stream.py
+++ b/src/free_claude_code/core/openai_responses/stream.py
@@ -1,23 +1,26 @@
"""Translate Anthropic SSE streams into OpenAI Responses SSE streams."""
import asyncio
-from collections.abc import AsyncIterable, AsyncIterator
+from collections.abc import AsyncIterable, AsyncIterator, Callable
from typing import Any
-from free_claude_code.core.anthropic import get_user_facing_error_message
-from free_claude_code.core.trace import trace_event
+from free_claude_code.core.diagnostics import safe_exception_message
+from free_claude_code.core.failures import ExecutionFailure, find_execution_failure
from .anthropic_sse import iter_sse_events
from .models import OpenAIResponsesRequest
from .streaming import ResponsesStreamAssembler
+PostStartTerminalFailureObserver = Callable[[BaseException], None]
+
async def iter_responses_sse_from_anthropic(
chunks: AsyncIterable[Any],
request: OpenAIResponsesRequest,
+ *,
+ on_post_start_terminal_failure: PostStartTerminalFailureObserver | None = None,
) -> AsyncIterator[str]:
"""Yield Responses SSE events translated from an Anthropic SSE stream."""
-
assembler = ResponsesStreamAssembler(request)
emitted_any_chunk = False
try:
@@ -34,41 +37,46 @@ async def iter_responses_sse_from_anthropic(
raise
except asyncio.CancelledError:
raise
- except BaseExceptionGroup as exc:
+ except ExecutionFailure as exc:
if not emitted_any_chunk:
raise
- trace_event(
- stage="responses",
- event="responses.stream.terminal_failure_frame",
- source="openai_responses",
- exc_type=type(exc).__name__,
- )
- for chunk in assembler.fail_response(
- {
- "error": {
- "type": "api_error",
- "message": get_user_facing_error_message(exc),
- }
- }
- ):
+ _observe_post_start_terminal_failure(on_post_start_terminal_failure, exc)
+ for chunk in assembler.fail_execution(exc):
yield chunk
- return
+ except BaseExceptionGroup as exc:
+ if not emitted_any_chunk:
+ raise
+ failure = find_execution_failure(exc)
+ if failure is not None:
+ _observe_post_start_terminal_failure(
+ on_post_start_terminal_failure, failure
+ )
+ for chunk in assembler.fail_execution(failure):
+ yield chunk
+ else:
+ _observe_post_start_terminal_failure(on_post_start_terminal_failure, exc)
+ for chunk in assembler.fail_response(_unexpected_error_data(exc)):
+ yield chunk
except Exception as exc:
if not emitted_any_chunk:
raise
- trace_event(
- stage="responses",
- event="responses.stream.terminal_failure_frame",
- source="openai_responses",
- exc_type=type(exc).__name__,
- )
- for chunk in assembler.fail_response(
- {
- "error": {
- "type": "api_error",
- "message": get_user_facing_error_message(exc),
- }
- }
- ):
+ _observe_post_start_terminal_failure(on_post_start_terminal_failure, exc)
+ for chunk in assembler.fail_response(_unexpected_error_data(exc)):
yield chunk
- return
+
+
+def _observe_post_start_terminal_failure(
+ observer: PostStartTerminalFailureObserver | None,
+ exc: BaseException,
+) -> None:
+ if observer is not None:
+ observer(exc)
+
+
+def _unexpected_error_data(exc: BaseException) -> dict[str, dict[str, str]]:
+ return {
+ "error": {
+ "type": "api_error",
+ "message": safe_exception_message(exc),
+ }
+ }
diff --git a/src/free_claude_code/core/openai_responses/streaming/assembler.py b/src/free_claude_code/core/openai_responses/streaming/assembler.py
index 535fd5bd..1511e3f7 100644
--- a/src/free_claude_code/core/openai_responses/streaming/assembler.py
+++ b/src/free_claude_code/core/openai_responses/streaming/assembler.py
@@ -6,10 +6,11 @@ import uuid
from collections.abc import Mapping
from typing import Any
+from free_claude_code.core.failures import ExecutionFailure
from free_claude_code.core.trace import trace_event
from ..anthropic_sse import AnthropicSseEvent
-from ..errors import ResponsesConversionError
+from ..errors import ResponsesConversionError, openai_error_from_failure
from ..ids import (
new_call_id,
new_message_item_id,
@@ -41,6 +42,7 @@ class ResponsesStreamAssembler:
on_invalid_function_call=self._fail_invalid_function_call,
)
self._started = False
+ self._provisional_error: dict[str, Any] | None = None
self.terminal = False
self.final_response: dict[str, Any] | None = None
@@ -101,6 +103,9 @@ class ResponsesStreamAssembler:
chunks = self._flush_active_blocks()
if self.terminal:
return chunks
+ if self._provisional_error is not None:
+ chunks.extend(self._finish_failed_response(self._provisional_error))
+ return chunks
self.final_response = self.response_payload(status="completed")
chunks.append(events.response_completed(self.final_response))
self.terminal = True
@@ -111,10 +116,22 @@ class ResponsesStreamAssembler:
if self.terminal:
return chunks
error = openai_error_from_anthropic_error(data)
+ chunks.extend(self._finish_failed_response(error))
+ return chunks
+
+ def fail_execution(self, failure: ExecutionFailure) -> list[str]:
+ """Finish the current response with a canonical execution failure."""
+ chunks = self._flush_active_blocks()
+ if self.terminal:
+ return chunks
+ chunks.extend(self._finish_failed_response(openai_error_from_failure(failure)))
+ return chunks
+
+ def _finish_failed_response(self, error: dict[str, Any]) -> list[str]:
+ self._provisional_error = None
self.final_response = self.response_payload(status="failed", error=error)
- chunks.append(events.response_failed(self.final_response))
self.terminal = True
- return chunks
+ return [events.response_failed(self.final_response)]
def _ensure_started(self) -> list[str]:
if self._started:
@@ -321,9 +338,9 @@ class ResponsesStreamAssembler:
error_type=type(exc).__name__,
)
error = replay_unsafe_function_call_error()
- self.final_response = self.response_payload(status="failed", error=error)
- self.terminal = True
- return [events.response_failed(self.final_response)]
+ if self._provisional_error is None:
+ self._provisional_error = error
+ return []
def _event_index(data: Mapping[str, Any]) -> int | None:
diff --git a/src/free_claude_code/messaging/node_runner.py b/src/free_claude_code/messaging/node_runner.py
index 1d171c56..6b8eb941 100644
--- a/src/free_claude_code/messaging/node_runner.py
+++ b/src/free_claude_code/messaging/node_runner.py
@@ -5,9 +5,9 @@ from collections.abc import Callable
from loguru import logger
-from free_claude_code.core.anthropic import (
+from free_claude_code.core.diagnostics import (
format_user_error_preview,
- get_user_facing_error_message,
+ safe_exception_message,
)
from free_claude_code.core.trace import trace_event
@@ -193,7 +193,7 @@ class MessagingNodeRunner:
resume_session_arg=parent_session_id,
)
except RuntimeError as e:
- error_message = get_user_facing_error_message(e)
+ error_message = safe_exception_message(e)
transcript.apply({"type": "error", "message": error_message})
await update_ui(
self._format_status("⏳", "Session limit reached", None),
diff --git a/src/free_claude_code/messaging/platforms/discord.py b/src/free_claude_code/messaging/platforms/discord.py
index 655c65fe..f6cb6793 100644
--- a/src/free_claude_code/messaging/platforms/discord.py
+++ b/src/free_claude_code/messaging/platforms/discord.py
@@ -7,7 +7,7 @@ from typing import Any
from loguru import logger
-from free_claude_code.core.anthropic import format_user_error_preview
+from free_claude_code.core.diagnostics import format_user_error_preview
from ..limiter import MessagingRateLimiter
from ..models import IncomingMessage
diff --git a/src/free_claude_code/messaging/platforms/telegram.py b/src/free_claude_code/messaging/platforms/telegram.py
index 9aecc679..342e23e8 100644
--- a/src/free_claude_code/messaging/platforms/telegram.py
+++ b/src/free_claude_code/messaging/platforms/telegram.py
@@ -10,7 +10,7 @@ os.environ["PTB_TIMEDELTA"] = "1"
from loguru import logger
-from free_claude_code.core.anthropic import format_user_error_preview
+from free_claude_code.core.diagnostics import format_user_error_preview
from ..limiter import MessagingRateLimiter
from ..models import IncomingMessage
diff --git a/src/free_claude_code/messaging/platforms/voice_flow.py b/src/free_claude_code/messaging/platforms/voice_flow.py
index 31926130..907df9cb 100644
--- a/src/free_claude_code/messaging/platforms/voice_flow.py
+++ b/src/free_claude_code/messaging/platforms/voice_flow.py
@@ -10,7 +10,7 @@ from typing import Any
from loguru import logger
-from free_claude_code.core.anthropic import format_user_error_preview
+from free_claude_code.core.diagnostics import format_user_error_preview
from ..models import IncomingMessage
from ..voice import PendingVoiceRegistry, Transcriber
diff --git a/src/free_claude_code/messaging/trees/processor.py b/src/free_claude_code/messaging/trees/processor.py
index 876117a1..4af4546c 100644
--- a/src/free_claude_code/messaging/trees/processor.py
+++ b/src/free_claude_code/messaging/trees/processor.py
@@ -6,7 +6,7 @@ from collections.abc import Awaitable, Callable
from loguru import logger
from free_claude_code.config.settings import get_settings
-from free_claude_code.core.anthropic import get_user_facing_error_message
+from free_claude_code.core.diagnostics import safe_exception_message
from ..safe_diagnostics import format_exception_for_log
from .node import MessageNode, MessageState
@@ -98,7 +98,7 @@ class TreeQueueProcessor:
await tree.update_state(
node.node_id,
MessageState.ERROR,
- error_message=get_user_facing_error_message(e),
+ error_message=safe_exception_message(e),
)
finally:
async with tree.with_lock():
diff --git a/src/free_claude_code/providers/__init__.py b/src/free_claude_code/providers/__init__.py
index 9741e498..4507cb09 100644
--- a/src/free_claude_code/providers/__init__.py
+++ b/src/free_claude_code/providers/__init__.py
@@ -6,26 +6,8 @@ from ``providers.nvidia_nim`` etc. to avoid loading every adapter when the
"""
from .base import BaseProvider, ProviderConfig
-from .exceptions import (
- APIError,
- AuthenticationError,
- InvalidRequestError,
- ModelListResponseError,
- OverloadedError,
- ProviderError,
- RateLimitError,
- UnknownProviderTypeError,
-)
__all__ = [
- "APIError",
- "AuthenticationError",
"BaseProvider",
- "InvalidRequestError",
- "ModelListResponseError",
- "OverloadedError",
"ProviderConfig",
- "ProviderError",
- "RateLimitError",
- "UnknownProviderTypeError",
]
diff --git a/src/free_claude_code/providers/base.py b/src/free_claude_code/providers/base.py
index fc501dd8..6e39827a 100644
--- a/src/free_claude_code/providers/base.py
+++ b/src/free_claude_code/providers/base.py
@@ -3,11 +3,17 @@
from abc import ABC, abstractmethod
from collections.abc import AsyncIterator
+from loguru import logger
from pydantic import BaseModel
from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.constants import HTTP_CONNECT_TIMEOUT_DEFAULT
from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.diagnostics import (
+ exception_cause_types,
+ redacted_exception_traceback,
+)
+from free_claude_code.core.trace import trace_event
from free_claude_code.providers.model_listing import model_infos_from_ids
@@ -71,11 +77,6 @@ class BaseProvider(ABC):
request_id: str | None = None,
) -> None:
"""Log streaming transport failures (metadata-only unless verbose is enabled)."""
- from loguru import logger
-
- from free_claude_code.core.trace import trace_event
- from free_claude_code.providers.error_mapping import exception_cause_types
-
response = getattr(error, "response", None)
http_status = (
getattr(response, "status_code", None) if response is not None else None
@@ -93,8 +94,12 @@ class BaseProvider(ABC):
)
if self._config.log_api_error_tracebacks:
- logger.opt(exception=error).error(
- "{}_ERROR:{} {}: {}", tag, req_tag, type(error).__name__, error
+ logger.error(
+ "{}_ERROR:{} exc_type={}\n{}",
+ tag,
+ req_tag,
+ type(error).__name__,
+ redacted_exception_traceback(error),
)
return
logger.error(
diff --git a/src/free_claude_code/providers/cloudflare/client.py b/src/free_claude_code/providers/cloudflare/client.py
index 44e84f72..01c8c622 100644
--- a/src/free_claude_code/providers/cloudflare/client.py
+++ b/src/free_claude_code/providers/cloudflare/client.py
@@ -6,15 +6,13 @@ from urllib.parse import quote
import httpx
+from free_claude_code.application.errors import ApplicationUnavailableError
from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.defaults import CLOUDFLARE_AI_REST_ROOT
-from free_claude_code.providers.exceptions import (
- AuthenticationError,
- ModelListResponseError,
-)
from free_claude_code.providers.model_listing import (
+ ModelListResponseError,
extract_openai_model_ids,
model_infos_from_ids,
)
@@ -50,7 +48,7 @@ def _cloudflare_account_api_url(api_root: str | None, account_id: str) -> str:
stripped_account = account_id.strip()
if not stripped_account:
- raise AuthenticationError(
+ raise ApplicationUnavailableError(
"CLOUDFLARE_ACCOUNT_ID is not set. Add it to your .env file."
)
root = (api_root or CLOUDFLARE_AI_REST_ROOT).rstrip("/")
diff --git a/src/free_claude_code/providers/cohere/client.py b/src/free_claude_code/providers/cohere/client.py
index 3cfc03b8..399748d0 100644
--- a/src/free_claude_code/providers/cohere/client.py
+++ b/src/free_claude_code/providers/cohere/client.py
@@ -4,10 +4,10 @@ from collections.abc import Mapping
from copy import deepcopy
from typing import Any
+from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.defaults import COHERE_DEFAULT_BASE
-from free_claude_code.providers.exceptions import InvalidRequestError
from free_claude_code.providers.rate_limit import ProviderRateLimiter
from free_claude_code.providers.transports.openai_chat import (
OpenAIChatRequestPolicy,
diff --git a/src/free_claude_code/providers/deepseek/compat.py b/src/free_claude_code/providers/deepseek/compat.py
index c379fec8..ed2c7b3e 100644
--- a/src/free_claude_code/providers/deepseek/compat.py
+++ b/src/free_claude_code/providers/deepseek/compat.py
@@ -5,13 +5,13 @@ from typing import Any
from loguru import logger
+from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
from free_claude_code.core.anthropic import serialize_tool_result_content
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.anthropic.native_messages_request import (
dump_raw_messages_request,
)
-from free_claude_code.providers.exceptions import InvalidRequestError
from free_claude_code.providers.transports.openai_chat import (
OpenAIChatRequestPolicy,
build_openai_chat_request_body,
diff --git a/src/free_claude_code/providers/error_mapping.py b/src/free_claude_code/providers/error_mapping.py
deleted file mode 100644
index 7cd33e91..00000000
--- a/src/free_claude_code/providers/error_mapping.py
+++ /dev/null
@@ -1,407 +0,0 @@
-"""Provider-specific exception mapping and user-visible diagnostics."""
-
-import json
-from dataclasses import dataclass
-from typing import Any
-
-import httpx
-import openai
-
-from free_claude_code.config.constants import PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES
-from free_claude_code.core.anthropic import (
- get_user_facing_error_message,
- redact_sensitive_error_text,
-)
-from free_claude_code.core.anthropic.streaming import (
- is_transient_overload_error,
- retryable_transient_status,
-)
-from free_claude_code.providers.exceptions import (
- APIError,
- AuthenticationError,
- InvalidRequestError,
- OverloadedError,
- ProviderError,
- RateLimitError,
-)
-from free_claude_code.providers.rate_limit import ProviderRateLimiter
-
-_BODY_ATTR = "_fcc_provider_error_body"
-_BODY_TRUNCATED_ATTR = "_fcc_provider_error_body_truncated"
-_MAX_CAUSE_CHAIN_DEPTH = 4
-
-
-@dataclass(frozen=True)
-class ProviderErrorDetail:
- """Structured upstream error detail surfaced directly to users."""
-
- status_code: int | None = None
- body_text: str | None = None
- exception_text: str | None = None
- cause_chain_text: str | None = None
- error_type_hint: str | None = None
- body_truncated: bool = False
-
-
-def attach_provider_error_body(
- exc: Exception, body: bytes | str, *, truncated: bool = False
-) -> None:
- """Attach a streamed HTTP error body to an exception for later formatting."""
- setattr(exc, _BODY_ATTR, body)
- setattr(exc, _BODY_TRUNCATED_ATTR, truncated)
-
-
-def _status_code_from_exception(exc: Exception) -> int | None:
- status = getattr(exc, "status_code", None)
- if isinstance(status, int):
- return status
- response = getattr(exc, "response", None)
- response_status = getattr(response, "status_code", None)
- if isinstance(response_status, int):
- return response_status
- return None
-
-
-def _body_from_response(exc: Exception) -> Any:
- response = getattr(exc, "response", None)
- if response is None:
- return None
- try:
- return response.json()
- except ValueError, RuntimeError:
- pass
- try:
- return response.text
- except httpx.ResponseNotRead, RuntimeError:
- return None
-
-
-def _normalize_body_text(body: Any) -> str | None:
- if body is None:
- return None
- if isinstance(body, bytes):
- text = body.decode("utf-8", errors="replace")
- elif isinstance(body, str):
- text = body
- else:
- try:
- return json.dumps(body, ensure_ascii=False, separators=(",", ":"))
- except TypeError:
- text = str(body)
- stripped = text.strip()
- if not stripped:
- return None
- try:
- parsed = json.loads(stripped)
- except ValueError:
- return stripped
- return json.dumps(parsed, ensure_ascii=False, separators=(",", ":"))
-
-
-def _cap_text_bytes(text: str, max_bytes: int) -> tuple[str, bool]:
- encoded = text.encode("utf-8", errors="replace")
- if len(encoded) <= max_bytes:
- return text, False
- capped = encoded[:max_bytes].decode("utf-8", errors="replace")
- return f"{capped}\n... [truncated after {max_bytes} bytes]", True
-
-
-def _exception_causes(exc: BaseException) -> tuple[BaseException, ...]:
- causes: list[BaseException] = []
- seen: set[int] = {id(exc)}
- current: BaseException | None = exc
- while current is not None and len(causes) < _MAX_CAUSE_CHAIN_DEPTH:
- next_exc = current.__cause__ or current.__context__
- if next_exc is None or id(next_exc) in seen:
- break
- seen.add(id(next_exc))
- causes.append(next_exc)
- current = next_exc
- return tuple(causes)
-
-
-def exception_cause_types(exc: BaseException) -> tuple[str, ...]:
- """Return safe exception cause type names for default metadata logging."""
- return tuple(type(cause).__name__ for cause in _exception_causes(exc))
-
-
-def _exception_cause_chain_text(exc: BaseException) -> str | None:
- lines: list[str] = []
- for cause in _exception_causes(exc):
- raw_text = str(cause).strip()
- if raw_text:
- lines.append(
- f"{type(cause).__name__}: {redact_sensitive_error_text(raw_text)}"
- )
- else:
- lines.append(type(cause).__name__)
- if not lines:
- return None
- text = "\n".join(lines)
- capped, _ = _cap_text_bytes(text, PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES)
- return capped
-
-
-def _error_type_hint_from_body(body: Any, body_text: str | None) -> str | None:
- parsed = body
- if isinstance(parsed, bytes):
- text = parsed.decode("utf-8", errors="replace")
- try:
- parsed = json.loads(text)
- except ValueError:
- parsed = None
- elif isinstance(parsed, str):
- try:
- parsed = json.loads(parsed)
- except ValueError:
- parsed = None
- if isinstance(parsed, dict):
- error = parsed.get("error")
- if isinstance(error, dict):
- for key in ("type", "code"):
- value = error.get(key)
- if isinstance(value, str) and value.strip():
- return value.strip()
- for key in ("type", "code"):
- value = parsed.get(key)
- if isinstance(value, str) and value.strip():
- return value.strip()
- if (
- body_text
- and "model" in body_text.lower()
- and "unsupported" in body_text.lower()
- ):
- return "upstream_model_error"
- return None
-
-
-def extract_provider_error_detail(exc: Exception) -> ProviderErrorDetail:
- """Extract copyable upstream status/body/exception detail from provider errors."""
- raw_body = getattr(exc, _BODY_ATTR, None)
- raw_body_truncated = bool(getattr(exc, _BODY_TRUNCATED_ATTR, False))
- if raw_body is None:
- raw_body = getattr(exc, "body", None)
- if raw_body is None:
- raw_body = _body_from_response(exc)
-
- body_text = _normalize_body_text(raw_body)
- display_truncated = raw_body_truncated
- if body_text is not None:
- body_text = redact_sensitive_error_text(body_text)
- body_text, cap_truncated = _cap_text_bytes(
- body_text, PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES
- )
- display_truncated = display_truncated or cap_truncated
-
- exception_text = str(exc).strip() or None
- if exception_text is not None:
- exception_text = redact_sensitive_error_text(exception_text)
- exception_text, _ = _cap_text_bytes(
- exception_text, PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES
- )
-
- return ProviderErrorDetail(
- status_code=_status_code_from_exception(exc),
- body_text=body_text,
- exception_text=exception_text,
- cause_chain_text=_exception_cause_chain_text(exc),
- error_type_hint=_error_type_hint_from_body(raw_body, body_text),
- body_truncated=display_truncated,
- )
-
-
-def _provider_error_category(mapped: Exception) -> str | None:
- error_type = getattr(mapped, "error_type", None)
- if isinstance(error_type, str) and error_type.strip():
- return error_type.strip()
- return None
-
-
-def _append_request_id_lines(lines: list[str], request_id: str | None) -> None:
- if request_id:
- lines.extend(("", f"Request ID: {request_id}"))
-
-
-def format_provider_error_message(
- mapped: Exception,
- detail: ProviderErrorDetail,
- *,
- provider_name: str,
- read_timeout_s: float | None,
- request_id: str | None = None,
-) -> str:
- """Return a copyable user-facing provider error including upstream detail."""
- stable_message = get_user_facing_error_message(
- mapped, read_timeout_s=read_timeout_s
- )
- has_upstream_detail = detail.status_code is not None or detail.body_text is not None
- if not has_upstream_detail:
- lines = [stable_message]
- if detail.exception_text and detail.exception_text != stable_message:
- lines.extend(("", "Provider exception:", detail.exception_text))
- if detail.cause_chain_text:
- lines.extend(("", "Caused by:", detail.cause_chain_text))
- _append_request_id_lines(lines, request_id)
- return "\n".join(lines)
-
- if detail.status_code == 405:
- lines = [
- f"Upstream provider {provider_name} rejected the request method "
- "or endpoint (HTTP 405)."
- ]
- elif detail.status_code is not None:
- lines = [
- f"Upstream provider {provider_name} returned HTTP {detail.status_code}."
- ]
- else:
- lines = [f"Upstream provider {provider_name} returned an error."]
-
- category = detail.error_type_hint or _provider_error_category(mapped)
- if category:
- lines.append(f"Category: {category}")
- if stable_message and stable_message != lines[0]:
- lines.append(f"Mapped message: {stable_message}")
-
- lines.extend(("", "Upstream error:"))
- if detail.body_text:
- lines.append(detail.body_text)
- else:
- lines.append("(empty upstream error body)")
- if detail.body_truncated and (
- detail.body_text is None
- or f"truncated after {PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES} bytes"
- not in detail.body_text
- ):
- lines.append(
- f"... [truncated after {PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES} bytes]"
- )
-
- _append_request_id_lines(lines, request_id)
- return "\n".join(lines)
-
-
-def user_visible_message_for_mapped_provider_error(
- mapped: Exception,
- *,
- provider_name: str,
- read_timeout_s: float | None,
- detail: ProviderErrorDetail | None = None,
- request_id: str | None = None,
-) -> str:
- """Return the user-visible string after :func:`map_error` (405 + mapped types)."""
- if detail is not None:
- return format_provider_error_message(
- mapped,
- detail,
- provider_name=provider_name,
- read_timeout_s=read_timeout_s,
- request_id=request_id,
- )
- if getattr(mapped, "status_code", None) == 405:
- return (
- f"Upstream provider {provider_name} rejected the request method "
- "or endpoint (HTTP 405)."
- )
- return get_user_facing_error_message(mapped, read_timeout_s=read_timeout_s)
-
-
-def map_stream_start_error(
- error: Exception,
- *,
- provider_name: str,
- read_timeout_s: float | None,
- request_id: str | None,
- rate_limiter: ProviderRateLimiter,
-) -> ProviderError:
- """Map a final pre-start stream failure into an HTTP-serializable provider error.
-
- Providers call this only when no downstream-visible SSE chunk has escaped.
- At that boundary the API can still return a real non-200 response, which is
- preferable to synthesizing a successful SSE stream that starts with an error
- message.
- """
- mapped = map_error(error, rate_limiter=rate_limiter)
- detail = extract_provider_error_detail(error)
- message = user_visible_message_for_mapped_provider_error(
- mapped,
- provider_name=provider_name,
- read_timeout_s=read_timeout_s,
- detail=detail,
- request_id=request_id,
- )
- if isinstance(mapped, ProviderError):
- return ProviderError(
- message,
- status_code=mapped.status_code,
- error_type=mapped.error_type,
- raw_error=mapped.raw_error,
- )
- return APIError(message, status_code=502, raw_error=str(error))
-
-
-def map_error(e: Exception, *, rate_limiter: ProviderRateLimiter) -> Exception:
- """Map OpenAI or HTTPX exception to specific ProviderError.
-
- Streaming transports pass their owned limiter so reactive 429 handling
- applies only to that provider instance.
- """
- message = get_user_facing_error_message(e)
- limiter = rate_limiter
-
- if isinstance(e, openai.AuthenticationError):
- return AuthenticationError(message, raw_error=str(e))
- if isinstance(e, openai.RateLimitError):
- limiter.set_blocked(60)
- return RateLimitError(message, raw_error=str(e))
- if isinstance(e, openai.BadRequestError):
- return InvalidRequestError(message, raw_error=str(e))
- if isinstance(e, openai.InternalServerError):
- raw_message = str(e)
- sdk_status = retryable_transient_status(e) or getattr(e, "status_code", None)
- if is_transient_overload_error(e):
- return OverloadedError(message, raw_error=raw_message)
- if isinstance(sdk_status, int) and 500 <= sdk_status <= 599:
- stable = APIError("_", status_code=sdk_status)
- return APIError(
- get_user_facing_error_message(stable),
- status_code=sdk_status,
- raw_error=str(e),
- )
- return APIError(message, status_code=500, raw_error=str(e))
- if isinstance(e, openai.APIError):
- status = retryable_transient_status(e)
- if status == 429:
- limiter.set_blocked(60)
- return RateLimitError(
- "Provider rate limit reached. Please retry shortly.", raw_error=str(e)
- )
- if is_transient_overload_error(e):
- return OverloadedError(
- "Provider is currently overloaded. Please retry.", raw_error=str(e)
- )
- effective_status = status or getattr(e, "status_code", None)
- if not isinstance(effective_status, int):
- effective_status = 500
- stable = APIError("_", status_code=effective_status)
- return APIError(
- get_user_facing_error_message(stable),
- status_code=effective_status,
- raw_error=str(e),
- )
-
- if isinstance(e, httpx.HTTPStatusError):
- status = e.response.status_code
- if status in (401, 403):
- return AuthenticationError(message, raw_error=str(e))
- if status == 429:
- limiter.set_blocked(60)
- return RateLimitError(message, raw_error=str(e))
- if status == 400:
- return InvalidRequestError(message, raw_error=str(e))
- if status >= 500:
- if status in (502, 503, 504):
- return OverloadedError(message, raw_error=str(e))
- return APIError(message, status_code=status, raw_error=str(e))
- return APIError(message, status_code=status, raw_error=str(e))
-
- return e
diff --git a/src/free_claude_code/providers/exceptions.py b/src/free_claude_code/providers/exceptions.py
deleted file mode 100644
index d88bfeed..00000000
--- a/src/free_claude_code/providers/exceptions.py
+++ /dev/null
@@ -1,103 +0,0 @@
-"""Unified exception hierarchy for providers."""
-
-from typing import Any
-
-
-class ProviderError(Exception):
- """Base exception for all provider errors."""
-
- def __init__(
- self,
- message: str,
- status_code: int = 500,
- error_type: str = "api_error",
- raw_error: Any = None,
- ):
- super().__init__(message)
- self.message = message
- self.status_code = status_code
- self.error_type = error_type
- self.raw_error = raw_error
-
-
-class AuthenticationError(ProviderError):
- """Raised when API key is invalid or missing."""
-
- def __init__(self, message: str, raw_error: Any = None):
- super().__init__(
- message,
- status_code=401,
- error_type="authentication_error",
- raw_error=raw_error,
- )
-
-
-class InvalidRequestError(ProviderError):
- """Raised when the request parameters are invalid."""
-
- def __init__(self, message: str, raw_error: Any = None):
- super().__init__(
- message,
- status_code=400,
- error_type="invalid_request_error",
- raw_error=raw_error,
- )
-
-
-class RateLimitError(ProviderError):
- """Raised when rate limit is exceeded."""
-
- def __init__(self, message: str, raw_error: Any = None):
- super().__init__(
- message,
- status_code=429,
- error_type="rate_limit_error",
- raw_error=raw_error,
- )
-
-
-class OverloadedError(ProviderError):
- """Raised when the provider is overloaded."""
-
- def __init__(self, message: str, raw_error: Any = None):
- super().__init__(
- message,
- status_code=529,
- error_type="overloaded_error",
- raw_error=raw_error,
- )
-
-
-class APIError(ProviderError):
- """Raised when the provider returns a generic API error."""
-
- def __init__(self, message: str, status_code: int = 500, raw_error: Any = None):
- super().__init__(
- message,
- status_code=status_code,
- error_type="api_error",
- raw_error=raw_error,
- )
-
-
-class UnknownProviderTypeError(InvalidRequestError):
- """Raised when ``provider_id`` is not registered in the provider map."""
-
- def __init__(self, message: str) -> None:
- super().__init__(message)
-
-
-class ServiceUnavailableError(ProviderError):
- """Raised when the server is not ready (e.g. app lifespan did not wire state)."""
-
- def __init__(self, message: str, raw_error: Any = None):
- super().__init__(
- message,
- status_code=503,
- error_type="api_error",
- raw_error=raw_error,
- )
-
-
-class ModelListResponseError(ServiceUnavailableError):
- """Raised when a provider model-list response cannot be parsed safely."""
diff --git a/src/free_claude_code/providers/failure_policy.py b/src/free_claude_code/providers/failure_policy.py
new file mode 100644
index 00000000..c23d0164
--- /dev/null
+++ b/src/free_claude_code/providers/failure_policy.py
@@ -0,0 +1,378 @@
+"""Provider-owned SDK classification and retry qualification."""
+
+import json
+from collections.abc import Callable, Mapping
+from contextlib import suppress
+from dataclasses import replace
+from typing import Any
+
+import httpx
+import openai
+
+from free_claude_code.core.diagnostics import (
+ extract_upstream_error_detail,
+ format_execution_failure_message,
+ safe_exception_message,
+)
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
+
+MarkRateLimited = Callable[[float], None]
+
+_RATE_LIMIT_MARKERS = frozenset({"rate_limit", "rate limit", "too many requests"})
+_OVERLOAD_MARKERS = frozenset(
+ {
+ "resourceexhausted",
+ "resource exhausted",
+ "limit reached",
+ "overloaded",
+ "capacity",
+ }
+)
+_INTERNAL_ERROR_MARKERS = frozenset({"internal_server_error", "internal server error"})
+_AUTHENTICATION_MESSAGE = "Provider authentication failed. Check API key."
+_RATE_LIMIT_MESSAGE = "Provider rate limit reached. Please retry shortly."
+_INVALID_REQUEST_MESSAGE = "Invalid request sent to provider."
+_OVERLOADED_MESSAGE = "Provider is currently overloaded. Please retry."
+
+
+def classify_provider_failure(
+ exc: Exception,
+ *,
+ provider_name: str,
+ read_timeout_s: float | None,
+ request_id: str | None,
+ mark_rate_limited: MarkRateLimited,
+) -> ExecutionFailure:
+ """Return one detailed canonical failure after provider retries are exhausted."""
+ failure = _classify_provider_failure(
+ exc,
+ read_timeout_s=read_timeout_s,
+ mark_rate_limited=mark_rate_limited,
+ )
+ if isinstance(exc, ExecutionFailure):
+ message = failure.message
+ request_id_line = f"Request ID: {request_id}" if request_id else None
+ if request_id_line and request_id_line not in message:
+ message = f"{message}\n\n{request_id_line}"
+ return replace(failure, message=message)
+ message = format_execution_failure_message(
+ failure,
+ extract_upstream_error_detail(exc),
+ upstream_name=provider_name,
+ request_id=request_id,
+ )
+ return replace(failure, message=message)
+
+
+def retryable_transient_status(exc: BaseException) -> int | None:
+ """Infer a retryable HTTP-like status from one upstream exception."""
+ if isinstance(exc, ExecutionFailure):
+ status = exc.status_code
+ return status if exc.retryable and _is_retryable_status(status) else None
+ if isinstance(exc, openai.RateLimitError):
+ return 429
+ if isinstance(exc, httpx.HTTPStatusError):
+ status = exc.response.status_code
+ return status if _is_retryable_status(status) else None
+
+ status = _status_from_exception(exc)
+ if _is_retryable_status(status):
+ return status
+
+ body_status = _status_from_body(getattr(exc, "body", None))
+ if _is_retryable_status(body_status):
+ return body_status
+
+ text = transient_error_text(exc)
+ if _has_marker(text, _RATE_LIMIT_MARKERS):
+ return 429
+ if _has_marker(text, _OVERLOAD_MARKERS):
+ return 503
+ if _has_marker(text, _INTERNAL_ERROR_MARKERS):
+ return 500
+ return None
+
+
+def is_transient_overload_error(exc: BaseException) -> bool:
+ """Return whether an upstream exception reports overload or capacity pressure."""
+ if isinstance(exc, ExecutionFailure):
+ return exc.kind == FailureKind.OVERLOADED
+ return _has_marker(transient_error_text(exc), _OVERLOAD_MARKERS)
+
+
+def transient_error_text(exc: BaseException) -> str:
+ """Combine exception, body, and response text for provider classification."""
+ parts = [str(exc)]
+ body = getattr(exc, "body", None)
+ if body is not None:
+ parts.append(_body_to_text(body))
+ response = getattr(exc, "response", None)
+ if response is not None:
+ with suppress(Exception):
+ parts.append(response.text)
+ return " ".join(part for part in parts if part).lower()
+
+
+def is_retryable_provider_error(exc: BaseException) -> bool:
+ """Return whether provider policy permits stream retry or recovery."""
+ if isinstance(exc, ExecutionFailure):
+ return exc.retryable
+ if isinstance(exc, openai.AuthenticationError | openai.BadRequestError):
+ return False
+ if retryable_transient_status(exc) is not None:
+ return True
+ return isinstance(
+ exc,
+ (
+ TimeoutError,
+ httpx.TimeoutException,
+ httpx.ConnectError,
+ httpx.ReadError,
+ httpx.WriteError,
+ httpx.RemoteProtocolError,
+ httpx.NetworkError,
+ openai.APITimeoutError,
+ openai.APIConnectionError,
+ ),
+ )
+
+
+def retryable_upstream_status(exc: BaseException) -> int | None:
+ """Return a status eligible for provider-opening backoff."""
+ status = retryable_transient_status(exc)
+ return status if status is not None and _is_retryable_status(status) else None
+
+
+def retryable_upstream_transport_error(exc: BaseException) -> bool:
+ """Return whether a pre-response transport failure can be retried."""
+ if isinstance(exc, ExecutionFailure):
+ return exc.retryable and retryable_transient_status(exc) is None
+ if isinstance(exc, openai.AuthenticationError | openai.BadRequestError):
+ return False
+ return isinstance(
+ exc,
+ (
+ TimeoutError,
+ httpx.TimeoutException,
+ httpx.ConnectError,
+ httpx.ReadError,
+ httpx.WriteError,
+ httpx.RemoteProtocolError,
+ httpx.NetworkError,
+ openai.APITimeoutError,
+ openai.APIConnectionError,
+ ),
+ )
+
+
+def provider_error_message(
+ exc: BaseException,
+ *,
+ read_timeout_s: float | None = None,
+) -> str:
+ """Map raw provider exception types to stable customer-facing wording."""
+ if isinstance(exc, ExecutionFailure):
+ return exc.message
+ if isinstance(exc, httpx.ReadTimeout):
+ if read_timeout_s is not None:
+ return f"Provider request timed out after {read_timeout_s:g}s."
+ return "Provider request timed out."
+ if isinstance(exc, httpx.ConnectTimeout | httpx.ConnectError):
+ return "Could not connect to provider."
+ if isinstance(exc, httpx.RemoteProtocolError):
+ return "Provider connection was interrupted before a response was received."
+ if isinstance(exc, TimeoutError):
+ if read_timeout_s is not None:
+ return f"Provider request timed out after {read_timeout_s:g}s."
+ return "Request timed out."
+ if isinstance(exc, openai.RateLimitError):
+ return _RATE_LIMIT_MESSAGE
+ if isinstance(exc, openai.AuthenticationError):
+ return _AUTHENTICATION_MESSAGE
+ if isinstance(exc, openai.BadRequestError):
+ return _INVALID_REQUEST_MESSAGE
+ return safe_exception_message(exc)
+
+
+def _classify_provider_failure(
+ exc: Exception,
+ *,
+ read_timeout_s: float | None,
+ mark_rate_limited: MarkRateLimited,
+) -> ExecutionFailure:
+ if isinstance(exc, ExecutionFailure):
+ if exc.kind == FailureKind.RATE_LIMIT:
+ mark_rate_limited(60)
+ return exc
+
+ if isinstance(exc, openai.AuthenticationError):
+ return _failure(FailureKind.AUTHENTICATION, 401, _AUTHENTICATION_MESSAGE, False)
+ if isinstance(exc, openai.RateLimitError):
+ mark_rate_limited(60)
+ return _failure(FailureKind.RATE_LIMIT, 429, _RATE_LIMIT_MESSAGE, True)
+ if isinstance(exc, openai.BadRequestError):
+ return _failure(
+ FailureKind.INVALID_REQUEST, 400, _INVALID_REQUEST_MESSAGE, False
+ )
+ if isinstance(exc, openai.APITimeoutError):
+ return _failure(FailureKind.TIMEOUT, 500, _stable_upstream(500), True)
+ if isinstance(exc, openai.APIConnectionError):
+ return _failure(FailureKind.UNAVAILABLE, 500, _stable_upstream(500), True)
+ if isinstance(exc, openai.InternalServerError):
+ status = retryable_transient_status(exc) or getattr(exc, "status_code", None)
+ if is_transient_overload_error(exc):
+ return _failure(FailureKind.OVERLOADED, 529, _OVERLOADED_MESSAGE, True)
+ if isinstance(status, int) and 500 <= status <= 599:
+ return _failure(
+ FailureKind.UPSTREAM,
+ status,
+ _stable_upstream(status),
+ True,
+ )
+ return _failure(FailureKind.UPSTREAM, 500, _stable_upstream(500), True)
+ if isinstance(exc, openai.APIError):
+ status = retryable_transient_status(exc)
+ if status == 429:
+ mark_rate_limited(60)
+ return _failure(FailureKind.RATE_LIMIT, 429, _RATE_LIMIT_MESSAGE, True)
+ if is_transient_overload_error(exc):
+ return _failure(FailureKind.OVERLOADED, 529, _OVERLOADED_MESSAGE, True)
+ effective_status = status or getattr(exc, "status_code", None)
+ if not isinstance(effective_status, int):
+ effective_status = 500
+ return _failure(
+ FailureKind.UPSTREAM,
+ effective_status,
+ _stable_upstream(effective_status),
+ is_retryable_provider_error(exc),
+ )
+
+ if isinstance(exc, httpx.HTTPStatusError):
+ status = exc.response.status_code
+ if status in (401, 403):
+ return _failure(
+ FailureKind.AUTHENTICATION, 401, _AUTHENTICATION_MESSAGE, False
+ )
+ if status == 429:
+ mark_rate_limited(60)
+ return _failure(FailureKind.RATE_LIMIT, 429, _RATE_LIMIT_MESSAGE, True)
+ if status == 400:
+ return _failure(
+ FailureKind.INVALID_REQUEST, 400, _INVALID_REQUEST_MESSAGE, False
+ )
+ if status in (502, 503, 504):
+ return _failure(FailureKind.OVERLOADED, 529, _OVERLOADED_MESSAGE, True)
+ return _failure(
+ FailureKind.UPSTREAM,
+ status,
+ _stable_upstream(status),
+ _is_retryable_status(status),
+ )
+
+ kind = FailureKind.UPSTREAM
+ if isinstance(exc, TimeoutError | httpx.TimeoutException):
+ kind = FailureKind.TIMEOUT
+ elif isinstance(exc, httpx.ConnectError | httpx.NetworkError):
+ kind = FailureKind.UNAVAILABLE
+ return _failure(
+ kind,
+ 502,
+ provider_error_message(exc, read_timeout_s=read_timeout_s),
+ is_retryable_provider_error(exc),
+ )
+
+
+def _failure(
+ kind: FailureKind,
+ status_code: int,
+ message: str,
+ retryable: bool,
+) -> ExecutionFailure:
+ return ExecutionFailure(
+ kind=kind,
+ status_code=status_code,
+ message=message,
+ retryable=retryable,
+ )
+
+
+def _stable_upstream(status_code: int) -> str:
+ if status_code in (502, 503, 504):
+ return "Provider is temporarily unavailable. Please retry."
+ return "Provider API request failed."
+
+
+def _status_from_exception(exc: BaseException) -> int | None:
+ status = getattr(exc, "status_code", None)
+ return status if isinstance(status, int) else None
+
+
+def _status_from_body(body: Any) -> int | None:
+ for item in _body_candidates(body):
+ if not isinstance(item, Mapping):
+ continue
+ for key in ("status", "status_code", "code"):
+ status = _coerce_status(item.get(key))
+ if status is not None:
+ return status
+ type_status = _status_from_type_fields(item)
+ if type_status is not None:
+ return type_status
+ return None
+
+
+def _body_candidates(body: Any) -> tuple[Any, ...]:
+ if isinstance(body, str):
+ try:
+ return _body_candidates(json.loads(body))
+ except ValueError:
+ return (body,)
+ if isinstance(body, bytes):
+ return _body_candidates(body.decode("utf-8", errors="replace"))
+ if isinstance(body, Mapping):
+ nested = body.get("error")
+ return (body, nested) if isinstance(nested, Mapping) else (body,)
+ return (body,)
+
+
+def _coerce_status(value: Any) -> int | None:
+ if isinstance(value, int):
+ return value
+ if isinstance(value, str) and value.isdigit():
+ return int(value)
+ return None
+
+
+def _status_from_type_fields(item: Mapping[str, Any]) -> int | None:
+ values = [
+ value.lower()
+ for key in ("type", "code")
+ if isinstance((value := item.get(key)), str)
+ ]
+ text = " ".join(values)
+ if _has_marker(text, _RATE_LIMIT_MARKERS):
+ return 429
+ if _has_marker(text, _OVERLOAD_MARKERS):
+ return 503
+ if _has_marker(text, _INTERNAL_ERROR_MARKERS):
+ return 500
+ return None
+
+
+def _body_to_text(body: Any) -> str:
+ if isinstance(body, bytes):
+ return body.decode("utf-8", errors="replace")
+ if isinstance(body, str):
+ return body
+ try:
+ return json.dumps(body, ensure_ascii=False, separators=(",", ":"))
+ except TypeError:
+ return str(body)
+
+
+def _has_marker(text: str, markers: frozenset[str]) -> bool:
+ return any(marker in text for marker in markers)
+
+
+def _is_retryable_status(status: int | None) -> bool:
+ return isinstance(status, int) and (status == 429 or 500 <= status <= 599)
diff --git a/src/free_claude_code/providers/github_models/client.py b/src/free_claude_code/providers/github_models/client.py
index d0cf4252..d3ae9496 100644
--- a/src/free_claude_code/providers/github_models/client.py
+++ b/src/free_claude_code/providers/github_models/client.py
@@ -9,8 +9,10 @@ from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.defaults import GITHUB_MODELS_DEFAULT_BASE
-from free_claude_code.providers.exceptions import ModelListResponseError
-from free_claude_code.providers.model_listing import model_infos_from_ids
+from free_claude_code.providers.model_listing import (
+ ModelListResponseError,
+ model_infos_from_ids,
+)
from free_claude_code.providers.rate_limit import ProviderRateLimiter
from free_claude_code.providers.transports.http import maybe_await_aclose
from free_claude_code.providers.transports.openai_chat import (
diff --git a/src/free_claude_code/providers/huggingface/client.py b/src/free_claude_code/providers/huggingface/client.py
index 2e2b7800..1957f2e8 100644
--- a/src/free_claude_code/providers/huggingface/client.py
+++ b/src/free_claude_code/providers/huggingface/client.py
@@ -2,12 +2,12 @@
from copy import deepcopy
+from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.core.anthropic import ReasoningReplayMode, build_base_request_body
from free_claude_code.core.anthropic.conversion import OpenAIConversionError
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.defaults import HUGGINGFACE_DEFAULT_BASE
-from free_claude_code.providers.exceptions import InvalidRequestError
from free_claude_code.providers.rate_limit import ProviderRateLimiter
from free_claude_code.providers.transports.openai_chat import OpenAIChatTransport
diff --git a/src/free_claude_code/providers/lmstudio/client.py b/src/free_claude_code/providers/lmstudio/client.py
index 071b9a11..15e905b9 100644
--- a/src/free_claude_code/providers/lmstudio/client.py
+++ b/src/free_claude_code/providers/lmstudio/client.py
@@ -16,6 +16,7 @@ import time
import httpx
from loguru import logger
+from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.core.anthropic import (
ReasoningReplayMode,
build_base_request_body,
@@ -25,7 +26,6 @@ from free_claude_code.core.anthropic.conversion import OpenAIConversionError
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.defaults import LMSTUDIO_DEFAULT_BASE
-from free_claude_code.providers.exceptions import InvalidRequestError
from free_claude_code.providers.rate_limit import ProviderRateLimiter
from free_claude_code.providers.transports.openai_chat import OpenAIChatTransport
diff --git a/src/free_claude_code/providers/model_listing.py b/src/free_claude_code/providers/model_listing.py
index e47cabd0..d1cafef3 100644
--- a/src/free_claude_code/providers/model_listing.py
+++ b/src/free_claude_code/providers/model_listing.py
@@ -6,7 +6,14 @@ from typing import Any
from free_claude_code.application.model_metadata import (
ProviderModelInfo as _ProviderModelInfo,
)
-from free_claude_code.providers.exceptions import ModelListResponseError
+
+
+class ModelListResponseError(ValueError):
+ """A provider model-list response cannot be parsed safely."""
+
+ def __init__(self, message: str) -> None:
+ super().__init__(message)
+ self.message = message
def model_infos_from_ids(
diff --git a/src/free_claude_code/providers/rate_limit.py b/src/free_claude_code/providers/rate_limit.py
index 51e0e553..4e90a71a 100644
--- a/src/free_claude_code/providers/rate_limit.py
+++ b/src/free_claude_code/providers/rate_limit.py
@@ -7,13 +7,14 @@ from collections.abc import AsyncIterator, Callable
from contextlib import asynccontextmanager
from typing import Any, TypeVar
-import httpx
-import openai
from loguru import logger
-from free_claude_code.core.anthropic.streaming import retryable_transient_status
from free_claude_code.core.rate_limit import StrictSlidingWindowLimiter
from free_claude_code.core.trace import trace_event
+from free_claude_code.providers.failure_policy import (
+ retryable_upstream_status,
+ retryable_upstream_transport_error,
+)
T = TypeVar("T")
@@ -21,43 +22,6 @@ UPSTREAM_TRANSIENT_TOTAL_ATTEMPTS = 5
DEFAULT_UPSTREAM_MAX_RETRIES = UPSTREAM_TRANSIENT_TOTAL_ATTEMPTS - 1
-def _upstream_http_retryable(code: int) -> bool:
- """True for rate limit / upstream server failures that should backoff-retry."""
- return code == 429 or 500 <= code <= 599
-
-
-def retryable_upstream_status(exc: BaseException) -> int | None:
- """Return HTTP-like status codes that qualify for reactive backoff retries.
-
- ``429`` plus any upstream ``5xx`` use the same exponential backoff and scoped
- limiter blocking semantics as today's rate-limit path.
- """
- status = retryable_transient_status(exc)
- if status is not None and _upstream_http_retryable(status):
- return status
- return None
-
-
-def retryable_upstream_transport_error(exc: BaseException) -> bool:
- """Return whether a pre-response transport failure can be retried."""
- if isinstance(exc, openai.AuthenticationError | openai.BadRequestError):
- return False
- return isinstance(
- exc,
- (
- TimeoutError,
- httpx.TimeoutException,
- httpx.ConnectError,
- httpx.ReadError,
- httpx.WriteError,
- httpx.RemoteProtocolError,
- httpx.NetworkError,
- openai.APITimeoutError,
- openai.APIConnectionError,
- ),
- )
-
-
class ProviderRateLimiter:
"""
Rate limiter owned by one provider instance.
diff --git a/src/free_claude_code/providers/runtime/config.py b/src/free_claude_code/providers/runtime/config.py
index 8db5e41a..7e14ecf5 100644
--- a/src/free_claude_code/providers/runtime/config.py
+++ b/src/free_claude_code/providers/runtime/config.py
@@ -1,9 +1,9 @@
"""Provider configuration construction from neutral catalog metadata."""
+from free_claude_code.application.errors import ApplicationUnavailableError
from free_claude_code.config.provider_catalog import ProviderDescriptor
from free_claude_code.config.settings import Settings
from free_claude_code.providers.base import ProviderConfig
-from free_claude_code.providers.exceptions import AuthenticationError
def string_setting(settings: Settings, attr_name: str | None, default: str = "") -> str:
@@ -34,7 +34,7 @@ def require_provider_credential(
message = f"{descriptor.credential_env} is not set. Add it to your .env file."
if descriptor.credential_url:
message = f"{message} Get a key at {descriptor.credential_url}"
- raise AuthenticationError(message)
+ raise ApplicationUnavailableError(message)
def build_provider_config(
diff --git a/src/free_claude_code/providers/runtime/factory.py b/src/free_claude_code/providers/runtime/factory.py
index 50f82912..d6396051 100644
--- a/src/free_claude_code/providers/runtime/factory.py
+++ b/src/free_claude_code/providers/runtime/factory.py
@@ -2,13 +2,13 @@
from collections.abc import Callable
+from free_claude_code.application.errors import UnknownProviderError
from free_claude_code.config.provider_catalog import (
PROVIDER_CATALOG,
SUPPORTED_PROVIDER_IDS,
)
from free_claude_code.config.settings import Settings
from free_claude_code.providers.base import BaseProvider, ProviderConfig
-from free_claude_code.providers.exceptions import UnknownProviderTypeError
from free_claude_code.providers.rate_limit import ProviderRateLimiter
from .config import build_provider_config
@@ -312,7 +312,7 @@ def create_provider(provider_id: str, settings: Settings) -> BaseProvider:
descriptor = PROVIDER_CATALOG.get(provider_id)
if descriptor is None:
supported = "', '".join(PROVIDER_CATALOG)
- raise UnknownProviderTypeError(
+ raise UnknownProviderError(
f"Unknown provider_type: '{provider_id}'. Supported: '{supported}'"
)
diff --git a/src/free_claude_code/providers/runtime/validation.py b/src/free_claude_code/providers/runtime/validation.py
index 980a82b1..1da0082b 100644
--- a/src/free_claude_code/providers/runtime/validation.py
+++ b/src/free_claude_code/providers/runtime/validation.py
@@ -7,19 +7,16 @@ from collections.abc import Callable
import httpx
from loguru import logger
+from free_claude_code.application.errors import ApplicationUnavailableError
from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.model_refs import (
ConfiguredChatModelRef,
configured_chat_model_refs,
)
from free_claude_code.config.settings import Settings
+from free_claude_code.core.failures import ExecutionFailure
from free_claude_code.providers.base import BaseProvider
-from free_claude_code.providers.exceptions import (
- AuthenticationError,
- ModelListResponseError,
- ProviderError,
- ServiceUnavailableError,
-)
+from free_claude_code.providers.model_listing import ModelListResponseError
from .model_cache import ProviderModelCache
@@ -32,9 +29,9 @@ def provider_query_failure_reason(exc: BaseException, settings: Settings) -> str
return f"malformed model-list response: {exc.message}"
if isinstance(exc, httpx.HTTPStatusError):
return f"query failure: HTTP {exc.response.status_code}"
- if isinstance(exc, AuthenticationError):
+ if isinstance(exc, ApplicationUnavailableError):
return f"query failure: {exc.message}"
- if isinstance(exc, ProviderError) and settings.log_api_error_tracebacks:
+ if isinstance(exc, ExecutionFailure) and settings.log_api_error_tracebacks:
return f"query failure: {exc.message}"
return f"query failure: {type(exc).__name__}"
@@ -96,7 +93,7 @@ class ConfiguredModelValidator:
message = "Configured model validation failed:\n" + "\n".join(
f"- {failure}" for failure in failures
)
- raise ServiceUnavailableError(message)
+ raise ApplicationUnavailableError(message)
logger.info(
"Configured provider models validated: models={} providers={}",
diff --git a/src/free_claude_code/providers/stream_recovery.py b/src/free_claude_code/providers/stream_recovery.py
new file mode 100644
index 00000000..4ea18167
--- /dev/null
+++ b/src/free_claude_code/providers/stream_recovery.py
@@ -0,0 +1,222 @@
+"""Provider-owned stream holdback and recovery decisions."""
+
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import StrEnum
+
+import httpx
+import openai
+
+from free_claude_code.core.failures import ExecutionFailure
+from free_claude_code.core.trace import trace_event
+
+from .failure_policy import retryable_transient_status
+
+EARLY_TRANSPARENT_TOTAL_ATTEMPTS = 5
+EARLY_TRANSPARENT_MAX_RETRIES = EARLY_TRANSPARENT_TOTAL_ATTEMPTS - 1
+MIDSTREAM_RECOVERY_ATTEMPTS = 5
+EARLY_HOLDBACK_SECONDS = 0.75
+RECOVERY_BUFFER_MAX_BYTES = 65_536
+
+
+class TruncatedProviderStreamError(RuntimeError):
+ """An upstream stream ended without its required terminal marker."""
+
+
+class RecoveryFailureAction(StrEnum):
+ """How one provider stream should respond to an upstream failure."""
+
+ EARLY_RETRY = "early_retry"
+ MIDSTREAM_RECOVERY = "midstream_recovery"
+ FINAL_ERROR = "final_error"
+
+
+@dataclass(frozen=True, slots=True)
+class RecoveryDecision:
+ """Failure decision for one provider stream attempt."""
+
+ action: RecoveryFailureAction
+ retryable: bool
+ committed: bool
+ has_buffered: bool
+ early_retry_attempt: int | None = None
+ midstream_recovery_attempt: int | None = None
+
+
+class RecoveryHoldbackBuffer:
+ """Briefly retain SSE so early cutoffs can be retried invisibly."""
+
+ def __init__(
+ self,
+ *,
+ holdback_seconds: float = EARLY_HOLDBACK_SECONDS,
+ max_bytes: int = RECOVERY_BUFFER_MAX_BYTES,
+ now: Callable[[], float] | None = None,
+ ) -> None:
+ self._holdback_seconds = holdback_seconds
+ self._max_bytes = max_bytes
+ self._now = now or time.monotonic
+ self._events: list[str] = []
+ self._bytes = 0
+ self._started_at: float | None = None
+ self.committed = False
+
+ def push(self, event: str) -> list[str]:
+ if self.committed:
+ return [event]
+ if self._started_at is None:
+ self._started_at = self._now()
+ self._events.append(event)
+ self._bytes += len(event.encode("utf-8", errors="replace"))
+ if (
+ self._bytes >= self._max_bytes
+ or self._now() - self._started_at >= self._holdback_seconds
+ ):
+ return self.flush()
+ return []
+
+ def flush(self) -> list[str]:
+ if self.committed:
+ return []
+ self.committed = True
+ events = self._events
+ self._events = []
+ self._bytes = 0
+ self._started_at = None
+ return events
+
+ def discard(self) -> None:
+ self._events = []
+ self._bytes = 0
+ self._started_at = None
+
+ @property
+ def has_buffered(self) -> bool:
+ return bool(self._events)
+
+
+class RecoveryController:
+ """Own holdback and retry counters for one provider stream lifecycle."""
+
+ def __init__(self, *, provider_name: str, request_id: str | None) -> None:
+ self._provider_name = provider_name
+ self._request_id = request_id
+ self._holdback = RecoveryHoldbackBuffer()
+ self._early_retry_count = 0
+ self._midstream_recovery_count = 0
+
+ @property
+ def committed(self) -> bool:
+ return self._holdback.committed
+
+ @property
+ def has_buffered(self) -> bool:
+ return self._holdback.has_buffered
+
+ @property
+ def early_retries(self) -> int:
+ return self._early_retry_count
+
+ @property
+ def midstream_recoveries(self) -> int:
+ return self._midstream_recovery_count
+
+ def push(self, event: str) -> list[str]:
+ return self._holdback.push(event)
+
+ def flush(self) -> list[str]:
+ return self._holdback.flush()
+
+ def discard(self) -> None:
+ self._holdback.discard()
+
+ def flush_uncommitted(self, decision: RecoveryDecision) -> list[str]:
+ if not decision.committed and decision.has_buffered:
+ return self.flush()
+ return []
+
+ def advance_failure(
+ self,
+ error: BaseException,
+ *,
+ stream_opened: bool,
+ generated_output: bool,
+ complete_tool_salvageable: bool,
+ ) -> RecoveryDecision:
+ retryable = is_retryable_stream_error(error)
+ committed = self._holdback.committed
+ has_buffered = self._holdback.has_buffered
+
+ if (
+ retryable
+ and stream_opened
+ and not committed
+ and not complete_tool_salvageable
+ and self._early_retry_count < EARLY_TRANSPARENT_MAX_RETRIES
+ ):
+ self._early_retry_count += 1
+ self._holdback.discard()
+ self._holdback = RecoveryHoldbackBuffer()
+ trace_event(
+ stage="provider",
+ event="provider.recovery.early_retry",
+ source="provider",
+ provider=self._provider_name,
+ request_id=self._request_id,
+ retry_attempt=self._early_retry_count,
+ retryable=True,
+ )
+ return RecoveryDecision(
+ action=RecoveryFailureAction.EARLY_RETRY,
+ retryable=True,
+ committed=False,
+ has_buffered=has_buffered,
+ early_retry_attempt=self._early_retry_count,
+ )
+
+ if (
+ retryable
+ and generated_output
+ and self._midstream_recovery_count < MIDSTREAM_RECOVERY_ATTEMPTS
+ ):
+ self._midstream_recovery_count += 1
+ return RecoveryDecision(
+ action=RecoveryFailureAction.MIDSTREAM_RECOVERY,
+ retryable=True,
+ committed=committed,
+ has_buffered=has_buffered,
+ midstream_recovery_attempt=self._midstream_recovery_count,
+ )
+
+ return RecoveryDecision(
+ action=RecoveryFailureAction.FINAL_ERROR,
+ retryable=retryable,
+ committed=committed,
+ has_buffered=has_buffered,
+ )
+
+
+def is_retryable_stream_error(exc: BaseException) -> bool:
+ """Return whether one stream failure qualifies for retry or recovery."""
+ if isinstance(exc, TruncatedProviderStreamError):
+ return True
+ if isinstance(exc, ExecutionFailure):
+ return exc.retryable
+ if isinstance(exc, openai.AuthenticationError | openai.BadRequestError):
+ return False
+ if retryable_transient_status(exc) is not None:
+ return True
+ return isinstance(
+ exc,
+ (
+ TimeoutError,
+ httpx.ReadTimeout,
+ httpx.ReadError,
+ httpx.RemoteProtocolError,
+ httpx.ConnectError,
+ httpx.NetworkError,
+ openai.APITimeoutError,
+ openai.APIConnectionError,
+ ),
+ )
diff --git a/src/free_claude_code/providers/transports/anthropic_messages/http.py b/src/free_claude_code/providers/transports/anthropic_messages/http.py
index 99c9fdee..4df2ac0e 100644
--- a/src/free_claude_code/providers/transports/anthropic_messages/http.py
+++ b/src/free_claude_code/providers/transports/anthropic_messages/http.py
@@ -5,12 +5,13 @@ from typing import Any
import httpx
from loguru import logger
-from free_claude_code.config.constants import (
- NATIVE_MESSAGES_ERROR_BODY_LOG_CAP_BYTES,
- PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES,
+from free_claude_code.config.constants import NATIVE_MESSAGES_ERROR_BODY_LOG_CAP_BYTES
+from free_claude_code.core.diagnostics import (
+ ERROR_DETAIL_DISPLAY_CAP_BYTES,
+ attach_upstream_error_body,
+ redact_sensitive_error_text,
)
-from free_claude_code.providers.error_mapping import attach_provider_error_body
-from free_claude_code.providers.exceptions import ModelListResponseError
+from free_claude_code.providers.model_listing import ModelListResponseError
def model_list_json(response: httpx.Response, *, provider_name: str) -> Any:
@@ -62,14 +63,16 @@ async def raise_for_status_with_body(
response.raise_for_status()
except httpx.HTTPStatusError as error:
preview, truncated = await read_error_body_preview(
- response, PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES
+ response, ERROR_DETAIL_DISPLAY_CAP_BYTES
)
- attach_provider_error_body(error, preview, truncated=truncated)
+ attach_upstream_error_body(error, preview, truncated=truncated)
if log_api_error_tracebacks:
log_preview = preview[:NATIVE_MESSAGES_ERROR_BODY_LOG_CAP_BYTES]
log_truncated = truncated or len(preview) > len(log_preview)
if log_preview:
- text = log_preview.decode("utf-8", errors="replace")
+ text = redact_sensitive_error_text(
+ log_preview.decode("utf-8", errors="replace")
+ )
logger.error(
"{}_ERROR:{} HTTP {} body_preview_bytes={} truncated={}: {}",
provider_name,
diff --git a/src/free_claude_code/providers/transports/anthropic_messages/recovery.py b/src/free_claude_code/providers/transports/anthropic_messages/recovery.py
index 112a99ab..d27be5b7 100644
--- a/src/free_claude_code/providers/transports/anthropic_messages/recovery.py
+++ b/src/free_claude_code/providers/transports/anthropic_messages/recovery.py
@@ -8,18 +8,20 @@ import httpx
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
from free_claude_code.core.anthropic.streaming import (
- MIDSTREAM_RECOVERY_ATTEMPTS,
AnthropicStreamLedger,
- TruncatedProviderStreamError,
accept_tool_json_repair,
continuation_suffix,
- is_retryable_stream_error,
make_text_recovery_body,
make_tool_repair_body,
parse_complete_tool_input,
tool_schemas_by_name,
)
from free_claude_code.core.trace import trace_event
+from free_claude_code.providers.stream_recovery import (
+ MIDSTREAM_RECOVERY_ATTEMPTS,
+ TruncatedProviderStreamError,
+ is_retryable_stream_error,
+)
from free_claude_code.providers.transports.http import maybe_await_aclose
IterStreamChunks = Callable[..., AsyncIterator[str]]
@@ -43,6 +45,7 @@ class AnthropicMessagesRecovery:
*,
req_tag: str,
thinking_enabled: bool,
+ request_id: str | None = None,
) -> tuple[str, str]:
"""Collect text/thinking from an internal native recovery request."""
last_error: Exception | None = None
@@ -50,7 +53,10 @@ class AnthropicMessagesRecovery:
response: httpx.Response | None = None
try:
response = await self._transport._rate_limiter.execute_with_retry(
- self._transport._validated_stream_send, body, req_tag=req_tag
+ self._transport._validated_stream_send,
+ body,
+ req_tag=req_tag,
+ request_id=request_id,
)
state = self._transport._new_stream_state()
chunks = [
@@ -149,6 +155,7 @@ class AnthropicMessagesRecovery:
recovery_body,
req_tag=req_tag,
thinking_enabled=thinking_enabled,
+ request_id=request_id,
)
repair = accept_tool_json_repair(
block.content,
@@ -197,6 +204,7 @@ class AnthropicMessagesRecovery:
recovery_body,
req_tag=req_tag,
thinking_enabled=thinking_enabled,
+ request_id=request_id,
)
text_suffix = continuation_suffix(partial_text, text)
thinking_suffix = continuation_suffix(partial_thinking, thinking)
diff --git a/src/free_claude_code/providers/transports/anthropic_messages/request_policy.py b/src/free_claude_code/providers/transports/anthropic_messages/request_policy.py
index ad92beab..1b3369a0 100644
--- a/src/free_claude_code/providers/transports/anthropic_messages/request_policy.py
+++ b/src/free_claude_code/providers/transports/anthropic_messages/request_policy.py
@@ -6,12 +6,12 @@ from typing import Any, Literal
from loguru import logger
+from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.anthropic.native_messages_request import (
build_base_native_anthropic_request_body,
)
-from free_claude_code.providers.exceptions import InvalidRequestError
NativeExtraBodyPolicy = Literal["drop", "reject"]
NativeMessagesPostprocessor = Callable[[dict[str, Any], MessagesRequest, bool], None]
diff --git a/src/free_claude_code/providers/transports/anthropic_messages/stream.py b/src/free_claude_code/providers/transports/anthropic_messages/stream.py
index 041cb207..23b943e4 100644
--- a/src/free_claude_code/providers/transports/anthropic_messages/stream.py
+++ b/src/free_claude_code/providers/transports/anthropic_messages/stream.py
@@ -1,25 +1,29 @@
"""Native Anthropic Messages upstream adapter."""
+import sys
from collections.abc import AsyncIterator
from typing import Any
import httpx
+from free_claude_code.core.anthropic import execution_failure_from_anthropic_error
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
from free_claude_code.core.anthropic.streaming import (
AnthropicStreamLedger,
- RecoveryController,
- RecoveryFailureAction,
- TruncatedProviderStreamError,
tool_schemas_by_name,
)
from free_claude_code.core.trace import (
provider_native_messages_body_snapshot,
trace_event,
)
-from free_claude_code.providers.error_mapping import map_stream_start_error
-from free_claude_code.providers.transports.http import maybe_await_aclose
+from free_claude_code.providers.failure_policy import classify_provider_failure
+from free_claude_code.providers.stream_recovery import (
+ RecoveryController,
+ RecoveryFailureAction,
+ TruncatedProviderStreamError,
+)
+from free_claude_code.providers.transports.http import close_provider_stream
from .recovery import AnthropicMessagesRecovery
@@ -98,6 +102,7 @@ class AnthropicMessagesStreamAdapter:
self._transport._validated_stream_send,
body,
req_tag=req_tag,
+ request_id=self._request_id,
)
stream_opened = True
chunk_count = 0
@@ -111,6 +116,10 @@ class AnthropicMessagesStreamAdapter:
chunk_count += 1
chunk_bytes += len(chunk.encode("utf-8", errors="replace"))
for parsed in parse_sse_text(chunk):
+ if parsed.event == "error":
+ raise execution_failure_from_anthropic_error(
+ parsed.data
+ )
emitted = ledger.ingest_native_event(parsed)
if emitted is None:
continue
@@ -168,7 +177,12 @@ class AnthropicMessagesStreamAdapter:
)
if decision.action == RecoveryFailureAction.EARLY_RETRY:
if response is not None and not response.is_closed:
- await maybe_await_aclose(response)
+ await close_provider_stream(
+ response,
+ active_error=error,
+ provider_name=tag,
+ request_id=self._request_id,
+ )
response = None
state = self._transport._new_stream_state()
ledger = self._new_ledger()
@@ -208,19 +222,14 @@ class AnthropicMessagesStreamAdapter:
self._transport._log_stream_transport_error(
tag, req_tag, error, request_id=self._request_id
)
- mapped_error, error_message = self._transport._map_error_details(
- error, self._request_id
- )
- mapped_error_type = getattr(mapped_error, "error_type", None)
- terminal_error_type = (
- mapped_error_type
- if isinstance(mapped_error_type, str) and mapped_error_type
- else "api_error"
+ failure = classify_provider_failure(
+ error,
+ provider_name=tag,
+ read_timeout_s=self._transport._config.http_read_timeout,
+ request_id=self._request_id,
+ mark_rate_limited=self._transport._rate_limiter.set_blocked,
)
- if response is not None and not response.is_closed:
- await maybe_await_aclose(response)
-
error_trace: dict[str, Any] = {
"stage": "provider",
"event": "provider.response.error",
@@ -228,40 +237,34 @@ class AnthropicMessagesStreamAdapter:
"provider": tag,
"request_id": self._request_id,
"exc_type": type(error).__name__,
- "mapped_error_type": type(mapped_error).__name__,
+ "failure_kind": failure.kind.value,
+ "status_code": failure.status_code,
+ "provider_retryable": failure.retryable,
"mid_stream": sent_any_event or decision.committed,
}
if self._transport._config.log_api_error_tracebacks:
- error_trace["error_message"] = error_message
+ error_trace["error_message"] = failure.message
trace_event(**error_trace)
if decision.committed:
- for event in ledger.terminal_error_tail(
- error_message,
- error_type=terminal_error_type,
- ):
+ for event in ledger.close_unclosed_blocks():
yield event
elif decision.has_buffered and complete_tool_salvageable:
for event in recovery.flush():
sent_any_event = True
yield event
- for event in ledger.terminal_error_tail(
- error_message,
- error_type=terminal_error_type,
- ):
+ for event in ledger.close_unclosed_blocks():
yield event
else:
recovery.discard()
- raise map_stream_start_error(
- error,
- provider_name=tag,
- read_timeout_s=self._transport._config.http_read_timeout,
- request_id=self._request_id,
- rate_limiter=self._transport._rate_limiter,
- ) from error
- return
+ raise failure from error
finally:
if response is not None and not response.is_closed:
- await maybe_await_aclose(response)
+ await close_provider_stream(
+ response,
+ active_error=sys.exception(),
+ provider_name=tag,
+ request_id=self._request_id,
+ )
async def iter_stream_chunks(
self,
diff --git a/src/free_claude_code/providers/transports/anthropic_messages/transport.py b/src/free_claude_code/providers/transports/anthropic_messages/transport.py
index ec923dbc..09c699ee 100644
--- a/src/free_claude_code/providers/transports/anthropic_messages/transport.py
+++ b/src/free_claude_code/providers/transports/anthropic_messages/transport.py
@@ -1,5 +1,6 @@
"""Shared transport for providers with native Anthropic Messages endpoints."""
+import sys
from collections.abc import AsyncIterator
from typing import Any, Literal
@@ -12,17 +13,15 @@ from free_claude_code.core.anthropic.native_sse_block_policy import (
transform_native_sse_block_event,
)
from free_claude_code.providers.base import BaseProvider, ProviderConfig
-from free_claude_code.providers.error_mapping import (
- extract_provider_error_detail,
- map_error,
- user_visible_message_for_mapped_provider_error,
-)
from free_claude_code.providers.model_listing import (
extract_openai_model_ids,
model_infos_from_ids,
)
from free_claude_code.providers.rate_limit import ProviderRateLimiter
-from free_claude_code.providers.transports.http import maybe_await_aclose
+from free_claude_code.providers.transports.http import (
+ close_provider_stream,
+ maybe_await_aclose,
+)
from .http import model_list_json, raise_for_status_with_body
from .request_policy import (
@@ -181,24 +180,12 @@ class AnthropicMessagesTransport(BaseProvider):
)
return event
- def _map_error_details(
- self, error: Exception, request_id: str | None
- ) -> tuple[Exception, str]:
- """Map an exception into a user-facing provider error message."""
- mapped_error = map_error(error, rate_limiter=self._rate_limiter)
- return (
- mapped_error,
- user_visible_message_for_mapped_provider_error(
- mapped_error,
- provider_name=self._provider_name,
- read_timeout_s=self._config.http_read_timeout,
- detail=extract_provider_error_detail(error),
- request_id=request_id,
- ),
- )
-
async def _validated_stream_send(
- self, body: dict, *, req_tag: str
+ self,
+ body: dict,
+ *,
+ req_tag: str,
+ request_id: str | None = None,
) -> httpx.Response:
"""Send request and raise mapped HTTP errors before yielding body chunks."""
send_response = await self._send_stream_request(body)
@@ -207,7 +194,12 @@ class AnthropicMessagesTransport(BaseProvider):
await self._raise_for_status(send_response, req_tag=req_tag)
finally:
if not send_response.is_closed:
- await maybe_await_aclose(send_response)
+ await close_provider_stream(
+ send_response,
+ active_error=sys.exception(),
+ provider_name=self._provider_name,
+ request_id=request_id,
+ )
return send_response
async def stream_response(
diff --git a/src/free_claude_code/providers/transports/http.py b/src/free_claude_code/providers/transports/http.py
index ef785252..a489cd03 100644
--- a/src/free_claude_code/providers/transports/http.py
+++ b/src/free_claude_code/providers/transports/http.py
@@ -3,6 +3,10 @@
import inspect
from typing import Any
+from loguru import logger
+
+from free_claude_code.core.trace import trace_event
+
async def maybe_await_aclose(response: Any) -> None:
"""Call ``aclose`` on httpx-like responses; ignore sync test doubles."""
@@ -12,3 +16,36 @@ async def maybe_await_aclose(response: Any) -> None:
result = close()
if inspect.isawaitable(result):
await result
+
+
+async def close_provider_stream(
+ stream: Any,
+ *,
+ active_error: BaseException | None,
+ provider_name: str,
+ request_id: str | None,
+) -> None:
+ """Close one stream without letting cleanup change its established outcome."""
+ try:
+ await maybe_await_aclose(stream)
+ except Exception as close_error:
+ active_error_type = (
+ type(active_error).__name__ if active_error is not None else None
+ )
+ trace_event(
+ stage="provider",
+ event="provider.stream.close_failed",
+ source="provider",
+ provider=provider_name,
+ request_id=request_id,
+ close_exc_type=type(close_error).__name__,
+ preserved_exc_type=active_error_type,
+ )
+ logger.warning(
+ "{}_STREAM_CLOSE_FAILED request_id={} close_exc_type={} "
+ "preserved_exc_type={}",
+ provider_name,
+ request_id,
+ type(close_error).__name__,
+ active_error_type,
+ )
diff --git a/src/free_claude_code/providers/transports/openai_chat/recovery.py b/src/free_claude_code/providers/transports/openai_chat/recovery.py
index e38b9fb5..6c79261d 100644
--- a/src/free_claude_code/providers/transports/openai_chat/recovery.py
+++ b/src/free_claude_code/providers/transports/openai_chat/recovery.py
@@ -5,18 +5,20 @@ from typing import Any
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.anthropic.streaming import (
- MIDSTREAM_RECOVERY_ATTEMPTS,
AnthropicStreamLedger,
- TruncatedProviderStreamError,
accept_tool_json_repair,
continuation_suffix,
- is_retryable_stream_error,
make_text_recovery_body,
make_tool_repair_body,
parse_complete_tool_input,
tool_schemas_by_name,
)
from free_claude_code.core.trace import trace_event
+from free_claude_code.providers.stream_recovery import (
+ MIDSTREAM_RECOVERY_ATTEMPTS,
+ TruncatedProviderStreamError,
+ is_retryable_stream_error,
+)
from free_claude_code.providers.transports.http import maybe_await_aclose
from .tool_calls import all_emitted_tools_complete, started_tool_states
diff --git a/src/free_claude_code/providers/transports/openai_chat/request_policy.py b/src/free_claude_code/providers/transports/openai_chat/request_policy.py
index b70b4c88..f46e29a7 100644
--- a/src/free_claude_code/providers/transports/openai_chat/request_policy.py
+++ b/src/free_claude_code/providers/transports/openai_chat/request_policy.py
@@ -7,10 +7,10 @@ from typing import Any, Literal
from loguru import logger
+from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.core.anthropic import ReasoningReplayMode, build_base_request_body
from free_claude_code.core.anthropic.conversion import OpenAIConversionError
from free_claude_code.core.anthropic.models import MessagesRequest
-from free_claude_code.providers.exceptions import InvalidRequestError
MaxTokensField = Literal["max_tokens", "max_completion_tokens"]
OpenAIChatPostprocessor = Callable[[dict[str, Any], MessagesRequest, bool], None]
diff --git a/src/free_claude_code/providers/transports/openai_chat/stream.py b/src/free_claude_code/providers/transports/openai_chat/stream.py
index 3037e17f..16f8aaea 100644
--- a/src/free_claude_code/providers/transports/openai_chat/stream.py
+++ b/src/free_claude_code/providers/transports/openai_chat/stream.py
@@ -1,6 +1,7 @@
"""OpenAI-chat upstream adapter."""
import asyncio
+import sys
import uuid
from collections.abc import AsyncIterator, Iterator
from typing import Any
@@ -15,14 +16,16 @@ from free_claude_code.core.anthropic import (
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.anthropic.streaming import (
AnthropicStreamLedger,
+ map_stop_reason,
+)
+from free_claude_code.core.trace import provider_chat_body_snapshot, trace_event
+from free_claude_code.providers.failure_policy import classify_provider_failure
+from free_claude_code.providers.stream_recovery import (
RecoveryController,
RecoveryFailureAction,
TruncatedProviderStreamError,
- map_stop_reason,
)
-from free_claude_code.core.trace import provider_chat_body_snapshot, trace_event
-from free_claude_code.providers.error_mapping import map_stream_start_error
-from free_claude_code.providers.transports.http import maybe_await_aclose
+from free_claude_code.providers.transports.http import close_provider_stream
from .recovery import OpenAIChatRecovery
from .tool_calls import (
@@ -272,14 +275,12 @@ class OpenAIChatStreamAdapter:
self._transport._log_stream_transport_error(
tag, req_tag, error, request_id=self._request_id
)
- mapped_error, error_message = self._transport._map_error_details(
- error, self._request_id
- )
- mapped_error_type = getattr(mapped_error, "error_type", None)
- terminal_error_type = (
- mapped_error_type
- if isinstance(mapped_error_type, str) and mapped_error_type
- else "api_error"
+ failure = classify_provider_failure(
+ error,
+ provider_name=tag,
+ read_timeout_s=self._transport._config.http_read_timeout,
+ request_id=self._request_id,
+ mark_rate_limited=self._transport._rate_limiter.set_blocked,
)
error_trace: dict[str, Any] = {
"stage": "provider",
@@ -288,10 +289,12 @@ class OpenAIChatStreamAdapter:
"provider": tag,
"request_id": self._request_id,
"exc_type": type(error).__name__,
- "mapped_error_type": type(mapped_error).__name__,
+ "failure_kind": failure.kind.value,
+ "status_code": failure.status_code,
+ "provider_retryable": failure.retryable,
}
if self._transport._config.log_api_error_tracebacks:
- error_trace["error_message"] = error_message
+ error_trace["error_message"] = failure.message
trace_event(**error_trace)
if (
not decision.committed
@@ -302,22 +305,18 @@ class OpenAIChatStreamAdapter:
yield event
elif not decision.committed:
recovery.discard()
- raise map_stream_start_error(
- error,
- provider_name=tag,
- read_timeout_s=self._transport._config.http_read_timeout,
- request_id=self._request_id,
- rate_limiter=self._transport._rate_limiter,
- ) from error
- for event in ledger.terminal_error_tail(
- error_message,
- error_type=terminal_error_type,
- ):
+ raise failure from error
+ for event in ledger.close_unclosed_blocks():
yield event
- return
+ raise failure from error
finally:
if stream is not None:
- await maybe_await_aclose(stream)
+ await close_provider_stream(
+ stream,
+ active_error=sys.exception(),
+ provider_name=tag,
+ request_id=self._request_id,
+ )
remaining = think_parser.flush()
if remaining:
diff --git a/src/free_claude_code/providers/transports/openai_chat/transport.py b/src/free_claude_code/providers/transports/openai_chat/transport.py
index 646b94fc..5d480c04 100644
--- a/src/free_claude_code/providers/transports/openai_chat/transport.py
+++ b/src/free_claude_code/providers/transports/openai_chat/transport.py
@@ -11,11 +11,6 @@ from openai import AsyncOpenAI
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.anthropic.streaming import AnthropicStreamLedger
from free_claude_code.providers.base import BaseProvider, ProviderConfig
-from free_claude_code.providers.error_mapping import (
- extract_provider_error_detail,
- map_error,
- user_visible_message_for_mapped_provider_error,
-)
from free_claude_code.providers.model_listing import extract_openai_model_ids
from free_claude_code.providers.rate_limit import ProviderRateLimiter
@@ -198,21 +193,6 @@ class OpenAIChatTransport(BaseProvider):
)
return clamped
- def _map_error_details(
- self, error: Exception, request_id: str | None
- ) -> tuple[Exception, str]:
- mapped_error = map_error(error, rate_limiter=self._rate_limiter)
- return (
- mapped_error,
- user_visible_message_for_mapped_provider_error(
- mapped_error,
- provider_name=self._provider_name,
- read_timeout_s=self._config.http_read_timeout,
- detail=extract_provider_error_detail(error),
- request_id=request_id,
- ),
- )
-
async def stream_response(
self,
request: MessagesRequest,
diff --git a/src/free_claude_code/runtime/application.py b/src/free_claude_code/runtime/application.py
index 5c108249..5bece33b 100644
--- a/src/free_claude_code/runtime/application.py
+++ b/src/free_claude_code/runtime/application.py
@@ -13,6 +13,7 @@ from loguru import logger
import free_claude_code.cli.managed as cli_managed
import free_claude_code.messaging.session as messaging_session
import free_claude_code.messaging.workflow as messaging_workflow_module
+from free_claude_code.application.errors import ApplicationUnavailableError
from free_claude_code.application.ports import StopResult
from free_claude_code.config.admin.persistence import (
PreparedAdminUpdate,
@@ -36,7 +37,6 @@ from free_claude_code.messaging.platforms.ports import (
MessagingRuntime,
)
from free_claude_code.messaging.voice import Transcriber
-from free_claude_code.providers.exceptions import ServiceUnavailableError
from .provider_manager import ProviderRuntimeManager
@@ -90,7 +90,7 @@ def warn_if_process_auth_token(settings: Settings) -> None:
def startup_failure_message(settings: Settings, exc: Exception) -> str:
"""Return the existing concise ASGI startup failure message."""
- if isinstance(exc, ServiceUnavailableError):
+ if isinstance(exc, ApplicationUnavailableError):
return exc.message.strip() or "Server startup failed."
if settings.log_api_error_tracebacks:
return f"{type(exc).__name__}: {exc}"
@@ -289,7 +289,7 @@ class ApplicationRuntime:
async def _validate_configured_models_best_effort(self) -> None:
try:
await self.provider_manager.validate_configured_models()
- except ServiceUnavailableError as exc:
+ except ApplicationUnavailableError as exc:
logger.warning(
"Configured provider model validation failed during startup; "
"server will continue and requests will fail at provider resolution "
diff --git a/src/free_claude_code/runtime/provider_manager.py b/src/free_claude_code/runtime/provider_manager.py
index 49000dca..b9390aba 100644
--- a/src/free_claude_code/runtime/provider_manager.py
+++ b/src/free_claude_code/runtime/provider_manager.py
@@ -6,11 +6,11 @@ from dataclasses import dataclass, field
from loguru import logger
+from free_claude_code.application.errors import ApplicationUnavailableError
from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.settings import Settings
from free_claude_code.core.trace import trace_event
from free_claude_code.providers.base import BaseProvider
-from free_claude_code.providers.exceptions import ServiceUnavailableError
from free_claude_code.providers.runtime import ProviderRuntime
from free_claude_code.providers.runtime.discovery import ProviderModelDiscovery
from free_claude_code.providers.runtime.model_cache import ProviderModelCache
@@ -106,7 +106,7 @@ class ProviderRuntimeManager:
async def acquire(self) -> ProviderGenerationLease:
if self._closing or self._closed:
- raise ServiceUnavailableError("Provider runtime is shutting down.")
+ raise ApplicationUnavailableError("Provider runtime is shutting down.")
generation = self._current
generation.active_leases += 1
generation.drained.clear()
@@ -160,7 +160,7 @@ class ProviderRuntimeManager:
"""Run an explicit full refresh without racing replacement."""
async with self._replace_lock:
if self._closing or self._closed:
- raise ServiceUnavailableError("Provider runtime is shutting down.")
+ raise ApplicationUnavailableError("Provider runtime is shutting down.")
await self._cancel_refresh()
await self._refresh_generation(self._current, only_missing=False)
@@ -174,7 +174,7 @@ class ProviderRuntimeManager:
"""Prepare, commit, and atomically publish one replacement generation."""
async with self._replace_lock:
if self._closing or self._closed:
- raise ServiceUnavailableError("Provider runtime is shutting down.")
+ raise ApplicationUnavailableError("Provider runtime is shutting down.")
await self._cancel_refresh()
await self._retry_unpublished_cleanup()
candidate_id = self._next_generation_id
diff --git a/tests/api/test_api.py b/tests/api/test_api.py
index 42bc6079..482f0db3 100644
--- a/tests/api/test_api.py
+++ b/tests/api/test_api.py
@@ -3,14 +3,7 @@ from unittest.mock import MagicMock, patch
import pytest
from fastapi.testclient import TestClient
-from free_claude_code.providers.exceptions import (
- APIError,
- AuthenticationError,
- InvalidRequestError,
- OverloadedError,
- ProviderError,
- RateLimitError,
-)
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.providers.nvidia_nim import NvidiaNimProvider
from tests.api.support import create_test_app
@@ -33,7 +26,12 @@ async def _mock_stream_response(*args, **kwargs):
async def _mock_pre_start_rate_limit(*args, **kwargs):
"""Provider stream that fails before any downstream-visible SSE chunk."""
_stream_response_calls.append((args, kwargs))
- raise RateLimitError("upstream is busy")
+ raise ExecutionFailure(
+ kind=FailureKind.RATE_LIMIT,
+ status_code=429,
+ message="upstream is busy",
+ retryable=True,
+ )
yield "unreachable"
@@ -170,7 +168,7 @@ def test_create_message_pre_start_provider_error_returns_terminal_json(
}
with (
- patch("free_claude_code.api.handlers.messages.trace_event") as trace,
+ patch("free_claude_code.api.response_streams.trace_event") as trace,
patch("free_claude_code.application.execution.trace_event") as execution_trace,
):
response = client.post("/v1/messages", json=payload)
@@ -200,6 +198,9 @@ def test_create_message_pre_start_provider_error_returns_terminal_json(
"status_code": 429,
"error_type": "rate_limit_error",
"client_should_retry": False,
+ "exc_type": "ExecutionFailure",
+ "failure_kind": "rate_limit",
+ "provider_retryable": True,
}
mock_provider.stream_response = _mock_stream_response
@@ -245,23 +246,46 @@ def test_model_mapping(client: TestClient):
@pytest.mark.parametrize(
- ("provider_error", "expected_status", "expected_type"),
+ ("failure", "expected_type"),
[
- (AuthenticationError("Invalid Key"), 401, "authentication_error"),
(
- InvalidRequestError("Invalid request api_key=SECRET useful detail"),
- 400,
+ ExecutionFailure(
+ FailureKind.AUTHENTICATION, 401, "Invalid Key", retryable=False
+ ),
+ "authentication_error",
+ ),
+ (
+ ExecutionFailure(
+ FailureKind.INVALID_REQUEST,
+ 400,
+ "Invalid request api_key=SECRET useful detail",
+ retryable=False,
+ ),
"invalid_request_error",
),
- (RateLimitError("Too Many Requests"), 429, "rate_limit_error"),
- (OverloadedError("Server Overloaded"), 529, "overloaded_error"),
- (APIError("Upstream failed", status_code=503), 503, "api_error"),
+ (
+ ExecutionFailure(
+ FailureKind.RATE_LIMIT, 429, "Too Many Requests", retryable=True
+ ),
+ "rate_limit_error",
+ ),
+ (
+ ExecutionFailure(
+ FailureKind.OVERLOADED, 529, "Server Overloaded", retryable=True
+ ),
+ "overloaded_error",
+ ),
+ (
+ ExecutionFailure(
+ FailureKind.UPSTREAM, 503, "Upstream failed", retryable=True
+ ),
+ "api_error",
+ ),
],
)
def test_provider_execution_errors_preserve_status_and_type(
client: TestClient,
- provider_error: ProviderError,
- expected_status: int,
+ failure: ExecutionFailure,
expected_type: str,
):
base_payload = {
@@ -272,12 +296,12 @@ def test_provider_execution_errors_preserve_status_and_type(
}
def _raise_provider_error(*args, **kwargs):
- raise provider_error
+ raise failure
try:
mock_provider.stream_response = _raise_provider_error
response = client.post("/v1/messages", json=base_payload)
- error = _terminal_json_error(response, status_code=expected_status)
+ error = _terminal_json_error(response, status_code=failure.status_code)
assert error["type"] == expected_type
assert "SECRET" not in error["message"]
if expected_type == "invalid_request_error":
diff --git a/tests/api/test_api_handlers.py b/tests/api/test_api_handlers.py
index a40e072a..4b636bce 100644
--- a/tests/api/test_api_handlers.py
+++ b/tests/api/test_api_handlers.py
@@ -11,6 +11,7 @@ from free_claude_code.api.handlers import (
ResponsesHandler,
TokenCountHandler,
)
+from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.config.settings import Settings
from free_claude_code.core.anthropic.models import (
Message,
@@ -18,8 +19,8 @@ from free_claude_code.core.anthropic.models import (
TokenCountRequest,
)
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.providers.exceptions import InvalidRequestError, RateLimitError
_CLASSIFIER_SYSTEM = (
"You are a security monitor. Respond with <block>yes</block> or <block>no</block>."
@@ -336,7 +337,12 @@ async def test_messages_handler_stream_false_provider_exception_keeps_status() -
"thinking_enabled": thinking_enabled,
}
)
- raise RateLimitError("upstream is busy")
+ raise ExecutionFailure(
+ kind=FailureKind.RATE_LIMIT,
+ status_code=429,
+ message="upstream is busy",
+ retryable=True,
+ )
yield "unreachable"
provider = FailingProvider()
diff --git a/tests/api/test_app_lifespan_and_errors.py b/tests/api/test_app_lifespan_and_errors.py
index e81b25e2..6a2e6daf 100644
--- a/tests/api/test_app_lifespan_and_errors.py
+++ b/tests/api/test_app_lifespan_and_errors.py
@@ -7,12 +7,12 @@ import pytest
from fastapi import FastAPI
from fastapi.testclient import TestClient
+from free_claude_code.application.errors import (
+ ApplicationUnavailableError,
+ InvalidRequestError,
+)
from free_claude_code.config.settings import Settings
from free_claude_code.messaging.transcription import TranscriptionService
-from free_claude_code.providers.exceptions import (
- AuthenticationError,
- ServiceUnavailableError,
-)
from free_claude_code.providers.nvidia_nim.client import NvidiaNimProvider
from free_claude_code.providers.nvidia_nim.voice import NvidiaNimTranscriber
from free_claude_code.runtime.application import (
@@ -94,40 +94,40 @@ async def test_runtime_startup_logs_admin_url_without_printed_server_banner():
)
-def test_create_app_provider_error_handler_returns_anthropic_format():
+def test_create_app_application_error_handler_returns_anthropic_format():
app = create_test_app(_settings(log_api_error_tracebacks=False))
- @app.get("/raise_provider")
- async def _raise_provider():
- raise AuthenticationError("bad key")
+ @app.get("/raise_application")
+ async def _raise_application():
+ raise InvalidRequestError("bad request")
- response = TestClient(app).get("/raise_provider")
+ response = TestClient(app).get("/raise_application")
- assert response.status_code == 401
+ assert response.status_code == 400
body = response.json()
assert body["type"] == "error"
- assert body["error"]["type"] == "authentication_error"
+ assert body["error"]["type"] == "invalid_request_error"
assert body["request_id"] == response.headers["request-id"]
assert "x-should-retry" not in response.headers
-def test_provider_error_default_log_excludes_provider_message():
+def test_application_error_handler_does_not_log_error_message():
app = create_test_app(_settings(log_api_error_tracebacks=False))
secret = "provider-upstream-secret-detail"
- @app.get("/raise_provider_secret")
- async def _raise_provider_secret():
- raise AuthenticationError(secret)
+ @app.get("/raise_application_secret")
+ async def _raise_application_secret():
+ raise InvalidRequestError(secret)
with patch("free_claude_code.api.app.logger.error") as log_error:
- response = TestClient(app).get("/raise_provider_secret")
+ response = TestClient(app).get("/raise_application_secret")
- assert response.status_code == 401
+ assert response.status_code == 400
blob = " ".join(
str(value) for call in log_error.call_args_list for value in call.args
)
assert secret not in blob
- assert "authentication_error" in blob
+ log_error.assert_not_called()
def test_create_app_general_exception_handler_returns_correlated_500():
@@ -170,7 +170,7 @@ async def test_model_validation_failure_does_not_block_runtime_startup():
settings = _settings(messaging_platform="none")
manager = ProviderRuntimeManager(settings)
runtime = ApplicationRuntime(manager, transcriber=None)
- validation = AsyncMock(side_effect=ServiceUnavailableError("bad model"))
+ validation = AsyncMock(side_effect=ApplicationUnavailableError("bad model"))
with (
patch.object(manager, "validate_configured_models", new=validation),
@@ -201,7 +201,7 @@ def test_startup_failure_message_preserves_existing_concise_contract():
assert (
startup_failure_message(
quiet,
- ServiceUnavailableError("configured model is unavailable"),
+ ApplicationUnavailableError("configured model is unavailable"),
)
== "configured model is unavailable"
)
diff --git a/tests/api/test_dependencies.py b/tests/api/test_dependencies.py
index 546a70cb..d77830f6 100644
--- a/tests/api/test_dependencies.py
+++ b/tests/api/test_dependencies.py
@@ -10,9 +10,9 @@ from free_claude_code.api.dependencies import (
resolve_provider,
)
from free_claude_code.api.ports import ApiServices
+from free_claude_code.application.errors import ApplicationUnavailableError
from free_claude_code.application.ports import RequestRuntimeLease
from free_claude_code.config.settings import Settings
-from free_claude_code.providers.exceptions import AuthenticationError
from tests.api.support import create_test_app
@@ -84,19 +84,19 @@ def test_resolve_provider_skips_initialization_log_for_cached_provider() -> None
log_info.assert_not_called()
-def test_resolve_provider_missing_key_raises_503() -> None:
+def test_resolve_provider_missing_key_preserves_readiness_error() -> None:
lease = _lease(
- error=AuthenticationError(
+ error=ApplicationUnavailableError(
"OPENROUTER_API_KEY is required. Get one at https://openrouter.ai"
)
)
- with pytest.raises(HTTPException) as exc_info:
+ with pytest.raises(ApplicationUnavailableError) as exc_info:
resolve_provider("open_router", lease=lease)
assert exc_info.value.status_code == 503
- assert "OPENROUTER_API_KEY" in exc_info.value.detail
- assert "openrouter.ai" in exc_info.value.detail
+ assert "OPENROUTER_API_KEY" in exc_info.value.message
+ assert "openrouter.ai" in exc_info.value.message
def test_resolve_provider_unrelated_error_is_not_reclassified() -> None:
diff --git a/tests/api/test_execution_failure_contract.py b/tests/api/test_execution_failure_contract.py
new file mode 100644
index 00000000..b2e86e51
--- /dev/null
+++ b/tests/api/test_execution_failure_contract.py
@@ -0,0 +1,421 @@
+"""Public commit-boundary behavior for canonical execution failures."""
+
+from collections.abc import AsyncIterator
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+import pytest
+from fastapi.testclient import TestClient
+
+from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
+from free_claude_code.core.anthropic.streaming import format_sse_event
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
+from tests.api.support import create_test_app
+
+_PARTIAL_CONTENT = "PARTIAL_ASSISTANT_CONTENT"
+
+
+class CanonicalFailureProvider:
+ """Provider double that raises one request-correlated canonical failure."""
+
+ def __init__(
+ self,
+ chunks: list[str],
+ *,
+ kind: FailureKind,
+ status_code: int,
+ message: str,
+ retryable: bool,
+ grouped: bool = False,
+ ) -> None:
+ self._chunks = chunks
+ self._kind = kind
+ self._status_code = status_code
+ self._message = message
+ self._retryable = retryable
+ self._grouped = grouped
+ self.preflight_stream = MagicMock()
+ self.stream_kwargs: list[dict[str, Any]] = []
+
+ async def stream_response(
+ self,
+ _request: object,
+ **kwargs: Any,
+ ) -> AsyncIterator[str]:
+ self.stream_kwargs.append(kwargs)
+ for chunk in self._chunks:
+ yield chunk
+ request_id = kwargs["request_id"]
+ failure = ExecutionFailure(
+ kind=self._kind,
+ status_code=self._status_code,
+ message=f"{self._message}\n\nRequest ID: {request_id}",
+ retryable=self._retryable,
+ )
+ if self._grouped:
+ raise ExceptionGroup(
+ "provider stream and cleanup failed",
+ [
+ RuntimeError("cleanup failed"),
+ ExceptionGroup("provider request failed", [failure]),
+ ],
+ )
+ raise failure
+
+
+def _messages_payload(*, stream: bool) -> dict[str, object]:
+ return {
+ "model": "nvidia_nim/test-model",
+ "messages": [{"role": "user", "content": "Hello"}],
+ "max_tokens": 32,
+ "stream": stream,
+ }
+
+
+def _responses_payload() -> dict[str, object]:
+ return {
+ "model": "nvidia_nim/test-model",
+ "input": "Hello",
+ "max_output_tokens": 32,
+ }
+
+
+def _partial_anthropic_stream(*, close_block: bool) -> list[str]:
+ chunks = [
+ format_sse_event("message_start", {"type": "message_start", "message": {}}),
+ format_sse_event(
+ "content_block_start",
+ {
+ "type": "content_block_start",
+ "index": 0,
+ "content_block": {"type": "text", "text": ""},
+ },
+ ),
+ format_sse_event(
+ "content_block_delta",
+ {
+ "type": "content_block_delta",
+ "index": 0,
+ "delta": {"type": "text_delta", "text": _PARTIAL_CONTENT},
+ },
+ ),
+ ]
+ if close_block:
+ chunks.append(
+ format_sse_event(
+ "content_block_stop",
+ {"type": "content_block_stop", "index": 0},
+ )
+ )
+ return chunks
+
+
+def _client_for(provider: CanonicalFailureProvider):
+ app = create_test_app()
+ return (
+ patch("free_claude_code.api.routes.resolve_provider", return_value=provider),
+ TestClient(app),
+ )
+
+
+def _terminal_trace(trace_mock: MagicMock) -> dict[str, Any]:
+ return dict(
+ next(
+ call.kwargs
+ for call in trace_mock.call_args_list
+ if call.kwargs.get("event")
+ == "free_claude_code.api.response.terminal_execution_error"
+ )
+ )
+
+
+def _grouped_rate_limit_provider(chunks: list[str]) -> CanonicalFailureProvider:
+ return CanonicalFailureProvider(
+ chunks,
+ kind=FailureKind.RATE_LIMIT,
+ status_code=429,
+ message="upstream is busy",
+ retryable=True,
+ grouped=True,
+ )
+
+
+ ("path", "payload", "expected_type"),
+ [
+ ("/v1/messages", _messages_payload(stream=True), "rate_limit_error"),
+ ("/v1/responses", _responses_payload(), "rate_limit_error"),
+ ],
+)
+def test_grouped_pre_start_execution_failure_keeps_canonical_wire_error(
+ path: str,
+ payload: dict[str, object],
+ expected_type: str,
+) -> None:
+ provider = _grouped_rate_limit_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 == 429
+ assert response.headers["x-should-retry"] == "false"
+ error = response.json()["error"]
+ assert error["type"] == expected_type
+ assert error["message"] == f"upstream is busy\n\nRequest ID: {request_id}"
+ trace = _terminal_trace(trace_mock)
+ assert trace["status_code"] == 429
+ assert trace["error_type"] == "rate_limit_error"
+ assert trace["exc_type"] == "ExecutionFailure"
+ assert trace["failure_kind"] == "rate_limit"
+
+
[email protected]("path", ["/v1/messages", "/v1/responses"])
+def test_grouped_post_start_execution_failure_keeps_canonical_terminal_event(
+ path: str,
+) -> None:
+ provider = _grouped_rate_limit_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)
+ if path == "/v1/messages":
+ assert events[-1].event == "error"
+ error = events[-1].data["error"]
+ else:
+ assert events[-1].event == "response.failed"
+ error = events[-1].data["response"]["error"]
+ assert response.status_code == 200
+ assert error["type"] == "rate_limit_error"
+ assert error["message"] == f"upstream is busy\n\nRequest ID: {request_id}"
+ assert _terminal_trace(trace_mock)["failure_kind"] == "rate_limit"
+
+
+def test_grouped_stream_false_execution_failure_discards_partial_content() -> None:
+ provider = _grouped_rate_limit_provider(
+ _partial_anthropic_stream(close_block=False)
+ )
+ 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("/v1/messages", json=_messages_payload(stream=False))
+
+ request_id = response.headers["request-id"]
+ assert response.status_code == 429
+ assert response.headers["x-should-retry"] == "false"
+ assert response.json()["error"] == {
+ "type": "rate_limit_error",
+ "message": f"upstream is busy\n\nRequest ID: {request_id}",
+ }
+ assert _PARTIAL_CONTENT not in response.text
+ trace = _terminal_trace(trace_mock)
+ assert trace["status_code"] == 429
+ assert trace["error_type"] == "rate_limit_error"
+ assert trace["exc_type"] == "ExecutionFailure"
+ assert trace["failure_kind"] == "rate_limit"
+
+
+def test_messages_pre_start_execution_failure_is_correlated_terminal_json() -> None:
+ provider = CanonicalFailureProvider(
+ [],
+ kind=FailureKind.RATE_LIMIT,
+ status_code=429,
+ message="upstream is busy",
+ retryable=True,
+ )
+ resolver_patch, client = _client_for(provider)
+
+ with resolver_patch, client:
+ response = client.post("/v1/messages", json=_messages_payload(stream=True))
+
+ request_id = response.headers["request-id"]
+ assert response.status_code == 429
+ assert response.headers["content-type"].startswith("application/json")
+ assert response.headers["x-should-retry"] == "false"
+ assert "x-request-id" not in response.headers
+ assert response.json() == {
+ "type": "error",
+ "error": {
+ "type": "rate_limit_error",
+ "message": f"upstream is busy\n\nRequest ID: {request_id}",
+ },
+ "request_id": request_id,
+ }
+ assert provider.stream_kwargs[0]["request_id"] == request_id
+
+
+def test_responses_pre_start_execution_failure_is_correlated_terminal_json() -> None:
+ provider = CanonicalFailureProvider(
+ [],
+ kind=FailureKind.OVERLOADED,
+ status_code=529,
+ message="provider overloaded",
+ retryable=True,
+ )
+ resolver_patch, client = _client_for(provider)
+
+ with resolver_patch, client:
+ response = client.post("/v1/responses", json=_responses_payload())
+
+ request_id = response.headers["request-id"]
+ assert response.status_code == 529
+ assert response.headers["content-type"].startswith("application/json")
+ assert response.headers["x-should-retry"] == "false"
+ assert response.headers["x-request-id"] == request_id
+ assert response.json() == {
+ "error": {
+ "message": f"provider overloaded\n\nRequest ID: {request_id}",
+ "type": "overloaded_error",
+ "param": None,
+ "code": None,
+ }
+ }
+ assert provider.stream_kwargs[0]["request_id"] == request_id
+
+
+def test_messages_post_start_execution_failure_follows_closed_block() -> None:
+ provider = CanonicalFailureProvider(
+ _partial_anthropic_stream(close_block=True),
+ kind=FailureKind.OVERLOADED,
+ status_code=529,
+ message="provider overloaded",
+ retryable=True,
+ )
+ 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("/v1/messages", json=_messages_payload(stream=True))
+
+ 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
+ assert [event.event for event in events] == [
+ "message_start",
+ "content_block_start",
+ "content_block_delta",
+ "content_block_stop",
+ "error",
+ ]
+ assert events[-1].data["error"] == {
+ "type": "overloaded_error",
+ "message": f"provider overloaded\n\nRequest ID: {request_id}",
+ }
+ assert "message_stop" not in response.text
+ assert _terminal_trace(trace_mock) == {
+ "stage": "egress",
+ "event": "free_claude_code.api.response.terminal_execution_error",
+ "source": "api",
+ "wire_api": "messages",
+ "request_id": request_id,
+ "status_code": 529,
+ "error_type": "overloaded_error",
+ "client_should_retry": False,
+ "exc_type": "ExecutionFailure",
+ "failure_kind": "overloaded",
+ "provider_retryable": True,
+ }
+
+
+def test_responses_post_start_execution_failure_retains_id_after_block_close() -> None:
+ provider = CanonicalFailureProvider(
+ _partial_anthropic_stream(close_block=True),
+ kind=FailureKind.RATE_LIMIT,
+ status_code=429,
+ message="upstream is busy",
+ retryable=True,
+ )
+ 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("/v1/responses", json=_responses_payload())
+
+ request_id = response.headers["request-id"]
+ events = parse_sse_text(response.text)
+ event_names = [event.event for event in events]
+ created = events[0].data["response"]
+ failed = events[-1].data["response"]
+ assert response.status_code == 200
+ assert response.headers["x-request-id"] == request_id
+ assert "x-should-retry" not in response.headers
+ assert event_names[0] == "response.created"
+ assert "response.output_item.done" in event_names
+ assert event_names.index("response.output_item.done") < event_names.index(
+ "response.failed"
+ )
+ assert event_names[-1] == "response.failed"
+ assert failed["id"] == created["id"]
+ assert failed["status"] == "failed"
+ assert failed["error"] == {
+ "message": f"upstream is busy\n\nRequest ID: {request_id}",
+ "type": "rate_limit_error",
+ "param": None,
+ "code": None,
+ }
+ assert _terminal_trace(trace_mock) == {
+ "stage": "egress",
+ "event": "free_claude_code.api.response.terminal_execution_error",
+ "source": "api",
+ "wire_api": "responses",
+ "request_id": request_id,
+ "status_code": 429,
+ "error_type": "rate_limit_error",
+ "client_should_retry": False,
+ "exc_type": "ExecutionFailure",
+ "failure_kind": "rate_limit",
+ "provider_retryable": True,
+ }
+
+
+def test_messages_stream_false_discards_partial_content_on_execution_failure() -> None:
+ provider = CanonicalFailureProvider(
+ _partial_anthropic_stream(close_block=False),
+ kind=FailureKind.RATE_LIMIT,
+ status_code=429,
+ message="upstream is busy",
+ retryable=True,
+ )
+ 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 == 429
+ assert response.headers["content-type"].startswith("application/json")
+ assert response.headers["x-should-retry"] == "false"
+ assert response.json()["request_id"] == request_id
+ assert response.json()["error"] == {
+ "type": "rate_limit_error",
+ "message": f"upstream is busy\n\nRequest ID: {request_id}",
+ }
+ assert _PARTIAL_CONTENT not in response.text
diff --git a/tests/api/test_openai_responses.py b/tests/api/test_openai_responses.py
index 94e93663..7dd7a20e 100644
--- a/tests/api/test_openai_responses.py
+++ b/tests/api/test_openai_responses.py
@@ -4,9 +4,10 @@ from unittest.mock import MagicMock, patch
import pytest
from fastapi.testclient import TestClient
+from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
from free_claude_code.core.anthropic.streaming import format_sse_event
-from free_claude_code.providers.exceptions import InvalidRequestError, RateLimitError
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
from tests.api.support import create_test_app
@@ -31,7 +32,12 @@ class PreStartFailingProvider(FakeProvider):
async def stream_response(self, request_data, **_kwargs):
self.requests.append(request_data)
self.stream_kwargs.append(_kwargs)
- raise RateLimitError("upstream is busy")
+ raise ExecutionFailure(
+ kind=FailureKind.RATE_LIMIT,
+ status_code=429,
+ message="upstream is busy",
+ retryable=True,
+ )
yield "unreachable"
@@ -147,7 +153,7 @@ def test_create_response_pre_start_provider_error_returns_openai_error() -> None
app = create_test_app()
with (
patch("free_claude_code.api.routes.resolve_provider", return_value=provider),
- patch("free_claude_code.api.handlers.responses.trace_event") as trace,
+ patch("free_claude_code.api.response_streams.trace_event") as trace,
TestClient(app) as client,
):
response = client.post(
@@ -177,6 +183,8 @@ def test_create_response_pre_start_provider_error_returns_openai_error() -> None
assert terminal_trace["status_code"] == 429
assert terminal_trace["error_type"] == "rate_limit_error"
assert terminal_trace["client_should_retry"] is False
+ assert terminal_trace["failure_kind"] == "rate_limit"
+ assert terminal_trace["provider_retryable"] is True
def test_create_response_post_start_failure_preserves_response_id() -> None:
diff --git a/tests/api/test_ordinary_error_phases.py b/tests/api/test_ordinary_error_phases.py
new file mode 100644
index 00000000..71d435ec
--- /dev/null
+++ b/tests/api/test_ordinary_error_phases.py
@@ -0,0 +1,255 @@
+"""Ordinary ingress, routing, readiness, and preflight error contracts."""
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import httpx
+import pytest
+from fastapi.testclient import TestClient
+
+from free_claude_code.application.errors import (
+ ApplicationError,
+ ApplicationUnavailableError,
+ InvalidRequestError,
+ UnknownProviderError,
+)
+from free_claude_code.config.settings import Settings
+from tests.api.support import create_test_app
+
+_PRODUCT_REQUESTS = (
+ (
+ "messages",
+ "/v1/messages",
+ {
+ "model": "open_router/test-model",
+ "messages": [{"role": "user", "content": "hello"}],
+ "stream": True,
+ },
+ ),
+ (
+ "responses",
+ "/v1/responses",
+ {
+ "model": "open_router/test-model",
+ "input": "hello",
+ },
+ ),
+)
+
+
+def _settings(**updates: object) -> Settings:
+ return Settings().model_copy(
+ update={
+ "anthropic_auth_token": "",
+ "log_api_error_tracebacks": False,
+ **updates,
+ }
+ )
+
+
+def _assert_ordinary_protocol_error(
+ response: httpx.Response,
+ *,
+ wire_api: str,
+ status_code: int,
+ error_type: str,
+ message: str,
+) -> None:
+ assert response.status_code == status_code
+ assert response.headers["content-type"].startswith("application/json")
+ assert "x-should-retry" not in response.headers
+
+ request_id = response.headers["request-id"]
+ assert request_id.startswith("req_")
+ if wire_api == "responses":
+ assert response.headers["x-request-id"] == request_id
+ assert response.json() == {
+ "error": {
+ "message": message,
+ "type": error_type,
+ "param": None,
+ "code": None,
+ }
+ }
+ return
+
+ assert "x-request-id" not in response.headers
+ assert response.json() == {
+ "type": "error",
+ "error": {"type": error_type, "message": message},
+ "request_id": request_id,
+ }
+
+
+ "error_type",
+ [InvalidRequestError, UnknownProviderError, ApplicationUnavailableError],
+)
+def test_application_errors_share_one_protocol_neutral_base(
+ error_type: type[ApplicationError],
+) -> None:
+ assert isinstance(error_type("failure"), ApplicationError)
+
+
+ ("wire_api", "path", "payload"),
+ _PRODUCT_REQUESTS,
+ ids=("messages", "responses"),
+)
+def test_missing_provider_credential_is_protocol_specific_503_without_terminal_header(
+ wire_api: str,
+ path: str,
+ payload: dict[str, object],
+) -> None:
+ message = (
+ "OPENROUTER_API_KEY is not set. Add it to your .env file. "
+ "Get a key at https://openrouter.ai/keys"
+ )
+ app = create_test_app(
+ _settings(
+ model="open_router/test-model",
+ open_router_api_key="",
+ )
+ )
+
+ with TestClient(app) as client:
+ response = client.post(path, json=payload)
+
+ _assert_ordinary_protocol_error(
+ response,
+ wire_api=wire_api,
+ status_code=503,
+ error_type="api_error",
+ message=message,
+ )
+
+
+ ("wire_api", "path", "payload"),
+ _PRODUCT_REQUESTS,
+ ids=("messages", "responses"),
+)
+def test_runtime_acquisition_failure_is_protocol_specific_503_without_terminal_header(
+ wire_api: str,
+ path: str,
+ payload: dict[str, object],
+) -> None:
+ message = "Provider runtime is shutting down."
+ app = create_test_app(_settings())
+ acquire = AsyncMock(side_effect=ApplicationUnavailableError(message))
+
+ with (
+ patch.object(app.state.services.requests, "acquire", new=acquire),
+ TestClient(app) as client,
+ ):
+ response = client.post(path, json=payload)
+
+ acquire.assert_awaited_once()
+ _assert_ordinary_protocol_error(
+ response,
+ wire_api=wire_api,
+ status_code=503,
+ error_type="api_error",
+ message=message,
+ )
+
+
+ ("wire_api", "path", "payload"),
+ _PRODUCT_REQUESTS,
+ ids=("messages", "responses"),
+)
+def test_unknown_provider_is_protocol_specific_400_without_terminal_header(
+ wire_api: str,
+ path: str,
+ payload: dict[str, object],
+) -> None:
+ message = "Unknown provider_type: 'unknown'."
+ app = create_test_app(_settings())
+
+ with (
+ patch(
+ "free_claude_code.api.routes.resolve_provider",
+ side_effect=UnknownProviderError(message),
+ ),
+ TestClient(app) as client,
+ ):
+ response = client.post(path, json=payload)
+
+ _assert_ordinary_protocol_error(
+ response,
+ wire_api=wire_api,
+ status_code=400,
+ error_type="invalid_request_error",
+ message=message,
+ )
+
+
+ ("wire_api", "path", "payload"),
+ _PRODUCT_REQUESTS,
+ ids=("messages", "responses"),
+)
+def test_preflight_rejection_is_protocol_specific_400_without_terminal_header(
+ wire_api: str,
+ path: str,
+ payload: dict[str, object],
+) -> None:
+ message = "bad tool shape"
+ provider = MagicMock()
+ provider.preflight_stream.side_effect = InvalidRequestError(message)
+ app = create_test_app(_settings())
+
+ with (
+ patch(
+ "free_claude_code.api.routes.resolve_provider",
+ return_value=provider,
+ ),
+ TestClient(app) as client,
+ ):
+ response = client.post(path, json=payload)
+
+ provider.stream_response.assert_not_called()
+ _assert_ordinary_protocol_error(
+ response,
+ wire_api=wire_api,
+ status_code=400,
+ error_type="invalid_request_error",
+ message=message,
+ )
+
+
+ ("wire_api", "path", "payload"),
+ _PRODUCT_REQUESTS,
+ ids=("messages", "responses"),
+)
+ ("headers", "detail"),
+ [
+ ({}, "Missing API key"),
+ ({"x-api-key": "wrong"}, "Invalid API key"),
+ ],
+ ids=("missing", "invalid"),
+)
+def test_proxy_auth_preserves_fastapi_detail_contract(
+ wire_api: str,
+ path: str,
+ payload: dict[str, object],
+ headers: dict[str, str],
+ detail: str,
+) -> None:
+ app = create_test_app(_settings(anthropic_auth_token="secret"))
+
+ with TestClient(app) as client:
+ response = client.post(path, json=payload, headers=headers)
+
+ assert response.status_code == 401
+ assert response.json() == {"detail": detail}
+ assert response.headers["content-type"].startswith("application/json")
+ assert "x-should-retry" not in response.headers
+ request_id = response.headers["request-id"]
+ assert request_id.startswith("req_")
+ if wire_api == "responses":
+ assert response.headers["x-request-id"] == request_id
+ else:
+ assert "x-request-id" not in response.headers
diff --git a/tests/api/test_response_streams.py b/tests/api/test_response_streams.py
index 37f54d7a..56e0c10e 100644
--- a/tests/api/test_response_streams.py
+++ b/tests/api/test_response_streams.py
@@ -14,9 +14,12 @@ from free_claude_code.api.response_streams import (
bind_response_lifetime,
terminal_execution_error_response,
)
-from free_claude_code.core.anthropic import anthropic_error_payload
+from free_claude_code.core.anthropic import (
+ anthropic_error_payload,
+ anthropic_failure_payload,
+)
from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
-from free_claude_code.providers.exceptions import RateLimitError
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
async def _body_chunks(chunks: list[str]) -> AsyncGenerator[str]:
@@ -38,13 +41,10 @@ async def _body_then_raises(
def _json_error(exc: BaseException) -> JSONResponse:
- if isinstance(exc, RateLimitError):
- return JSONResponse(
+ if isinstance(exc, ExecutionFailure):
+ return terminal_execution_error_response(
status_code=exc.status_code,
- content=anthropic_error_payload(
- error_type=exc.error_type,
- message=exc.message,
- ),
+ content=anthropic_failure_payload(exc),
)
return JSONResponse(
status_code=500,
@@ -75,6 +75,7 @@ async def test_anthropic_response_waits_for_first_chunk_before_returning() -> No
anthropic_sse_streaming_response(
body(),
pre_start_error_response=_json_error,
+ request_id="req_test",
)
)
@@ -90,12 +91,21 @@ async def test_anthropic_response_waits_for_first_chunk_before_returning() -> No
@pytest.mark.asyncio
async def test_anthropic_pre_start_provider_error_returns_non_200_json() -> None:
response = await anthropic_sse_streaming_response(
- _body_raises(RateLimitError("provider says slow down")),
+ _body_raises(
+ ExecutionFailure(
+ kind=FailureKind.RATE_LIMIT,
+ status_code=429,
+ message="provider says slow down",
+ retryable=True,
+ )
+ ),
pre_start_error_response=_json_error,
+ request_id="req_test",
)
assert isinstance(response, JSONResponse)
assert response.status_code == 429
+ assert response.headers["x-should-retry"] == "false"
body = json.loads(bytes(response.body))
assert body["error"]["type"] == "rate_limit_error"
assert body["error"]["message"] == "provider says slow down"
@@ -129,6 +139,7 @@ async def test_anthropic_post_start_exception_emits_terminal_error_frame() -> No
RuntimeError("socket cut"),
),
pre_start_error_response=_json_error,
+ request_id="req_test",
)
assert isinstance(response, StreamingResponse)
diff --git a/tests/api/test_web_server_tools.py b/tests/api/test_web_server_tools.py
index bda1a0d2..d1463ed3 100644
--- a/tests/api/test_web_server_tools.py
+++ b/tests/api/test_web_server_tools.py
@@ -21,6 +21,7 @@ from free_claude_code.api.web_tools.outbound import (
)
from free_claude_code.api.web_tools.request import is_web_server_tool_request
from free_claude_code.api.web_tools.streaming import stream_web_server_tool_response
+from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.application.routing import (
ModelRouter,
ResolvedModel,
@@ -35,7 +36,6 @@ from free_claude_code.core.anthropic.stream_contracts import (
text_content,
)
from free_claude_code.messaging.event_parser import parse_cli_event
-from free_claude_code.providers.exceptions import InvalidRequestError
_STRICT_EGRESS = WebFetchEgressPolicy(
allow_private_network_targets=False,
diff --git a/tests/contracts/test_import_boundaries.py b/tests/contracts/test_import_boundaries.py
index 9148e849..d553bfd0 100644
--- a/tests/contracts/test_import_boundaries.py
+++ b/tests/contracts/test_import_boundaries.py
@@ -3,13 +3,6 @@
import ast
from pathlib import Path
-# `free_claude_code.api` may only import this narrow ``providers`` surface.
-_API_ALLOWED_PROVIDER_MODULES = frozenset(
- {
- "free_claude_code.providers.exceptions",
- }
-)
-
_PACKAGE_ROOT = Path("src") / "free_claude_code"
@@ -202,6 +195,43 @@ def test_core_does_not_import_product_packages() -> None:
assert offenders == []
+def test_core_does_not_import_provider_transport_sdks() -> None:
+ """Provider SDK and HTTP failure policy belongs under ``providers``."""
+ repo_root = Path(__file__).resolve().parents[2]
+ offenders = _imports_matching(
+ [repo_root / "src" / "free_claude_code" / "core"],
+ forbidden_prefixes=("httpx", "openai"),
+ )
+ assert offenders == []
+
+
+def test_providers_do_not_own_wire_error_type_literals() -> None:
+ """Provider failures carry semantic kinds, never protocol error names."""
+ repo_root = Path(__file__).resolve().parents[2]
+ providers_root = repo_root / "src" / "free_claude_code" / "providers"
+ wire_types = {
+ "api_error",
+ "authentication_error",
+ "billing_error",
+ "invalid_request_error",
+ "not_found_error",
+ "overloaded_error",
+ "permission_error",
+ "rate_limit_error",
+ "request_too_large",
+ "timeout_error",
+ }
+ offenders: list[str] = []
+ for path in providers_root.rglob("*.py"):
+ tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+ offenders.extend(
+ f"{path.relative_to(repo_root).as_posix()}:{node.lineno}: {node.value}"
+ for node in ast.walk(tree)
+ if isinstance(node, ast.Constant) and node.value in wire_types
+ )
+ assert offenders == []
+
+
def test_application_owns_routing_execution_and_consumer_ports() -> None:
repo_root = Path(__file__).resolve().parents[2]
package_root = repo_root / "src" / "free_claude_code"
@@ -251,7 +281,10 @@ def test_application_owns_routing_execution_and_consumer_ports() -> None:
"free_claude_code.application."
):
continue
- if imported == "free_claude_code.application.model_metadata":
+ if imported in {
+ "free_claude_code.application.errors",
+ "free_claude_code.application.model_metadata",
+ }:
continue
unexpected_provider_application_imports.append(
f"{path.relative_to(repo_root)}: {imported}"
@@ -447,22 +480,14 @@ def test_neutral_moved_helpers_keep_their_dependency_boundaries() -> None:
)
-def test_api_may_only_import_narrow_provider_facade() -> None:
- """HTTP layer must not depend on per-adapter provider subpackages."""
+def test_api_does_not_import_provider_implementation_packages() -> None:
+ """HTTP adapters depend on application contracts, never provider internals."""
repo_root = Path(__file__).resolve().parents[2]
- offenders: list[str] = []
- for path in (repo_root / "src" / "free_claude_code" / "api").rglob("*.py"):
- for imported in _imports_from(path, repo_root):
- if imported is None or not imported.startswith(
- "free_claude_code.providers"
- ):
- continue
- if imported in _API_ALLOWED_PROVIDER_MODULES:
- continue
- if imported.startswith("free_claude_code.providers."):
- rel = path.relative_to(repo_root)
- offenders.append(f"{rel}: {imported}")
- assert sorted(offenders) == []
+ offenders = _imports_matching(
+ [repo_root / "src" / "free_claude_code" / "api"],
+ forbidden_prefixes=("free_claude_code.providers",),
+ )
+ assert offenders == []
def test_removed_openrouter_rollback_transport_stays_removed() -> None:
@@ -580,51 +605,41 @@ def test_anthropic_core_has_no_cloud_provider_native_policy() -> None:
assert occurrences == []
-def test_anthropic_stream_engine_owns_provider_stream_state() -> None:
+def test_protocol_stream_state_and_provider_recovery_have_separate_owners() -> None:
repo_root = Path(__file__).resolve().parents[2]
- anthropic_root = repo_root / "src" / "free_claude_code" / "core" / "anthropic"
- streaming_root = anthropic_root / "streaming"
+ package_root = repo_root / "src" / "free_claude_code"
+ streaming_root = package_root / "core" / "anthropic" / "streaming"
+ providers_root = package_root / "providers"
+ stream_recovery = providers_root / "stream_recovery.py"
- for removed in {
- "sse.py",
- "emitted_sse_tracker.py",
- "stream_recovery.py",
- "stream_recovery_session.py",
- }:
- assert not (anthropic_root / removed).exists()
+ assert (
+ _imports_matching(
+ [streaming_root],
+ forbidden_prefixes=("free_claude_code.providers",),
+ )
+ == []
+ )
+ assert "free_claude_code.providers.failure_policy" in set(
+ _imports_from(stream_recovery, repo_root)
+ )
- for filename in {
- "__init__.py",
- "emitter.py",
- "ledger.py",
- "lifecycle.py",
- "recovery.py",
+ streaming_exports = (streaming_root / "__init__.py").read_text(encoding="utf-8")
+ for provider_owned_name in {
+ "RecoveryController",
+ "RecoveryFailureAction",
+ "RecoveryHoldbackBuffer",
+ "is_retryable_stream_error",
}:
- assert (streaming_root / filename).exists()
-
- forbidden = (
- "SSEBuilder",
- "ContentBlockManager",
- "ToolCallState",
- "EmittedNativeSseTracker",
- "StreamRecoverySession",
- "OpenAIChatStreamRunner",
- "AnthropicMessagesStreamRunner",
- )
- offenders: list[str] = []
- for path in [
- *anthropic_root.rglob("*.py"),
- *(repo_root / "src" / "free_claude_code" / "providers" / "transports").rglob(
- "*.py"
- ),
- ]:
- text = path.read_text(encoding="utf-8")
- offenders.extend(
- f"{path.relative_to(repo_root)}: {name}"
- for name in forbidden
- if name in text
+ assert provider_owned_name not in streaming_exports
+
+ for transport in {"openai_chat", "anthropic_messages"}:
+ imports = set(
+ _imports_from(
+ providers_root / "transports" / transport / "stream.py",
+ repo_root,
+ )
)
- assert sorted(offenders) == []
+ assert "free_claude_code.providers.stream_recovery" in imports
def test_openai_responses_uses_adapter_boundary() -> None:
@@ -717,7 +732,9 @@ def test_openai_responses_uses_adapter_boundary() -> None:
if "free_claude_code.core.openai_responses" in imports:
responses_importers.append(path.relative_to(repo_root).as_posix())
assert sorted(responses_importers) == [
+ "src/free_claude_code/api/app.py",
"src/free_claude_code/api/handlers/responses.py",
+ "src/free_claude_code/api/request_errors.py",
"src/free_claude_code/api/routes.py",
]
diff --git a/tests/contracts/test_stream_contracts.py b/tests/contracts/test_stream_contracts.py
index 2f5de9a0..e737c714 100644
--- a/tests/contracts/test_stream_contracts.py
+++ b/tests/contracts/test_stream_contracts.py
@@ -105,19 +105,6 @@ def test_redacted_thinking_block_start_stop_is_valid() -> None:
assert_anthropic_stream_contract(events)
-def test_terminal_error_is_valid_without_fake_message_stop() -> None:
- builder = AnthropicStreamLedger("msg_error", "contract-model")
- chunks = [builder.message_start()]
- chunks.extend(builder.ensure_text_block())
- chunks.append(builder.emit_text_delta("partial"))
- chunks.extend(builder.terminal_error_tail("provider interrupted"))
- events = parse_sse_text("".join(chunks))
-
- assert_anthropic_stream_contract(events, allow_error=True)
- assert event_names(events)[-2:] == ["content_block_stop", "error"]
- assert "message_stop" not in event_names(events)
-
-
def test_enable_thinking_false_suppresses_reasoning_only() -> None:
events = _parse_builder_events(
_events_from_text_chunks(
diff --git a/tests/core/anthropic/test_errors.py b/tests/core/anthropic/test_errors.py
index cbf5dd5a..21e1974d 100644
--- a/tests/core/anthropic/test_errors.py
+++ b/tests/core/anthropic/test_errors.py
@@ -3,8 +3,6 @@ import pytest
from free_claude_code.core.anthropic import (
anthropic_error_payload,
anthropic_status_for_error_type,
- get_user_facing_error_message,
- redact_sensitive_error_text,
)
@@ -43,23 +41,3 @@ def test_anthropic_error_payload_adds_request_id_and_redacts_credentials() -> No
},
"request_id": "req_test",
}
-
-
-def test_unknown_exception_message_is_detailed_but_redacted() -> None:
- error = RuntimeError("gateway failed api_key=SECRET details remain")
-
- assert get_user_facing_error_message(error) == (
- "gateway failed api_key=<redacted> details remain"
- )
-
-
-def test_redaction_covers_json_credentials_and_recognizable_key_prefixes() -> None:
- sanitized = redact_sensitive_error_text(
- '{"authorization":"Bearer AUTH_TOKEN","api_key":"sk-live-secret-key",'
- '"client_secret":"CLIENT_SECRET"} raw=nvapi-standalone-secret'
- )
-
- assert sanitized == (
- '{"authorization":"<redacted>","api_key":"<redacted>",'
- '"client_secret":"<redacted>"} raw=<redacted>'
- )
diff --git a/tests/providers/test_stream_ledger.py b/tests/core/anthropic/test_stream_ledger.py
similarity index 92%
rename from tests/providers/test_stream_ledger.py
rename to tests/core/anthropic/test_stream_ledger.py
index 42e68484..e1c05f2a 100644
--- a/tests/providers/test_stream_ledger.py
+++ b/tests/core/anthropic/test_stream_ledger.py
@@ -635,64 +635,6 @@ class TestAnthropicStreamLedgerStateManagement:
assert events == []
-class TestAnthropicStreamLedgerError:
- """Tests for protocol-native terminal errors."""
-
- def test_terminal_error_tail_closes_open_block_without_success_stop(self):
- builder = AnthropicStreamLedger("msg_1", "model")
- builder.start_text_block()
-
- events = list(builder.terminal_error_tail("Something went wrong"))
- parsed = parse_sse_text("".join(events))
-
- assert [event.event for event in parsed] == [
- "content_block_stop",
- "error",
- ]
- assert parsed[-1].data["error"]["message"] == "Something went wrong"
-
- def test_terminal_error_tail_after_message_delta_does_not_fake_message_stop(self):
- builder = AnthropicStreamLedger("msg_1", "model")
- builder.ingest_native_event(
- SSEEvent(
- "message_delta",
- {
- "type": "message_delta",
- "delta": {"stop_reason": "end_turn", "stop_sequence": None},
- "usage": {"input_tokens": 1, "output_tokens": 2},
- },
- "",
- )
- )
-
- events = list(builder.terminal_error_tail("Something went wrong"))
- parsed = parse_sse_text("".join(events))
-
- assert [event.event for event in parsed] == ["error"]
- assert parsed[0].data["error"]["message"] == "Something went wrong"
-
- def test_terminal_error_tail_after_message_stop_emits_nothing(self):
- builder = AnthropicStreamLedger("msg_1", "model")
- builder.ingest_native_event(
- SSEEvent(
- "message_delta",
- {
- "type": "message_delta",
- "delta": {"stop_reason": "end_turn", "stop_sequence": None},
- "usage": {"input_tokens": 1, "output_tokens": 2},
- },
- "",
- )
- )
- builder.ingest_native_event(
- SSEEvent("message_stop", {"type": "message_stop"}, "")
- )
-
- events = list(builder.terminal_error_tail("Something went wrong"))
-
- assert events == []
-
-
class TestAnthropicStreamLedgerTokenEstimation:
"""Tests for estimate_output_tokens."""
diff --git a/tests/core/anthropic/test_stream_repair.py b/tests/core/anthropic/test_stream_repair.py
new file mode 100644
index 00000000..1f8c7e30
--- /dev/null
+++ b/tests/core/anthropic/test_stream_repair.py
@@ -0,0 +1,47 @@
+"""Neutral Anthropic continuation and tool-repair helpers."""
+
+from free_claude_code.core.anthropic.streaming import (
+ ToolSchema,
+ accept_tool_json_repair,
+ continuation_suffix,
+)
+
+
+def test_continuation_suffix_trims_overlap() -> None:
+ assert continuation_suffix("hello wor", "world") == "ld"
+ assert continuation_suffix("alpha", "alpha beta") == " beta"
+ assert continuation_suffix("", "fresh") == "fresh"
+
+
+def test_tool_json_repair_requires_append_only_schema_valid_json() -> None:
+ schemas = {
+ "Echo": ToolSchema(
+ name="Echo",
+ input_schema={
+ "type": "object",
+ "properties": {"message": {"type": "string"}},
+ "required": ["message"],
+ "additionalProperties": False,
+ },
+ )
+ }
+
+ accepted = accept_tool_json_repair(
+ '{"message":',
+ '"ok"}',
+ tool_name="Echo",
+ schemas=schemas,
+ )
+ assert accepted is not None
+ assert accepted.suffix == '"ok"}'
+ assert accepted.parsed_input == {"message": "ok"}
+
+ assert (
+ accept_tool_json_repair(
+ '{"message":',
+ "1}",
+ tool_name="Echo",
+ schemas=schemas,
+ )
+ is None
+ )
diff --git a/tests/core/openai_responses/test_sse.py b/tests/core/openai_responses/test_sse.py
index 939a67f3..8d59893f 100644
--- a/tests/core/openai_responses/test_sse.py
+++ b/tests/core/openai_responses/test_sse.py
@@ -5,6 +5,7 @@ import pytest
from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
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 (
OpenAIResponsesAdapter,
OpenAIResponsesRequest,
@@ -153,6 +154,85 @@ async def test_anthropic_malformed_function_tool_arguments_fail_on_eof() -> None
assert events[-1].data["response"]["output"] == []
+async def test_provider_failure_outranks_provisional_incomplete_function_call() -> None:
+ failure = ExecutionFailure(
+ kind=FailureKind.RATE_LIMIT,
+ status_code=429,
+ message="provider is busy\n\nRequest ID: req_failure_precedence",
+ retryable=True,
+ )
+ incomplete_tool = _anthropic_tool_stream(partial_json='{"value":')[:4]
+
+ text = await _collect_sse(
+ _responses_sse(
+ _aiter_then_raise(incomplete_tool, failure),
+ {"model": "nvidia_nim/test-model", "stream": True},
+ )
+ )
+
+ events = parse_sse_text(text)
+ assert [event.event for event in events].count("response.failed") == 1
+ assert events[-1].event == "response.failed"
+ failed = events[-1].data["response"]
+ assert failed["id"] == events[0].data["response"]["id"]
+ assert failed["error"] == {
+ "message": "provider is busy\n\nRequest ID: req_failure_precedence",
+ "type": "rate_limit_error",
+ "param": None,
+ "code": None,
+ }
+
+
+async def test_post_start_failure_observer_runs_before_terminal_failure_event() -> None:
+ failure = RuntimeError("socket closed")
+ timeline: list[tuple[str, object]] = []
+
+ def observe_terminal_failure(exc: BaseException) -> None:
+ timeline.append(("observed", exc))
+
+ stream = _ADAPTER.iter_sse_from_anthropic(
+ _aiter_then_raise(_anthropic_text_stream("partial")[:3], failure),
+ OpenAIResponsesRequest.model_validate(
+ {"model": "nvidia_nim/test-model", "stream": True}
+ ),
+ on_post_start_terminal_failure=observe_terminal_failure,
+ )
+ parts: list[str] = []
+ async for chunk in stream:
+ parts.append(chunk)
+ event = parse_sse_text(chunk)
+ assert len(event) == 1
+ timeline.append(("emitted", event[0].event))
+
+ events = parse_sse_text("".join(parts))
+ assert timeline.count(("observed", failure)) == 1
+ assert timeline.index(("observed", failure)) < timeline.index(
+ ("emitted", "response.failed")
+ )
+ assert events[-1].data["response"]["error"]["message"] == "socket closed"
+
+
+async def test_unrelated_post_start_exception_group_remains_unexpected() -> None:
+ grouped = ExceptionGroup("stream failed", [RuntimeError("socket closed")])
+ observed: list[BaseException] = []
+ stream = _ADAPTER.iter_sse_from_anthropic(
+ _aiter_then_raise(_anthropic_text_stream("partial")[:3], grouped),
+ OpenAIResponsesRequest.model_validate(
+ {"model": "nvidia_nim/test-model", "stream": True}
+ ),
+ on_post_start_terminal_failure=observed.append,
+ )
+
+ events = parse_sse_text(await _collect_sse(stream))
+
+ assert observed == [grouped]
+ assert events[-1].event == "response.failed"
+ assert events[-1].data["response"]["error"]["type"] == "api_error"
+
+
@pytest.mark.asyncio
async def test_namespaced_anthropic_tool_stream_restores_responses_namespace() -> None:
text = await _collect_sse(
@@ -483,6 +563,14 @@ async def _aiter(chunks: list[str]) -> AsyncIterator[str]:
yield chunk
+async def _aiter_then_raise(
+ chunks: list[str], failure: BaseException
+) -> AsyncIterator[str]:
+ for chunk in chunks:
+ yield chunk
+ raise failure
+
+
def _anthropic_text_stream(text: str) -> list[str]:
return [
format_sse_event("message_start", {"type": "message_start", "message": {}}),
diff --git a/tests/core/test_diagnostics.py b/tests/core/test_diagnostics.py
new file mode 100644
index 00000000..5654f201
--- /dev/null
+++ b/tests/core/test_diagnostics.py
@@ -0,0 +1,152 @@
+"""Protocol-neutral diagnostic redaction and detail contracts."""
+
+from httpx import ConnectError, HTTPStatusError, Request, Response
+
+from free_claude_code.core.diagnostics import (
+ ERROR_DETAIL_DISPLAY_CAP_BYTES,
+ UpstreamErrorDetail,
+ attach_upstream_error_body,
+ exception_cause_types,
+ extract_upstream_error_detail,
+ format_execution_failure_message,
+ format_user_error_preview,
+ redact_sensitive_error_text,
+ safe_exception_message,
+)
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
+
+
+def test_redaction_preserves_context_and_covers_recognizable_credentials() -> None:
+ sanitized = redact_sensitive_error_text(
+ '{"authorization":"Bearer AUTH_TOKEN","api_key":"sk-live-secret-key",'
+ '"client_secret":"CLIENT_SECRET"} raw=nvapi-standalone-secret '
+ "token=PLAIN_TOKEN"
+ )
+
+ assert sanitized == (
+ '{"authorization":"<redacted>","api_key":"<redacted>",'
+ '"client_secret":"<redacted>"} raw=<redacted> token=<redacted>'
+ )
+
+
+def test_safe_exception_message_is_detailed_redacted_and_non_empty() -> None:
+ assert (
+ safe_exception_message(
+ RuntimeError("gateway failed api_key=SECRET useful detail")
+ )
+ == "gateway failed api_key=<redacted> useful detail"
+ )
+ assert safe_exception_message(RuntimeError()) == (
+ "Provider request failed unexpectedly."
+ )
+ assert format_user_error_preview(ValueError("x" * 500), max_len=20) == "x" * 20
+
+
+def test_extract_upstream_error_detail_compacts_json_and_redacts_secrets() -> None:
+ response = Response(
+ status_code=400,
+ request=Request("POST", "https://provider.test/v1/messages"),
+ json={
+ "error": {
+ "type": "BadRequest",
+ "message": "bad field api_key=SECRET authorization: Bearer TOKEN",
+ }
+ },
+ )
+ error = HTTPStatusError(
+ "Bad Request",
+ request=response.request,
+ response=response,
+ )
+
+ detail = extract_upstream_error_detail(error)
+
+ assert isinstance(detail, UpstreamErrorDetail)
+ assert detail.status_code == 400
+ assert detail.body_text == (
+ '{"error":{"type":"BadRequest","message":'
+ '"bad field api_key=<redacted> authorization: <redacted>"}}'
+ )
+ assert detail.exception_text == "Bad Request"
+ assert detail.cause_chain_text is None
+ assert detail.category_hint == "BadRequest"
+ assert not detail.body_truncated
+ assert "SECRET" not in repr(detail)
+ assert "TOKEN" not in repr(detail)
+
+
+def test_attached_upstream_body_is_capped_after_redaction() -> None:
+ assert ERROR_DETAIL_DISPLAY_CAP_BYTES == 16_384
+ response = Response(
+ status_code=500,
+ request=Request("POST", "https://provider.test/v1/messages"),
+ content=b"",
+ )
+ error = HTTPStatusError(
+ "Server Error",
+ request=response.request,
+ response=response,
+ )
+ attach_upstream_error_body(
+ error,
+ "token=SECRET " + "x" * ERROR_DETAIL_DISPLAY_CAP_BYTES,
+ )
+
+ detail = extract_upstream_error_detail(error)
+
+ assert detail.body_text is not None
+ assert detail.body_truncated
+ assert "SECRET" not in detail.body_text
+ assert "token=<redacted>" in detail.body_text
+ assert f"truncated after {ERROR_DETAIL_DISPLAY_CAP_BYTES} bytes" in detail.body_text
+
+
+def test_cause_chain_is_redacted_capped_and_has_safe_type_metadata() -> None:
+ request = Request("POST", "https://provider.test/v1/messages")
+ error = RuntimeError("provider connection failed")
+ error.__cause__ = ConnectError(
+ "connect failed authorization: Bearer SECRET token=ALSO_SECRET "
+ + "x" * ERROR_DETAIL_DISPLAY_CAP_BYTES,
+ request=request,
+ )
+
+ detail = extract_upstream_error_detail(error)
+
+ assert exception_cause_types(error) == ("ConnectError",)
+ assert detail.cause_chain_text is not None
+ assert "ConnectError: connect failed authorization: <redacted>" in (
+ detail.cause_chain_text
+ )
+ assert "SECRET" not in detail.cause_chain_text
+ assert f"truncated after {ERROR_DETAIL_DISPLAY_CAP_BYTES} bytes" in (
+ detail.cause_chain_text
+ )
+
+
+def test_execution_failure_format_uses_semantic_category_and_request_id() -> None:
+ failure = ExecutionFailure(
+ kind=FailureKind.INVALID_REQUEST,
+ status_code=400,
+ message="Invalid request sent to provider.",
+ retryable=False,
+ )
+ detail = UpstreamErrorDetail(
+ status_code=400,
+ body_text='{"error":{"message":"bad field token=<redacted>"}}',
+ exception_text="Bad Request",
+ category_hint=None,
+ )
+
+ message = format_execution_failure_message(
+ failure,
+ detail,
+ upstream_name="ACME",
+ request_id="req_diagnostic",
+ )
+
+ assert "Upstream provider ACME returned HTTP 400." in message
+ assert "Category: invalid_request" in message
+ assert "Mapped message: Invalid request sent to provider." in message
+ assert '{"error":{"message":"bad field token=<redacted>"}}' in message
+ assert "Request ID: req_diagnostic" in message
+ assert "invalid_request_error" not in message
diff --git a/tests/core/test_failure_protocol_mapping.py b/tests/core/test_failure_protocol_mapping.py
new file mode 100644
index 00000000..029d544c
--- /dev/null
+++ b/tests/core/test_failure_protocol_mapping.py
@@ -0,0 +1,80 @@
+"""Canonical execution failures and their protocol-owned wire mappings."""
+
+import pytest
+
+from free_claude_code.core.anthropic.errors import (
+ anthropic_error_type_for_failure,
+ anthropic_failure_payload,
+ execution_failure_from_anthropic_error,
+)
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
+from free_claude_code.core.openai_responses.errors import (
+ openai_error_type_for_failure,
+ openai_failure_payload,
+)
+
+
+ ("kind", "anthropic_type", "openai_type"),
+ [
+ (FailureKind.INVALID_REQUEST, "invalid_request_error", "invalid_request_error"),
+ (FailureKind.AUTHENTICATION, "authentication_error", "authentication_error"),
+ (FailureKind.PERMISSION, "permission_error", "permission_error"),
+ (FailureKind.RATE_LIMIT, "rate_limit_error", "rate_limit_error"),
+ (FailureKind.OVERLOADED, "overloaded_error", "overloaded_error"),
+ # Existing finalized transport timeouts are exposed as api_error; the
+ # semantic kind becomes more precise without changing that wire contract.
+ (FailureKind.TIMEOUT, "api_error", "api_error"),
+ (FailureKind.UPSTREAM, "api_error", "api_error"),
+ (FailureKind.UNAVAILABLE, "api_error", "api_error"),
+ ],
+)
+def test_each_protocol_owns_failure_kind_to_wire_type_mapping(
+ kind: FailureKind,
+ anthropic_type: str,
+ openai_type: str,
+) -> None:
+ assert anthropic_error_type_for_failure(kind) == anthropic_type
+ assert openai_error_type_for_failure(kind) == openai_type
+
+
+ ("native_type", "kind", "status_code"),
+ [
+ ("billing_error", FailureKind.PERMISSION, 402),
+ ("not_found_error", FailureKind.INVALID_REQUEST, 404),
+ ("request_too_large", FailureKind.INVALID_REQUEST, 413),
+ ("timeout_error", FailureKind.TIMEOUT, 504),
+ ],
+)
+def test_native_error_type_round_trips_through_status_aware_execution_failure(
+ native_type: str,
+ kind: FailureKind,
+ status_code: int,
+) -> None:
+ failure = execution_failure_from_anthropic_error(
+ {
+ "type": "error",
+ "error": {
+ "type": native_type,
+ "message": "Native provider failure.",
+ },
+ }
+ )
+
+ assert failure.kind is kind
+ assert failure.status_code == status_code
+ assert anthropic_failure_payload(failure)["error"]["type"] == native_type
+ assert openai_failure_payload(failure)["error"]["type"] == native_type
+
+
+def test_finalized_status_502_timeout_keeps_existing_api_error_wire_type() -> None:
+ failure = ExecutionFailure(
+ kind=FailureKind.TIMEOUT,
+ status_code=502,
+ message="Provider request timed out.",
+ retryable=True,
+ )
+
+ assert anthropic_failure_payload(failure)["error"]["type"] == "api_error"
+ assert openai_failure_payload(failure)["error"]["type"] == "api_error"
diff --git a/tests/core/test_failures.py b/tests/core/test_failures.py
new file mode 100644
index 00000000..1a2672bb
--- /dev/null
+++ b/tests/core/test_failures.py
@@ -0,0 +1,112 @@
+"""Canonical, protocol-neutral execution failure contracts."""
+
+from dataclasses import FrozenInstanceError, fields, is_dataclass
+
+import pytest
+
+from free_claude_code.core.failures import (
+ ExecutionFailure,
+ FailureKind,
+ find_execution_failure,
+)
+
+
+def test_failure_kind_has_only_protocol_neutral_semantics() -> None:
+ assert tuple(FailureKind) == (
+ FailureKind.INVALID_REQUEST,
+ FailureKind.AUTHENTICATION,
+ FailureKind.PERMISSION,
+ FailureKind.RATE_LIMIT,
+ FailureKind.OVERLOADED,
+ FailureKind.TIMEOUT,
+ FailureKind.UPSTREAM,
+ FailureKind.UNAVAILABLE,
+ )
+ assert tuple(kind.value for kind in FailureKind) == (
+ "invalid_request",
+ "authentication",
+ "permission",
+ "rate_limit",
+ "overloaded",
+ "timeout",
+ "upstream",
+ "unavailable",
+ )
+
+
+def test_execution_failure_is_the_direct_frozen_slotted_exception() -> None:
+ failure = ExecutionFailure(
+ kind=FailureKind.RATE_LIMIT,
+ status_code=429,
+ message="Provider rate limit reached.",
+ retryable=True,
+ )
+
+ assert is_dataclass(failure)
+ assert tuple(field.name for field in fields(failure)) == (
+ "kind",
+ "status_code",
+ "message",
+ "retryable",
+ )
+ assert ExecutionFailure.__slots__ == (
+ "kind",
+ "status_code",
+ "message",
+ "retryable",
+ )
+ assert str(failure) == "Provider rate limit reached."
+ assert failure.args == ("Provider rate limit reached.",)
+
+ with pytest.raises(ExecutionFailure) as raised:
+ raise failure
+
+ assert raised.value is failure
+ with pytest.raises(FrozenInstanceError):
+ failure.status_code = 500
+
+
+def test_execution_failure_uses_exception_identity_not_value_equality() -> None:
+ first = ExecutionFailure(
+ kind=FailureKind.UPSTREAM,
+ status_code=500,
+ message="same",
+ retryable=True,
+ )
+ second = ExecutionFailure(
+ kind=FailureKind.UPSTREAM,
+ status_code=500,
+ message="same",
+ retryable=True,
+ )
+
+ assert first is not second
+ assert first != second
+
+
+def test_find_execution_failure_recurses_through_nested_groups() -> None:
+ failure = ExecutionFailure(
+ kind=FailureKind.RATE_LIMIT,
+ status_code=429,
+ message="provider is busy",
+ retryable=True,
+ )
+ grouped = ExceptionGroup(
+ "stream and cleanup failed",
+ [
+ RuntimeError("cleanup failed"),
+ ExceptionGroup("provider failed", [failure]),
+ ],
+ )
+
+ assert find_execution_failure(failure) is failure
+ assert find_execution_failure(grouped) is failure
+
+
+def test_find_execution_failure_leaves_unrelated_groups_unclassified() -> None:
+ grouped = BaseExceptionGroup(
+ "unrelated failures",
+ [RuntimeError("socket closed"), KeyboardInterrupt()],
+ )
+
+ assert find_execution_failure(grouped) is None
diff --git a/tests/providers/test_anthropic_messages.py b/tests/providers/test_anthropic_messages.py
index d3eba10e..d3f00d00 100644
--- a/tests/providers/test_anthropic_messages.py
+++ b/tests/providers/test_anthropic_messages.py
@@ -9,14 +9,17 @@ import pytest
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
from free_claude_code.core.anthropic.streaming import (
- MIDSTREAM_RECOVERY_ATTEMPTS,
AnthropicStreamLedger,
- TruncatedProviderStreamError,
format_sse_event,
)
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.providers.base import ProviderConfig
-from free_claude_code.providers.exceptions import ProviderError
from free_claude_code.providers.rate_limit import ProviderRateLimiter
+from free_claude_code.providers.stream_recovery import (
+ EARLY_TRANSPARENT_TOTAL_ATTEMPTS,
+ MIDSTREAM_RECOVERY_ATTEMPTS,
+ TruncatedProviderStreamError,
+)
from free_claude_code.providers.transports.anthropic_messages import (
AnthropicMessagesTransport,
)
@@ -49,12 +52,15 @@ class FakeResponse:
text="",
raise_after_line_index: int | None = None,
raise_error: Exception | None = None,
+ close_error: Exception | None = None,
):
self.status_code = status_code
self._lines = lines or []
self._text = text
self._raise_after_line_index = raise_after_line_index
self._raise_error = raise_error or RuntimeError("mid-stream failure")
+ self._close_error = close_error
+ self.close_calls = 0
self.is_closed = False
self.request = httpx.Request("POST", "https://example.test/v1/messages")
self.headers = httpx.Headers()
@@ -80,6 +86,9 @@ class FakeResponse:
response.raise_for_status()
async def aclose(self):
+ self.close_calls += 1
+ if self._close_error is not None:
+ raise self._close_error
self.is_closed = True
async def aiter_bytes(self, chunk_size: int = 65_536):
@@ -309,7 +318,7 @@ async def test_stream_maps_pre_start_non_200_to_provider_error_and_closes_respon
new_callable=AsyncMock,
return_value=response,
),
- pytest.raises(ProviderError) as exc_info,
+ pytest.raises(ExecutionFailure) as exc_info,
):
[event async for event in provider.stream_response(req, request_id="REQ_123")]
@@ -319,6 +328,45 @@ async def test_stream_maps_pre_start_non_200_to_provider_error_and_closes_respon
assert "REQ_123" in exc_info.value.message
+async def test_native_http_close_failure_cannot_mask_mapped_status(provider_config):
+ provider = NativeProvider(
+ provider_config,
+ rate_limiter=passthrough_rate_limiter(),
+ )
+ req = make_messages_request()
+ response = FakeResponse(
+ status_code=400,
+ text="original native HTTP body",
+ close_error=RuntimeError("cleanup api_key=SECRET"),
+ )
+
+ with (
+ patch.object(provider._client, "build_request", return_value=MagicMock()),
+ patch.object(
+ provider._client,
+ "send",
+ new_callable=AsyncMock,
+ return_value=response,
+ ),
+ pytest.raises(ExecutionFailure) as exc_info,
+ ):
+ [
+ event
+ async for event in provider.stream_response(
+ req,
+ request_id="req_native_http_close_failure",
+ )
+ ]
+
+ assert response.close_calls == 1
+ assert exc_info.value.kind is FailureKind.INVALID_REQUEST
+ assert exc_info.value.status_code == 400
+ assert "original native HTTP body" in exc_info.value.message
+ assert "cleanup" not in exc_info.value.message
+ assert "SECRET" not in exc_info.value.message
+
+
@pytest.mark.asyncio
async def test_precommit_native_error_raises_without_leaking_open_block(
provider_config,
@@ -367,7 +415,7 @@ async def test_precommit_native_error_raises_without_leaking_open_block(
new_callable=AsyncMock,
return_value=response,
),
- pytest.raises(ProviderError) as exc_info,
+ pytest.raises(ExecutionFailure) as exc_info,
):
[e async for e in provider.stream_response(req)]
@@ -375,10 +423,116 @@ async def test_precommit_native_error_raises_without_leaking_open_block(
@pytest.mark.asyncio
-async def test_midstream_error_after_native_message_delta_does_not_duplicate_terminal(
+async def test_native_upstream_error_event_retries_then_raises_canonical_failure(
+ provider_config,
+):
+ """Native wire errors become one semantic failure instead of leaking or masking."""
+ provider = NativeProvider(
+ provider_config,
+ rate_limiter=passthrough_rate_limiter(),
+ )
+ req = make_messages_request()
+ upstream_error = format_sse_event(
+ "error",
+ {
+ "type": "error",
+ "error": {
+ "type": "rate_limit_error",
+ "message": "native quota exhausted api_key=SECRET useful detail",
+ },
+ },
+ )
+ responses = [
+ FakeResponse(lines=_lines_from_events(upstream_error))
+ for _ in range(EARLY_TRANSPARENT_TOTAL_ATTEMPTS)
+ ]
+ events: list[str] = []
+
+ with (
+ patch.object(provider._client, "build_request", return_value=MagicMock()),
+ patch.object(
+ provider._client,
+ "send",
+ new_callable=AsyncMock,
+ side_effect=responses,
+ ) as mock_send,
+ pytest.raises(ExecutionFailure) as exc_info,
+ ):
+ async for event in provider.stream_response(
+ req,
+ request_id="req_native_error",
+ ):
+ events.extend((event,))
+
+ failure = exc_info.value
+ assert mock_send.await_count == EARLY_TRANSPARENT_TOTAL_ATTEMPTS
+ assert all(response.is_closed for response in responses)
+ assert events == []
+ assert failure.kind is FailureKind.RATE_LIMIT
+ assert failure.status_code == 429
+ assert failure.retryable
+ assert "native quota exhausted" in failure.message
+ assert "useful detail" in failure.message
+ assert "api_key=<redacted>" in failure.message
+ assert "SECRET" not in failure.message
+ assert "Request ID: req_native_error" in failure.message
+
+
+async def test_native_stream_close_failure_cannot_mask_execution_failure(
provider_config,
):
- """If native upstream emitted message_delta before cutoff, recovery cannot append content."""
+ provider = NativeProvider(
+ provider_config,
+ rate_limiter=passthrough_rate_limiter(),
+ )
+ req = make_messages_request()
+ upstream_error = format_sse_event(
+ "error",
+ {
+ "type": "error",
+ "error": {
+ "type": "invalid_request_error",
+ "message": "original native provider failure",
+ },
+ },
+ )
+ response = FakeResponse(
+ lines=_lines_from_events(upstream_error),
+ close_error=RuntimeError("cleanup api_key=SECRET"),
+ )
+
+ with (
+ patch.object(provider._client, "build_request", return_value=MagicMock()),
+ patch.object(
+ provider._client,
+ "send",
+ new_callable=AsyncMock,
+ return_value=response,
+ ),
+ pytest.raises(ExecutionFailure) as exc_info,
+ ):
+ [
+ event
+ async for event in provider.stream_response(
+ req,
+ request_id="req_native_close_failure",
+ )
+ ]
+
+ assert response.close_calls == 1
+ assert exc_info.value.kind is FailureKind.INVALID_REQUEST
+ assert exc_info.value.status_code == 400
+ assert "original native provider failure" in exc_info.value.message
+ assert "cleanup" not in exc_info.value.message
+ assert "SECRET" not in exc_info.value.message
+
+
+async def test_midstream_error_after_native_message_delta_raises_without_wire_terminal(
+ provider_config,
+):
+ """Providers preserve the committed prefix and leave terminal wire errors to API."""
provider = NativeProvider(
provider_config,
rate_limiter=passthrough_rate_limiter(),
@@ -434,6 +588,7 @@ async def test_midstream_error_after_native_message_delta_does_not_duplicate_ter
)
)
+ events: list[str] = []
with (
patch.object(provider._client, "build_request", return_value=MagicMock()),
patch.object(
@@ -448,14 +603,17 @@ async def test_midstream_error_after_native_message_delta_does_not_duplicate_ter
new_callable=AsyncMock,
return_value=("hello recovered", ""),
) as mock_collect,
+ pytest.raises(ExecutionFailure) as exc_info,
):
- events = [e async for e in provider.stream_response(req)]
+ async for event in provider.stream_response(req):
+ events.extend((event,))
parsed = parse_sse_text("".join(events))
assert mock_collect.await_count == 0
+ assert "Provider stream ended without message_stop." in exc_info.value.message
assert sum(event.event == "message_delta" for event in parsed) == 1
assert sum(event.event == "message_stop" for event in parsed) == 0
- assert sum(event.event == "error" for event in parsed) == 1
+ assert sum(event.event == "error" for event in parsed) == 0
message_delta_index = next(
index for index, event in enumerate(parsed) if event.event == "message_delta"
)
@@ -804,7 +962,7 @@ async def test_native_recovery_collect_text_reads_eager_start_content(provider_c
@pytest.mark.asyncio
-async def test_truncated_native_recovery_stream_falls_back_to_error_tail(
+async def test_truncated_native_recovery_stream_raises_after_closing_block(
provider_config,
):
"""Partial native recovery bytes are not converted into a success tail."""
@@ -862,6 +1020,7 @@ async def test_truncated_native_recovery_stream_falls_back_to_error_tail(
for _ in range(MIDSTREAM_RECOVERY_ATTEMPTS)
]
+ events: list[str] = []
with (
patch.object(provider._client, "build_request", return_value=MagicMock()),
patch.object(
@@ -870,16 +1029,20 @@ async def test_truncated_native_recovery_stream_falls_back_to_error_tail(
new_callable=AsyncMock,
side_effect=[original, *recovery_responses],
) as mock_send,
+ pytest.raises(ExecutionFailure) as exc_info,
):
- events = [e async for e in provider.stream_response(req)]
+ async for event in provider.stream_response(req):
+ events.extend((event,))
event_text = "".join(events)
assert mock_send.await_count == 1 + MIDSTREAM_RECOVERY_ATTEMPTS
assert original_text in event_text
assert "world" not in event_text
- assert "Provider stream ended without message_stop." in event_text
+ assert "Provider stream ended without message_stop." in exc_info.value.message
+ assert "Provider stream ended without message_stop." not in event_text
parsed = parse_sse_text(event_text)
- assert parsed[-1].event == "error"
+ assert parsed[-1].event == "content_block_stop"
+ assert not any(event.event == "error" for event in parsed)
assert not any(event.event == "message_stop" for event in parsed)
assert not any(
event.event == "content_block_delta"
diff --git a/tests/providers/test_anthropic_messages_429_retry.py b/tests/providers/test_anthropic_messages_429_retry.py
index 74100f56..26017819 100644
--- a/tests/providers/test_anthropic_messages_429_retry.py
+++ b/tests/providers/test_anthropic_messages_429_retry.py
@@ -6,8 +6,8 @@ import httpx
import pytest
from free_claude_code.core.anthropic.stream_contracts import event_names, parse_sse_text
+from free_claude_code.core.failures import ExecutionFailure
from free_claude_code.providers.base import ProviderConfig
-from free_claude_code.providers.exceptions import ProviderError
from tests.providers.request_factory import make_messages_request
from tests.providers.support import retrying_rate_limiter
from tests.providers.test_anthropic_messages import (
@@ -204,7 +204,7 @@ async def test_native_stream_5xx_retry_exhausted(provider_config, status_code, s
return_value=bad,
) as mock_send,
patch("asyncio.sleep", new_callable=AsyncMock),
- pytest.raises(ProviderError) as exc_info,
+ pytest.raises(ExecutionFailure) as exc_info,
):
[e async for e in provider.stream_response(req)]
@@ -236,7 +236,7 @@ async def test_native_stream_connection_error_retry_exhausted(provider_config):
patch(
"free_claude_code.providers.transports.anthropic_messages.stream.trace_event"
) as trace,
- pytest.raises(ProviderError) as exc_info,
+ pytest.raises(ExecutionFailure) as exc_info,
):
[e async for e in provider.stream_response(req, request_id="req_native_conn")]
@@ -271,7 +271,7 @@ async def test_non_retryable_4xx_http_error_not_retried(provider_config):
new_callable=AsyncMock,
return_value=err,
) as mock_send,
- pytest.raises(ProviderError) as exc_info,
+ pytest.raises(ExecutionFailure) as exc_info,
):
[e async for e in provider.stream_response(req)]
diff --git a/tests/providers/test_cloudflare.py b/tests/providers/test_cloudflare.py
index d5bf4c9e..5c51f9fd 100644
--- a/tests/providers/test_cloudflare.py
+++ b/tests/providers/test_cloudflare.py
@@ -7,6 +7,7 @@ from unittest.mock import AsyncMock, patch
import httpx
import pytest
+from free_claude_code.application.errors import ApplicationUnavailableError
from free_claude_code.core.anthropic.models import Message, MessagesRequest
from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
from free_claude_code.providers.base import ProviderConfig
@@ -15,7 +16,6 @@ from free_claude_code.providers.cloudflare import (
CloudflareProvider,
cloudflare_ai_base_url,
)
-from free_claude_code.providers.exceptions import AuthenticationError
from tests.providers.support import passthrough_rate_limiter
_ACCOUNT_ID = "account-123"
@@ -72,7 +72,7 @@ def test_cloudflare_ai_base_url_uses_account_scoped_openai_chat_root() -> None:
def test_missing_account_id_raises_authentication_error(
cloudflare_config: ProviderConfig,
) -> None:
- with pytest.raises(AuthenticationError, match="CLOUDFLARE_ACCOUNT_ID"):
+ with pytest.raises(ApplicationUnavailableError, match="CLOUDFLARE_ACCOUNT_ID"):
CloudflareProvider(
cloudflare_config, account_id=" ", rate_limiter=passthrough_rate_limiter()
)
diff --git a/tests/providers/test_cohere.py b/tests/providers/test_cohere.py
index 121e9e1d..819e29ef 100644
--- a/tests/providers/test_cohere.py
+++ b/tests/providers/test_cohere.py
@@ -4,9 +4,9 @@ from unittest.mock import AsyncMock, MagicMock, patch
import pytest
+from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.cohere import COHERE_DEFAULT_BASE, CohereProvider
-from free_claude_code.providers.exceptions import InvalidRequestError
from tests.providers.request_factory import make_messages_request
from tests.providers.support import passthrough_rate_limiter
diff --git a/tests/providers/test_deepseek.py b/tests/providers/test_deepseek.py
index a1659126..034f9748 100644
--- a/tests/providers/test_deepseek.py
+++ b/tests/providers/test_deepseek.py
@@ -6,6 +6,7 @@ from unittest.mock import AsyncMock, patch
import pytest
+from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
from free_claude_code.core.anthropic.models import (
ContentBlockImage,
@@ -19,7 +20,6 @@ from free_claude_code.providers.deepseek import (
DEEPSEEK_DEFAULT_BASE,
DeepSeekProvider,
)
-from free_claude_code.providers.exceptions import InvalidRequestError
from tests.providers.support import passthrough_rate_limiter
diff --git a/tests/providers/test_error_mapping.py b/tests/providers/test_error_mapping.py
deleted file mode 100644
index aae25536..00000000
--- a/tests/providers/test_error_mapping.py
+++ /dev/null
@@ -1,428 +0,0 @@
-"""Tests for provider error mapping and core error formatting."""
-
-from pathlib import Path
-from unittest.mock import MagicMock
-
-import openai
-import pytest
-from httpx import ConnectError, HTTPStatusError, ReadTimeout, Request, Response
-
-from free_claude_code.config.constants import PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES
-from free_claude_code.core.anthropic import (
- append_request_id,
- format_user_error_preview,
- get_user_facing_error_message,
-)
-from free_claude_code.providers.error_mapping import (
- attach_provider_error_body,
- exception_cause_types,
- extract_provider_error_detail,
- format_provider_error_message,
- map_error,
- user_visible_message_for_mapped_provider_error,
-)
-from free_claude_code.providers.exceptions import (
- APIError,
- AuthenticationError,
- InvalidRequestError,
- OverloadedError,
- RateLimitError,
-)
-from free_claude_code.providers.rate_limit import ProviderRateLimiter
-
-
-def _make_openai_error(cls, message="test error", status_code=None):
- """Helper to create openai exceptions with required httpx objects."""
- response = Response(
- status_code=status_code or 500, request=Request("POST", "http://test")
- )
- body = {"error": {"message": message}}
- # openai.APIError base class has a different constructor signature
- if cls is openai.APIError:
- return cls(message, request=Request("POST", "http://test"), body=body)
- return cls(message, response=response, body=body)
-
-
-def _make_statusless_openai_api_error(
- message: str, body: object | None = None
-) -> openai.APIError:
- return openai.APIError(message, request=Request("POST", "http://test"), body=body)
-
-
-def _rate_limiter() -> MagicMock:
- return MagicMock(spec=ProviderRateLimiter)
-
-
-class TestMapError:
- """Tests for map_error function."""
-
- def test_authentication_error(self):
- """openai.AuthenticationError -> AuthenticationError."""
- exc = _make_openai_error(openai.AuthenticationError, status_code=401)
- result = map_error(exc, rate_limiter=_rate_limiter())
- assert isinstance(result, AuthenticationError)
- assert result.status_code == 401
-
- def test_rate_limit_error(self):
- """openai.RateLimitError -> RateLimitError and triggers global block."""
- exc = _make_openai_error(openai.RateLimitError, status_code=429)
- limiter = _rate_limiter()
-
- result = map_error(exc, rate_limiter=limiter)
-
- assert isinstance(result, RateLimitError)
- assert result.status_code == 429
- limiter.set_blocked.assert_called_once_with(60)
-
- def test_bad_request_error(self):
- """openai.BadRequestError -> InvalidRequestError."""
- exc = _make_openai_error(openai.BadRequestError, status_code=400)
- result = map_error(exc, rate_limiter=_rate_limiter())
- assert isinstance(result, InvalidRequestError)
- assert result.status_code == 400
-
- @pytest.mark.parametrize(
- "message",
- ["Server overloaded", "No capacity available"],
- ids=["overloaded", "capacity"],
- )
- def test_internal_server_error_overloaded(self, message):
- """InternalServerError with overloaded/capacity keywords -> OverloadedError."""
- exc = _make_openai_error(
- openai.InternalServerError, message=message, status_code=500
- )
- result = map_error(exc, rate_limiter=_rate_limiter())
- assert isinstance(result, OverloadedError)
- assert result.status_code == 529
-
- def test_internal_server_error_generic(self):
- """InternalServerError without keywords maps to APIError preserving 5xx."""
- exc = _make_openai_error(
- openai.InternalServerError, message="Unknown error", status_code=500
- )
- result = map_error(exc, rate_limiter=_rate_limiter())
- assert isinstance(result, APIError)
- assert result.status_code == 500
-
- @pytest.mark.parametrize(
- ("status_code", "expect_substr"),
- [
- (500, "provider api request failed"),
- (502, "temporarily unavailable"),
- (503, "temporarily unavailable"),
- (504, "temporarily unavailable"),
- (599, "provider api request failed"),
- ],
- )
- def test_internal_server_error_preserves_5xx_status_for_messaging(
- self, status_code, expect_substr
- ):
- """InternalServerError carrying HTTP 5xx retains status for stable user messaging."""
- exc = _make_openai_error(
- openai.InternalServerError,
- message=f"upstream {status_code}",
- status_code=status_code,
- )
- result = map_error(exc, rate_limiter=_rate_limiter())
- assert isinstance(result, APIError)
- assert result.status_code == status_code
- assert expect_substr in result.message.lower()
-
- def test_generic_api_error(self):
- """openai.APIError -> APIError with original status_code."""
- exc = _make_openai_error(
- openai.APIError, message="Bad gateway", status_code=502
- )
- result = map_error(exc, rate_limiter=_rate_limiter())
- assert isinstance(result, APIError)
-
- def test_statusless_api_error_resource_exhausted_maps_to_overloaded(self):
- """Status-less SDK APIError overload text maps to user-visible overload."""
- exc = _make_statusless_openai_api_error(
- "ResourceExhausted: limit reached while generating response",
- {"error": {"message": "ResourceExhausted: limit reached", "code": 500}},
- )
-
- result = map_error(exc, rate_limiter=_rate_limiter())
-
- assert isinstance(result, OverloadedError)
- assert result.status_code == 529
-
- def test_statusless_api_error_rate_limit_body_blocks_limiter(self):
- """Status-less SDK APIError with 429 body uses scoped reactive limiting."""
- exc = _make_statusless_openai_api_error(
- "stream embedded error",
- {"error": {"message": "too many requests", "code": 429}},
- )
- limiter = MagicMock()
-
- result = map_error(exc, rate_limiter=limiter)
-
- assert isinstance(result, RateLimitError)
- assert result.status_code == 429
- limiter.set_blocked.assert_called_once_with(60)
-
- def test_statusless_api_error_without_transient_marker_maps_to_generic_500(self):
- """Unknown status-less SDK APIError stays generic instead of pretending success."""
- exc = _make_statusless_openai_api_error(
- "stream embedded error",
- {"error": {"message": "unknown provider failure"}},
- )
-
- result = map_error(exc, rate_limiter=_rate_limiter())
-
- assert isinstance(result, APIError)
- assert result.status_code == 500
- assert result.message == "Provider API request failed."
-
- def test_unmapped_exception_passthrough(self):
- """Non-openai exceptions are returned as-is."""
- exc = RuntimeError("unexpected")
- result = map_error(exc, rate_limiter=_rate_limiter())
- assert result is exc
- assert isinstance(result, RuntimeError)
-
- def test_value_error_passthrough(self):
- """ValueError passes through unchanged."""
- exc = ValueError("bad value")
- result = map_error(exc, rate_limiter=_rate_limiter())
- assert result is exc
-
-
-def test_user_facing_message_read_timeout_empty_string():
- """ReadTimeout wrapping TimeoutError should still produce readable text."""
- timeout_exc = ReadTimeout("")
- message = get_user_facing_error_message(timeout_exc, read_timeout_s=60)
- assert message == "Provider request timed out after 60s."
-
-
-def test_append_request_id_suffix():
- """Request id suffix should be appended deterministically."""
- message = append_request_id("Provider request failed.", "req_abc123")
- assert message == "Provider request failed. (request_id=req_abc123)"
-
-
-def test_user_facing_message_bad_request_prefers_mapped_text_over_sdk_string():
- """BadRequestError should map to stable wording even when str(exc) is non-empty."""
- exc = _make_openai_error(
- openai.BadRequestError, message="leaky-upstream-detail", status_code=400
- )
- assert get_user_facing_error_message(exc) == "Invalid request sent to provider."
-
-
-def test_format_user_error_preview_truncates():
- exc = ValueError("x" * 500)
- preview = format_user_error_preview(exc, max_len=20)
- assert len(preview) == 20
- assert preview == "x" * 20
-
-
-def test_user_visible_message_for_mapped_provider_error_405():
- mapped = APIError("ignored", status_code=405, raw_error="")
- msg = user_visible_message_for_mapped_provider_error(
- mapped, provider_name="ACME", read_timeout_s=30.0
- )
- assert "ACME" in msg and "405" in msg
-
-
-def test_openai_bad_request_body_is_user_visible():
- exc = _make_openai_error(
- openai.BadRequestError,
- message="Thinking mode does not support this tool_choice",
- status_code=400,
- )
- mapped = map_error(exc, rate_limiter=_rate_limiter())
- msg = format_provider_error_message(
- mapped,
- extract_provider_error_detail(exc),
- provider_name="NIM",
- read_timeout_s=60.0,
- request_id="req_body",
- )
-
- assert "Upstream provider NIM returned HTTP 400." in msg
- assert "Category: invalid_request_error" in msg
- assert "Thinking mode does not support this tool_choice" in msg
- assert (
- '{"error":{"message":"Thinking mode does not support this tool_choice"}}' in msg
- )
- assert "Request ID: req_body" in msg
-
-
-def test_auth_status_with_model_error_body_is_not_only_check_api_key():
- body = {
- "type": "error",
- "error": {
- "type": "ModelError",
- "message": "Model qwen3.7-max is not supported for format oa-compat",
- },
- }
- exc = openai.AuthenticationError(
- "Unauthorized",
- response=Response(status_code=401, request=Request("POST", "http://test")),
- body=body,
- )
- mapped = map_error(exc, rate_limiter=_rate_limiter())
- msg = format_provider_error_message(
- mapped,
- extract_provider_error_detail(exc),
- provider_name="OPENCODE_GO",
- read_timeout_s=60.0,
- request_id="req_model",
- )
-
- assert "Upstream provider OPENCODE_GO returned HTTP 401." in msg
- assert "Category: ModelError" in msg
- assert "Provider authentication failed. Check API key." in msg
- assert "Model qwen3.7-max is not supported for format oa-compat" in msg
- assert msg != "Provider authentication failed. Check API key."
-
-
-def test_http_status_error_json_body_is_compact_and_visible():
- response = Response(
- status_code=400,
- request=Request("POST", "http://test"),
- json={"error": {"type": "BadRequest", "message": "bad field"}},
- )
- exc = HTTPStatusError("Bad Request", request=response.request, response=response)
- mapped = map_error(exc, rate_limiter=_rate_limiter())
- msg = user_visible_message_for_mapped_provider_error(
- mapped,
- provider_name="LOCAL",
- read_timeout_s=30.0,
- detail=extract_provider_error_detail(exc),
- request_id="req_json",
- )
-
- assert "Upstream provider LOCAL returned HTTP 400." in msg
- assert "Category: BadRequest" in msg
- assert '{"error":{"type":"BadRequest","message":"bad field"}}' in msg
- assert "Request ID: req_json" in msg
-
-
-def test_http_status_error_body_redacts_credentials_but_keeps_context():
- response = Response(
- status_code=400,
- request=Request("POST", "http://test"),
- json={
- "error": {
- "type": "BadRequest",
- "message": "bad field api_key=SECRET authorization: Bearer TOKEN",
- }
- },
- )
- exc = HTTPStatusError("Bad Request", request=response.request, response=response)
-
- detail = extract_provider_error_detail(exc)
-
- assert detail.body_text is not None
- assert "bad field" in detail.body_text
- assert "api_key=<redacted>" in detail.body_text
- assert "authorization: <redacted>" in detail.body_text
- assert "SECRET" not in detail.body_text
- assert "TOKEN" not in detail.body_text
-
-
-def test_empty_http_error_body_is_explicitly_reported():
- response = Response(
- status_code=500,
- request=Request("POST", "http://test"),
- content=b"",
- )
- exc = HTTPStatusError("Server Error", request=response.request, response=response)
- mapped = map_error(exc, rate_limiter=_rate_limiter())
- msg = format_provider_error_message(
- mapped,
- extract_provider_error_detail(exc),
- provider_name="EMPTY",
- read_timeout_s=30.0,
- )
-
- assert "Upstream provider EMPTY returned HTTP 500." in msg
- assert "(empty upstream error body)" in msg
-
-
-def test_connection_error_without_response_includes_sanitized_cause_chain():
- request = Request("POST", "http://test")
- exc = openai.APIConnectionError(request=request)
- exc.__cause__ = ConnectError(
- "connect failed authorization: Bearer SECRET token=ALSO_SECRET",
- request=request,
- )
- mapped = map_error(exc, rate_limiter=_rate_limiter())
- detail = extract_provider_error_detail(exc)
- msg = format_provider_error_message(
- mapped,
- detail,
- provider_name="NIM",
- read_timeout_s=30.0,
- request_id="req_conn",
- )
-
- assert "Provider API request failed." in msg
- assert "Provider exception:" in msg
- assert "Connection error." in msg
- assert "Caused by:" in msg
- assert "ConnectError: connect failed authorization: <redacted>" in msg
- assert "SECRET" not in msg
- assert "Request ID: req_conn" in msg
- assert exception_cause_types(exc) == ("ConnectError",)
-
-
-def test_connection_error_cause_chain_is_capped_for_display():
- request = Request("POST", "http://test")
- exc = openai.APIConnectionError(request=request)
- exc.__cause__ = ConnectError(
- "x" * (PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES + 10),
- request=request,
- )
- detail = extract_provider_error_detail(exc)
-
- assert detail.cause_chain_text is not None
- assert f"truncated after {PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES} bytes" in (
- detail.cause_chain_text
- )
-
-
-def test_attached_provider_error_body_is_capped_for_display():
- response = Response(
- status_code=500,
- request=Request("POST", "http://test"),
- content=b"",
- )
- exc = HTTPStatusError("Server Error", request=response.request, response=response)
- attach_provider_error_body(exc, "x" * (PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES + 10))
- mapped = map_error(exc, rate_limiter=_rate_limiter())
- msg = format_provider_error_message(
- mapped,
- extract_provider_error_detail(exc),
- provider_name="LONG",
- read_timeout_s=30.0,
- )
-
- assert f"truncated after {PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES} bytes" in msg
- assert "x" * 100 in msg
-
-
-def test_streaming_transports_pass_scoped_rate_limiter_to_map_error():
- """Guardrail: streaming adapters must scope reactive 429 handling per provider."""
- root = Path(__file__).resolve().parents[2]
- for path in (
- root
- / "src"
- / "free_claude_code"
- / "providers"
- / "transports"
- / "anthropic_messages"
- / "transport.py",
- root
- / "src"
- / "free_claude_code"
- / "providers"
- / "transports"
- / "openai_chat"
- / "transport.py",
- ):
- text = path.read_text(encoding="utf-8")
- assert "map_error(" in text, str(path)
- assert "rate_limiter=self._rate_limiter" in text, str(path)
diff --git a/tests/providers/test_execution_failure_boundary.py b/tests/providers/test_execution_failure_boundary.py
new file mode 100644
index 00000000..acb6ccaa
--- /dev/null
+++ b/tests/providers/test_execution_failure_boundary.py
@@ -0,0 +1,233 @@
+"""Provider streams raise canonical failures after closing committed blocks."""
+
+from collections import deque
+from collections.abc import AsyncIterator
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from free_claude_code.config.nim import NimSettings
+from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
+from free_claude_code.providers.base import ProviderConfig
+from free_claude_code.providers.nvidia_nim import NvidiaNimProvider
+from free_claude_code.providers.transports.http import close_provider_stream
+from tests.providers.request_factory import make_messages_request
+from tests.providers.support import passthrough_rate_limiter
+
+
+class _FailingStream:
+ def __init__(
+ self,
+ chunks: list[object],
+ error: Exception | None,
+ *,
+ close_error: Exception | None = None,
+ ) -> None:
+ self._chunks = chunks
+ self._error = error
+ self._close_error = close_error
+ self.close_calls = 0
+
+ def __aiter__(self) -> AsyncIterator[object]:
+ return self._iterate()
+
+ async def _iterate(self) -> AsyncIterator[object]:
+ for chunk in self._chunks:
+ yield chunk
+ if self._error is not None:
+ raise self._error
+
+ async def aclose(self) -> None:
+ self.close_calls += 1
+ if self._close_error is not None:
+ raise self._close_error
+
+
+def _chunk(*, content: str | None = None, finish_reason: str | None = None) -> object:
+ delta = MagicMock(content=content, tool_calls=None, reasoning_content=None)
+ choice = MagicMock(delta=delta, finish_reason=finish_reason)
+ return MagicMock(choices=[choice], usage=None)
+
+
+def _provider() -> NvidiaNimProvider:
+ return NvidiaNimProvider(
+ ProviderConfig(
+ api_key="test_key",
+ base_url="https://test.api.nvidia.com/v1",
+ rate_limit=10,
+ rate_window=60,
+ ),
+ nim_settings=NimSettings(),
+ rate_limiter=passthrough_rate_limiter(),
+ )
+
+
+async def test_committed_provider_failure_closes_block_then_raises_canonical_value() -> (
+ None
+):
+ provider = _provider()
+ request = make_messages_request(
+ "test-model",
+ messages=[],
+ max_tokens=32,
+ )
+ # Crossing the recovery buffer's byte threshold makes the content block
+ # downstream-visible before the failure, so its close prelude must escape.
+ stream = _FailingStream(
+ [_chunk(content="x" * 65_536)],
+ RuntimeError("connection lost after commit"),
+ )
+ emitted: deque[str] = deque()
+
+ with (
+ patch.object(
+ provider._client.chat.completions,
+ "create",
+ new_callable=AsyncMock,
+ return_value=stream,
+ ),
+ pytest.raises(ExecutionFailure) as exc_info,
+ ):
+ async for event in provider.stream_response(
+ request,
+ request_id="req_committed_failure",
+ ):
+ emitted.append(event)
+
+ events = parse_sse_text("".join(emitted))
+ assert [event.event for event in events][-1] == "content_block_stop"
+ assert not any(event.event in {"error", "message_stop"} for event in events)
+ assert exc_info.value.kind is FailureKind.UPSTREAM
+ assert exc_info.value.status_code == 502
+ assert exc_info.value.retryable is False
+ assert "connection lost after commit" in exc_info.value.message
+ assert "Request ID: req_committed_failure" in exc_info.value.message
+
+
+async def test_openai_stream_close_failure_cannot_mask_execution_failure() -> None:
+ provider = _provider()
+ request = make_messages_request(
+ "test-model",
+ messages=[],
+ max_tokens=32,
+ )
+ stream = _FailingStream(
+ [],
+ RuntimeError("original provider failure"),
+ close_error=RuntimeError("cleanup api_key=SECRET"),
+ )
+
+ with (
+ patch.object(
+ provider._client.chat.completions,
+ "create",
+ new_callable=AsyncMock,
+ return_value=stream,
+ ),
+ patch("free_claude_code.providers.transports.http.trace_event") as trace_event,
+ pytest.raises(ExecutionFailure) as exc_info,
+ ):
+ [
+ event
+ async for event in provider.stream_response(
+ request,
+ request_id="req_close_failure",
+ )
+ ]
+
+ assert stream.close_calls == 1
+ assert exc_info.value.status_code == 502
+ assert "original provider failure" in exc_info.value.message
+ assert "cleanup" not in exc_info.value.message
+ assert "SECRET" not in exc_info.value.message
+ trace_event.assert_called_once_with(
+ stage="provider",
+ event="provider.stream.close_failed",
+ source="provider",
+ provider="NIM",
+ request_id="req_close_failure",
+ close_exc_type="RuntimeError",
+ preserved_exc_type="ExecutionFailure",
+ )
+ assert "SECRET" not in repr(trace_event.call_args)
+
+
+async def test_stream_close_failure_without_active_error_is_observability_only() -> (
+ None
+):
+ stream = _FailingStream(
+ [],
+ RuntimeError("unused"),
+ close_error=RuntimeError("normal close failed"),
+ )
+
+ with patch("free_claude_code.providers.transports.http.trace_event") as trace_event:
+ await close_provider_stream(
+ stream,
+ active_error=None,
+ provider_name="TEST",
+ request_id="req_normal_close",
+ )
+
+ assert stream.close_calls == 1
+ trace_event.assert_called_once_with(
+ stage="provider",
+ event="provider.stream.close_failed",
+ source="provider",
+ provider="TEST",
+ request_id="req_normal_close",
+ close_exc_type="RuntimeError",
+ preserved_exc_type=None,
+ )
+
+
+async def test_completed_stream_close_failure_preserves_success_lifecycle() -> None:
+ provider = _provider()
+ request = make_messages_request(
+ "test-model",
+ messages=[],
+ max_tokens=32,
+ )
+ stream = _FailingStream(
+ [_chunk(content="complete", finish_reason="stop")],
+ None,
+ close_error=RuntimeError("cleanup api_key=SECRET"),
+ )
+
+ with (
+ patch.object(
+ provider._client.chat.completions,
+ "create",
+ new_callable=AsyncMock,
+ return_value=stream,
+ ),
+ patch("free_claude_code.providers.transports.http.trace_event") as trace_event,
+ ):
+ emitted = [
+ event
+ async for event in provider.stream_response(
+ request,
+ request_id="req_successful_close_failure",
+ )
+ ]
+
+ events = parse_sse_text("".join(emitted))
+ assert events[-1].event == "message_stop"
+ assert sum(event.event == "message_stop" for event in events) == 1
+ assert not any(event.event == "error" for event in events)
+ assert stream.close_calls == 1
+ trace_event.assert_called_once_with(
+ stage="provider",
+ event="provider.stream.close_failed",
+ source="provider",
+ provider="NIM",
+ request_id="req_successful_close_failure",
+ close_exc_type="RuntimeError",
+ preserved_exc_type=None,
+ )
+ assert "SECRET" not in repr(trace_event.call_args)
diff --git a/tests/providers/test_failure_policy.py b/tests/providers/test_failure_policy.py
new file mode 100644
index 00000000..10e8d788
--- /dev/null
+++ b/tests/providers/test_failure_policy.py
@@ -0,0 +1,375 @@
+"""Raw provider failure classification into the canonical neutral model."""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from unittest.mock import Mock
+
+import httpx
+import openai
+import pytest
+
+from free_claude_code.core.diagnostics import (
+ ERROR_DETAIL_DISPLAY_CAP_BYTES,
+ attach_upstream_error_body,
+)
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
+from free_claude_code.providers.failure_policy import classify_provider_failure
+
+
+def _openai_status_error(
+ error_type: type[openai.APIStatusError],
+ *,
+ status_code: int,
+ message: str,
+ body: object | None = None,
+) -> openai.APIStatusError:
+ request = httpx.Request("POST", "https://provider.test/v1/chat/completions")
+ response = httpx.Response(status_code, request=request)
+ return error_type(
+ message,
+ response=response,
+ body=body or {"error": {"message": message}},
+ )
+
+
+def _statusless_openai_error(message: str, body: object | None) -> openai.APIError:
+ return openai.APIError(
+ message,
+ request=httpx.Request("POST", "https://provider.test/v1/chat/completions"),
+ body=body,
+ )
+
+
+def _http_status_error(status_code: int, message: str) -> httpx.HTTPStatusError:
+ request = httpx.Request("POST", "https://provider.test/v1/messages")
+ response = httpx.Response(
+ status_code,
+ request=request,
+ json={"error": {"message": message, "api_key": "SECRET"}},
+ )
+ return httpx.HTTPStatusError(message, request=request, response=response)
+
+
+@dataclass(frozen=True, slots=True)
+class _ClassificationCase:
+ name: str
+ error: Callable[[], Exception]
+ kind: FailureKind
+ status_code: int
+ retryable: bool
+ rate_limit_block_seconds: int | None = None
+
+
+_CASES = (
+ _ClassificationCase(
+ "openai_authentication",
+ lambda: _openai_status_error(
+ openai.AuthenticationError,
+ status_code=401,
+ message="Unauthorized",
+ ),
+ FailureKind.AUTHENTICATION,
+ 401,
+ False,
+ ),
+ _ClassificationCase(
+ "openai_rate_limit",
+ lambda: _openai_status_error(
+ openai.RateLimitError,
+ status_code=429,
+ message="Too many requests",
+ ),
+ FailureKind.RATE_LIMIT,
+ 429,
+ True,
+ 60,
+ ),
+ _ClassificationCase(
+ "openai_bad_request",
+ lambda: _openai_status_error(
+ openai.BadRequestError,
+ status_code=400,
+ message="bad tool shape",
+ ),
+ FailureKind.INVALID_REQUEST,
+ 400,
+ False,
+ ),
+ _ClassificationCase(
+ "openai_overload_marker",
+ lambda: _openai_status_error(
+ openai.InternalServerError,
+ status_code=500,
+ message="No capacity available",
+ ),
+ FailureKind.OVERLOADED,
+ 529,
+ True,
+ ),
+ _ClassificationCase(
+ "openai_generic_503_preserved",
+ lambda: _openai_status_error(
+ openai.InternalServerError,
+ status_code=503,
+ message="generic server failure",
+ ),
+ FailureKind.UPSTREAM,
+ 503,
+ True,
+ ),
+ _ClassificationCase(
+ "statusless_openai_rate_limit_body",
+ lambda: _statusless_openai_error(
+ "stream embedded error",
+ {"error": {"message": "too many requests", "code": 429}},
+ ),
+ FailureKind.RATE_LIMIT,
+ 429,
+ True,
+ 60,
+ ),
+ _ClassificationCase(
+ "statusless_openai_overload_body",
+ lambda: _statusless_openai_error(
+ "ResourceExhausted: limit reached",
+ {"error": {"message": "ResourceExhausted: limit reached"}},
+ ),
+ FailureKind.OVERLOADED,
+ 529,
+ True,
+ ),
+ _ClassificationCase(
+ "statusless_openai_unknown_is_not_retryable",
+ lambda: _statusless_openai_error(
+ "stream embedded error",
+ {"error": {"message": "unknown provider failure"}},
+ ),
+ FailureKind.UPSTREAM,
+ 500,
+ False,
+ ),
+ _ClassificationCase(
+ "http_403_keeps_authentication_quirk",
+ lambda: _http_status_error(403, "Forbidden"),
+ FailureKind.AUTHENTICATION,
+ 401,
+ False,
+ ),
+ _ClassificationCase(
+ "http_502_keeps_overload_quirk",
+ lambda: _http_status_error(502, "Bad gateway"),
+ FailureKind.OVERLOADED,
+ 529,
+ True,
+ ),
+ _ClassificationCase(
+ "http_599_preserves_status",
+ lambda: _http_status_error(599, "Upstream failure"),
+ FailureKind.UPSTREAM,
+ 599,
+ True,
+ ),
+ _ClassificationCase(
+ "http_405_is_not_retryable",
+ lambda: _http_status_error(405, "Wrong endpoint"),
+ FailureKind.UPSTREAM,
+ 405,
+ False,
+ ),
+ _ClassificationCase(
+ "read_timeout_keeps_pre_start_status",
+ lambda: httpx.ReadTimeout(
+ "",
+ request=httpx.Request("POST", "https://provider.test/v1/messages"),
+ ),
+ FailureKind.TIMEOUT,
+ 502,
+ True,
+ ),
+ _ClassificationCase(
+ "openai_connection_error_keeps_status",
+ lambda: openai.APIConnectionError(
+ request=httpx.Request("POST", "https://provider.test/v1/chat/completions")
+ ),
+ FailureKind.UNAVAILABLE,
+ 500,
+ True,
+ ),
+ _ClassificationCase(
+ "unknown_exception_keeps_gateway_status",
+ lambda: RuntimeError("unexpected provider failure"),
+ FailureKind.UPSTREAM,
+ 502,
+ False,
+ ),
+)
+
+
[email protected]("case", _CASES, ids=lambda case: case.name)
+def test_raw_provider_failure_maps_to_canonical_failure(
+ case: _ClassificationCase,
+) -> None:
+ mark_rate_limited = Mock()
+
+ failure = classify_provider_failure(
+ case.error(),
+ provider_name="TEST_PROVIDER",
+ read_timeout_s=30.0,
+ request_id="req_classification",
+ mark_rate_limited=mark_rate_limited,
+ )
+
+ assert isinstance(failure, ExecutionFailure)
+ assert failure.kind is case.kind
+ assert failure.status_code == case.status_code
+ assert failure.retryable is case.retryable
+ assert failure.message.strip()
+ assert "Request ID: req_classification" in failure.message
+ assert "SECRET" not in failure.message
+ if case.rate_limit_block_seconds is None:
+ mark_rate_limited.assert_not_called()
+ else:
+ mark_rate_limited.assert_called_once_with(case.rate_limit_block_seconds)
+
+
+def test_classification_preserves_useful_body_while_redacting_credentials() -> None:
+ error = _http_status_error(
+ 400,
+ "unsupported model format authorization: Bearer AUTH_SECRET",
+ )
+
+ failure = classify_provider_failure(
+ error,
+ provider_name="LOCAL",
+ read_timeout_s=60.0,
+ request_id="req_body",
+ mark_rate_limited=Mock(),
+ )
+
+ assert failure.kind is FailureKind.INVALID_REQUEST
+ assert failure.status_code == 400
+ assert "Upstream provider LOCAL returned HTTP 400." in failure.message
+ assert "unsupported model format" in failure.message
+ assert "Request ID: req_body" in failure.message
+ assert "AUTH_SECRET" not in failure.message
+ assert "SECRET" not in failure.message
+
+
+def test_auth_failure_preserves_model_error_body_instead_of_masking_it() -> None:
+ error = _openai_status_error(
+ openai.AuthenticationError,
+ status_code=401,
+ message="Unauthorized",
+ body={
+ "type": "error",
+ "error": {
+ "type": "ModelError",
+ "message": ("Model qwen3.7-max is not supported for format oa-compat"),
+ },
+ },
+ )
+
+ failure = classify_provider_failure(
+ error,
+ provider_name="OPENCODE_GO",
+ read_timeout_s=60.0,
+ request_id="req_model",
+ mark_rate_limited=Mock(),
+ )
+
+ assert failure.kind is FailureKind.AUTHENTICATION
+ assert failure.status_code == 401
+ assert "Category: ModelError" in failure.message
+ assert "Provider authentication failed. Check API key." in failure.message
+ assert "Model qwen3.7-max is not supported for format oa-compat" in failure.message
+ assert "Request ID: req_model" in failure.message
+
+
+def test_empty_http_error_body_is_reported_explicitly() -> None:
+ request = httpx.Request("POST", "https://provider.test/v1/messages")
+ response = httpx.Response(500, request=request, content=b"")
+ error = httpx.HTTPStatusError(
+ "Server Error",
+ request=request,
+ response=response,
+ )
+
+ failure = classify_provider_failure(
+ error,
+ provider_name="EMPTY",
+ read_timeout_s=30.0,
+ request_id="req_empty",
+ mark_rate_limited=Mock(),
+ )
+
+ assert failure.kind is FailureKind.UPSTREAM
+ assert failure.status_code == 500
+ assert "Upstream provider EMPTY returned HTTP 500." in failure.message
+ assert "(empty upstream error body)" in failure.message
+
+
+def test_http_405_diagnostic_names_rejected_upstream_endpoint() -> None:
+ failure = classify_provider_failure(
+ _http_status_error(405, "Method Not Allowed"),
+ provider_name="LOCAL",
+ read_timeout_s=30.0,
+ request_id="req_405",
+ mark_rate_limited=Mock(),
+ )
+
+ assert failure.kind is FailureKind.UPSTREAM
+ assert failure.status_code == 405
+ assert (
+ "Upstream provider LOCAL rejected the request method or endpoint (HTTP 405)."
+ in failure.message
+ )
+ assert "Request ID: req_405" in failure.message
+
+
+def test_connection_cause_chain_is_redacted_and_capped() -> None:
+ request = httpx.Request("POST", "https://provider.test/v1/chat/completions")
+ error = openai.APIConnectionError(request=request)
+ error.__cause__ = httpx.ConnectError(
+ "connect failed authorization: Bearer CAUSE_SECRET "
+ + "x" * (ERROR_DETAIL_DISPLAY_CAP_BYTES + 10),
+ request=request,
+ )
+
+ failure = classify_provider_failure(
+ error,
+ provider_name="NIM",
+ read_timeout_s=30.0,
+ request_id="req_cause",
+ mark_rate_limited=Mock(),
+ )
+
+ assert "Caused by:" in failure.message
+ assert "ConnectError: connect failed authorization: <redacted>" in failure.message
+ assert "CAUSE_SECRET" not in failure.message
+ assert f"truncated after {ERROR_DETAIL_DISPLAY_CAP_BYTES} bytes" in failure.message
+ assert "Request ID: req_cause" in failure.message
+
+
+def test_attached_streamed_error_body_remains_bounded() -> None:
+ request = httpx.Request("POST", "https://provider.test/v1/messages")
+ response = httpx.Response(500, request=request, content=b"")
+ error = httpx.HTTPStatusError(
+ "Server Error",
+ request=request,
+ response=response,
+ )
+ attach_upstream_error_body(
+ error,
+ "x" * (ERROR_DETAIL_DISPLAY_CAP_BYTES + 10),
+ )
+
+ failure = classify_provider_failure(
+ error,
+ provider_name="LONG",
+ read_timeout_s=30.0,
+ request_id="req_long",
+ mark_rate_limited=Mock(),
+ )
+
+ assert f"truncated after {ERROR_DETAIL_DISPLAY_CAP_BYTES} bytes" in failure.message
+ assert "x" * 100 in failure.message
diff --git a/tests/providers/test_fireworks.py b/tests/providers/test_fireworks.py
index ee02b0d1..39a6f72f 100644
--- a/tests/providers/test_fireworks.py
+++ b/tests/providers/test_fireworks.py
@@ -4,10 +4,10 @@ from unittest.mock import AsyncMock, MagicMock
import pytest
+from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
from free_claude_code.core.anthropic.models import Message, MessagesRequest
from free_claude_code.providers.base import ProviderConfig
-from free_claude_code.providers.exceptions import InvalidRequestError
from free_claude_code.providers.fireworks import FIREWORKS_BASE_URL, FireworksProvider
from free_claude_code.providers.transports.openai_chat import OpenAIChatTransport
from tests.providers.support import passthrough_rate_limiter
diff --git a/tests/providers/test_github_models.py b/tests/providers/test_github_models.py
index 908475b4..820555ff 100644
--- a/tests/providers/test_github_models.py
+++ b/tests/providers/test_github_models.py
@@ -10,12 +10,12 @@ import pytest
from free_claude_code.core.anthropic.models import Message, MessagesRequest
from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
from free_claude_code.providers.base import ProviderConfig
-from free_claude_code.providers.exceptions import ModelListResponseError
from free_claude_code.providers.github_models import (
GITHUB_MODELS_DEFAULT_BASE,
GitHubModelsProvider,
)
from free_claude_code.providers.github_models.client import GITHUB_MODELS_CATALOG_URL
+from free_claude_code.providers.model_listing import ModelListResponseError
from tests.providers.support import passthrough_rate_limiter
diff --git a/tests/providers/test_kimi.py b/tests/providers/test_kimi.py
index 16a040e5..dbd7c857 100644
--- a/tests/providers/test_kimi.py
+++ b/tests/providers/test_kimi.py
@@ -5,11 +5,11 @@ from unittest.mock import AsyncMock, MagicMock
import pytest
+from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
from free_claude_code.core.anthropic.models import Message, MessagesRequest
from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.defaults import KIMI_DEFAULT_BASE
-from free_claude_code.providers.exceptions import InvalidRequestError
from free_claude_code.providers.kimi import KimiProvider
from free_claude_code.providers.transports.openai_chat import OpenAIChatTransport
from tests.providers.support import passthrough_rate_limiter
diff --git a/tests/providers/test_llamacpp.py b/tests/providers/test_llamacpp.py
index efc73e91..e9d37132 100644
--- a/tests/providers/test_llamacpp.py
+++ b/tests/providers/test_llamacpp.py
@@ -7,8 +7,8 @@ import pytest
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
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.base import ProviderConfig
-from free_claude_code.providers.exceptions import ProviderError
from free_claude_code.providers.llamacpp import LlamaCppProvider
from tests.providers.request_factory import make_messages_request
from tests.providers.support import passthrough_rate_limiter
@@ -214,7 +214,7 @@ async def test_stream_error_status_code(llamacpp_provider):
return_value=mock_response,
),
):
- with pytest.raises(ProviderError) as exc_info:
+ with pytest.raises(ExecutionFailure) as exc_info:
[
e
async for e in llamacpp_provider.stream_response(
@@ -242,7 +242,7 @@ async def test_stream_network_error(llamacpp_provider):
side_effect=httpx.ConnectError("Connection refused"),
),
):
- with pytest.raises(ProviderError) as exc_info:
+ with pytest.raises(ExecutionFailure) as exc_info:
[
e
async for e in llamacpp_provider.stream_response(
@@ -279,7 +279,7 @@ async def test_stream_error_405_mentions_upstream_provider(llamacpp_provider):
new_callable=AsyncMock,
return_value=mock_response,
),
- pytest.raises(ProviderError) as exc_info,
+ pytest.raises(ExecutionFailure) as exc_info,
):
[e async for e in llamacpp_provider.stream_response(req, request_id="REQ405")]
diff --git a/tests/providers/test_lmstudio.py b/tests/providers/test_lmstudio.py
index 2cef3a0c..46f1e838 100644
--- a/tests/providers/test_lmstudio.py
+++ b/tests/providers/test_lmstudio.py
@@ -5,8 +5,8 @@ from unittest.mock import AsyncMock, MagicMock, patch
import httpx
import pytest
+from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.providers.base import ProviderConfig
-from free_claude_code.providers.exceptions import InvalidRequestError
from free_claude_code.providers.lmstudio import LMStudioProvider
from free_claude_code.providers.lmstudio.client import LMSTUDIO_DEFAULT_BASE
from tests.providers.request_factory import make_messages_request
diff --git a/tests/providers/test_mistral.py b/tests/providers/test_mistral.py
index 2be75f83..71df87bc 100644
--- a/tests/providers/test_mistral.py
+++ b/tests/providers/test_mistral.py
@@ -7,8 +7,8 @@ import openai
import pytest
from httpx import Request, Response
+from free_claude_code.core.failures import ExecutionFailure
from free_claude_code.providers.base import ProviderConfig
-from free_claude_code.providers.exceptions import ProviderError
from free_claude_code.providers.mistral import MISTRAL_DEFAULT_BASE, MistralProvider
from tests.providers.request_factory import make_messages_request
from tests.providers.support import passthrough_rate_limiter
@@ -702,7 +702,7 @@ async def test_stream_response_unrelated_bad_request_does_not_retry(mistral_prov
) as mock_create:
mock_create.side_effect = error
- with pytest.raises(ProviderError) as exc_info:
+ with pytest.raises(ExecutionFailure) as exc_info:
[e async for e in mistral_provider.stream_response(req)]
assert mock_create.await_count == 1
@@ -721,7 +721,7 @@ async def test_stream_response_generic_thinking_error_does_not_retry(
) as mock_create:
mock_create.side_effect = error
- with pytest.raises(ProviderError) as exc_info:
+ with pytest.raises(ExecutionFailure) as exc_info:
[e async for e in mistral_provider.stream_response(req)]
assert mock_create.await_count == 1
diff --git a/tests/providers/test_model_validation.py b/tests/providers/test_model_validation.py
index ea33d971..1a195eab 100644
--- a/tests/providers/test_model_validation.py
+++ b/tests/providers/test_model_validation.py
@@ -7,16 +7,14 @@ from unittest.mock import AsyncMock, patch
import httpx
import pytest
+from free_claude_code.application.errors import ApplicationUnavailableError
from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.nim import NimSettings
from free_claude_code.config.settings import Settings
from free_claude_code.providers.base import BaseProvider, ProviderConfig
from free_claude_code.providers.deepseek import DeepSeekProvider
-from free_claude_code.providers.exceptions import (
- ModelListResponseError,
- ServiceUnavailableError,
-)
from free_claude_code.providers.llamacpp import LlamaCppProvider
+from free_claude_code.providers.model_listing import ModelListResponseError
from free_claude_code.providers.nvidia_nim import NvidiaNimProvider
from free_claude_code.providers.ollama import OllamaProvider
from free_claude_code.providers.open_router import OpenRouterProvider
@@ -406,7 +404,7 @@ async def test_runtime_validation_reports_missing_model_with_sources() -> None:
{"nvidia_nim": FakeProvider(frozenset({"different-model"}))},
)
- with pytest.raises(ServiceUnavailableError) as exc_info:
+ with pytest.raises(ApplicationUnavailableError) as exc_info:
await runtime.validate_configured_models()
message = exc_info.value.message
@@ -429,7 +427,7 @@ async def test_runtime_validation_aggregates_multiple_failures() -> None:
},
)
- with pytest.raises(ServiceUnavailableError) as exc_info:
+ with pytest.raises(ApplicationUnavailableError) as exc_info:
await runtime.validate_configured_models()
message = exc_info.value.message
diff --git a/tests/providers/test_nvidia_nim.py b/tests/providers/test_nvidia_nim.py
index 79b24a62..63dec163 100644
--- a/tests/providers/test_nvidia_nim.py
+++ b/tests/providers/test_nvidia_nim.py
@@ -6,8 +6,8 @@ import pytest
from httpx import Request, Response
from free_claude_code.config.nim import NimSettings
+from free_claude_code.core.failures import ExecutionFailure
from free_claude_code.providers.defaults import NVIDIA_NIM_DEFAULT_BASE
-from free_claude_code.providers.exceptions import ProviderError
from free_claude_code.providers.nvidia_nim import NvidiaNimProvider
from free_claude_code.providers.nvidia_nim.tool_schema import (
NIM_TOOL_ARGUMENT_ALIASES_KEY,
@@ -494,7 +494,7 @@ async def test_stream_response_does_not_retry_unrelated_bad_request(provider_con
) as mock_create:
mock_create.side_effect = _make_bad_request_error("unrelated bad request")
- with pytest.raises(ProviderError) as exc_info:
+ with pytest.raises(ExecutionFailure) as exc_info:
[e async for e in provider.stream_response(req)]
assert mock_create.await_count == 1
@@ -885,7 +885,7 @@ async def test_stream_response_bad_request_without_reasoning_budget_does_not_ret
) as mock_create:
mock_create.side_effect = error
- with pytest.raises(ProviderError) as exc_info:
+ with pytest.raises(ExecutionFailure) as exc_info:
[e async for e in nim_provider.stream_response(req)]
assert mock_create.await_count == 1
@@ -904,7 +904,7 @@ async def test_stream_response_unrelated_internal_error_does_not_downgrade(
) as mock_create:
mock_create.side_effect = error
- with pytest.raises(ProviderError) as exc_info:
+ with pytest.raises(ExecutionFailure) as exc_info:
[e async for e in nim_provider.stream_response(req)]
assert mock_create.await_count == 1
@@ -925,7 +925,7 @@ async def test_stream_response_internal_reasoning_content_error_does_not_downgra
) as mock_create:
mock_create.side_effect = error
- with pytest.raises(ProviderError) as exc_info:
+ with pytest.raises(ExecutionFailure) as exc_info:
[e async for e in nim_provider.stream_response(req)]
assert mock_create.await_count == 1
diff --git a/tests/providers/test_ollama.py b/tests/providers/test_ollama.py
index 469f36aa..559b0c9b 100644
--- a/tests/providers/test_ollama.py
+++ b/tests/providers/test_ollama.py
@@ -6,8 +6,8 @@ import httpx
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.base import ProviderConfig
-from free_claude_code.providers.exceptions import ProviderError
from free_claude_code.providers.ollama import OLLAMA_DEFAULT_BASE, OllamaProvider
from tests.providers.request_factory import make_messages_request
from tests.providers.support import passthrough_rate_limiter
@@ -207,7 +207,7 @@ async def test_stream_error_status_code(ollama_provider):
new_callable=AsyncMock,
return_value=mock_response,
),
- pytest.raises(ProviderError) as exc_info,
+ pytest.raises(ExecutionFailure) as exc_info,
):
[
event
diff --git a/tests/providers/test_open_router.py b/tests/providers/test_open_router.py
index 4f378205..bc2b16ca 100644
--- a/tests/providers/test_open_router.py
+++ b/tests/providers/test_open_router.py
@@ -5,6 +5,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
import pytest
+from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.anthropic.stream_contracts import (
@@ -12,7 +13,6 @@ from free_claude_code.core.anthropic.stream_contracts import (
text_content,
)
from free_claude_code.providers.base import ProviderConfig
-from free_claude_code.providers.exceptions import InvalidRequestError
from free_claude_code.providers.open_router import OpenRouterProvider
from free_claude_code.providers.transports.openai_chat import OpenAIChatTransport
from tests.providers.request_factory import make_messages_request
diff --git a/tests/providers/test_openai_compat_5xx_retry.py b/tests/providers/test_openai_compat_5xx_retry.py
index 4053b363..75a713d0 100644
--- a/tests/providers/test_openai_compat_5xx_retry.py
+++ b/tests/providers/test_openai_compat_5xx_retry.py
@@ -8,8 +8,8 @@ import pytest
from httpx import Request, Response
from free_claude_code.config.nim import NimSettings
+from free_claude_code.core.failures import ExecutionFailure
from free_claude_code.providers.base import ProviderConfig
-from free_claude_code.providers.exceptions import ProviderError
from free_claude_code.providers.nvidia_nim import NvidiaNimProvider
from tests.providers.request_factory import make_messages_request
from tests.providers.support import retrying_rate_limiter
@@ -152,7 +152,7 @@ async def test_nim_stream_connection_error_exhausted_emits_cause_chain():
patch(
"free_claude_code.providers.transports.openai_chat.stream.trace_event"
) as trace,
- pytest.raises(ProviderError) as exc_info,
+ pytest.raises(ExecutionFailure) as exc_info,
):
[e async for e in provider.stream_response(req, request_id="req_conn")]
@@ -207,7 +207,7 @@ async def test_nim_stream_openai_5xx_exhausted_emits_user_message(
patch("asyncio.sleep", new_callable=AsyncMock),
):
mock_create.side_effect = _internal_5xx(status_code)
- with pytest.raises(ProviderError) as exc_info:
+ with pytest.raises(ExecutionFailure) as exc_info:
[e async for e in provider.stream_response(req)]
assert mock_create.await_count == 5
diff --git a/tests/providers/test_provider_rate_limit.py b/tests/providers/test_provider_rate_limit.py
index caa7fcb0..f59ecf5b 100644
--- a/tests/providers/test_provider_rate_limit.py
+++ b/tests/providers/test_provider_rate_limit.py
@@ -7,12 +7,14 @@ import openai
import pytest
from httpx import Request
+from free_claude_code.providers.failure_policy import (
+ retryable_upstream_status,
+ retryable_upstream_transport_error,
+)
from free_claude_code.providers.rate_limit import (
DEFAULT_UPSTREAM_MAX_RETRIES,
UPSTREAM_TRANSIENT_TOTAL_ATTEMPTS,
ProviderRateLimiter,
- retryable_upstream_status,
- retryable_upstream_transport_error,
)
diff --git a/tests/providers/test_provider_runtime.py b/tests/providers/test_provider_runtime.py
index 6e78e13f..b0c9a89d 100644
--- a/tests/providers/test_provider_runtime.py
+++ b/tests/providers/test_provider_runtime.py
@@ -5,6 +5,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
import pytest
+from free_claude_code.application.errors import UnknownProviderError
from free_claude_code.config.nim import NimSettings
from free_claude_code.config.provider_catalog import (
COHERE_DEFAULT_BASE,
@@ -19,7 +20,6 @@ from free_claude_code.providers.cloudflare import CloudflareProvider
from free_claude_code.providers.codestral import CodestralProvider
from free_claude_code.providers.cohere import CohereProvider
from free_claude_code.providers.deepseek import DeepSeekProvider
-from free_claude_code.providers.exceptions import UnknownProviderTypeError
from free_claude_code.providers.fireworks import FireworksProvider
from free_claude_code.providers.gemini import GeminiProvider
from free_claude_code.providers.github_models import GitHubModelsProvider
@@ -460,7 +460,7 @@ def test_different_providers_in_one_runtime_have_independent_limiters() -> None:
def test_unknown_provider_raises_unknown_provider_type_error():
- with pytest.raises(UnknownProviderTypeError, match="Unknown provider_type"):
+ with pytest.raises(UnknownProviderError, match="Unknown provider_type"):
create_provider("unknown", _make_settings())
diff --git a/tests/providers/test_provider_transport_logging.py b/tests/providers/test_provider_transport_logging.py
index 1f1f3165..1a0a949c 100644
--- a/tests/providers/test_provider_transport_logging.py
+++ b/tests/providers/test_provider_transport_logging.py
@@ -10,8 +10,8 @@ import pytest
from free_claude_code.config.constants import NATIVE_MESSAGES_ERROR_BODY_LOG_CAP_BYTES
from free_claude_code.config.nim import NimSettings
+from free_claude_code.core.failures import ExecutionFailure
from free_claude_code.providers.base import ProviderConfig
-from free_claude_code.providers.exceptions import ProviderError
from free_claude_code.providers.nvidia_nim import NvidiaNimProvider
from free_claude_code.providers.transports.anthropic_messages import (
stream as native_stream,
@@ -58,7 +58,7 @@ async def test_native_non_200_logs_exclude_body_text_by_default(
return_value=response,
),
caplog.at_level(logging.ERROR),
- pytest.raises(ProviderError),
+ pytest.raises(ExecutionFailure),
):
[e async for e in provider.stream_response(req)]
@@ -76,7 +76,10 @@ async def test_native_non_200_logs_body_when_verbose(caplog, provider_config):
rate_limiter=passthrough_rate_limiter(),
)
req = make_messages_request()
- response = FakeResponse(status_code=500, text="SECRET_UPSTREAM_BODY")
+ response = FakeResponse(
+ status_code=500,
+ text="api_key=SECRET_UPSTREAM_BODY useful native detail",
+ )
with (
patch.object(provider._client, "build_request", return_value=MagicMock()),
@@ -87,12 +90,14 @@ async def test_native_non_200_logs_body_when_verbose(caplog, provider_config):
return_value=response,
),
caplog.at_level(logging.ERROR),
- pytest.raises(ProviderError),
+ pytest.raises(ExecutionFailure),
):
[e async for e in provider.stream_response(req)]
messages = " | ".join(r.getMessage() for r in caplog.records)
- assert "SECRET_UPSTREAM_BODY" in messages
+ assert "api_key=<redacted>" in messages
+ assert "useful native detail" in messages
+ assert "SECRET_UPSTREAM_BODY" not in messages
assert "truncated=False" in messages
@@ -119,7 +124,7 @@ async def test_native_non_200_verbose_logs_only_capped_error_body(
return_value=response,
),
caplog.at_level(logging.ERROR),
- pytest.raises(ProviderError),
+ pytest.raises(ExecutionFailure),
):
[e async for e in provider.stream_response(req)]
@@ -150,7 +155,7 @@ async def test_native_non_200_default_does_not_read_oversized_body(
return_value=response,
),
caplog.at_level(logging.ERROR),
- pytest.raises(ProviderError),
+ pytest.raises(ExecutionFailure),
):
[e async for e in provider.stream_response(req)]
@@ -192,7 +197,7 @@ async def test_native_stream_failure_logs_exclude_exception_str_by_default(
),
patch.object(native_stream, "iter_sse_events", boom),
caplog.at_level(logging.ERROR),
- pytest.raises(ProviderError),
+ pytest.raises(ExecutionFailure),
):
[e async for e in provider.stream_response(req)]
@@ -202,6 +207,51 @@ async def test_native_stream_failure_logs_exclude_exception_str_by_default(
assert "http_status=None" in messages
+async def test_native_stream_failure_verbose_traceback_redacts_credentials(
+ caplog, provider_config
+):
+ provider_config.log_api_error_tracebacks = True
+ provider = NativeProvider(
+ provider_config,
+ rate_limiter=passthrough_rate_limiter(),
+ )
+ req = make_messages_request()
+ response = FakeResponse(
+ lines=[
+ "event: ping",
+ '{"type":"ping"}',
+ "",
+ ]
+ )
+
+ async def boom(_response):
+ raise RuntimeError(
+ "authorization: Bearer NATIVE_TRACE_SECRET useful traceback detail"
+ )
+ if False:
+ yield ""
+
+ with (
+ patch.object(provider._client, "build_request", return_value=MagicMock()),
+ patch.object(
+ provider._client,
+ "send",
+ new_callable=AsyncMock,
+ return_value=response,
+ ),
+ patch.object(native_stream, "iter_sse_events", boom),
+ caplog.at_level(logging.ERROR),
+ pytest.raises(ExecutionFailure),
+ ):
+ [e async for e in provider.stream_response(req)]
+
+ messages = " | ".join(r.getMessage() for r in caplog.records)
+ assert "authorization: <redacted>" in messages
+ assert "useful traceback detail" in messages
+ assert "NATIVE_TRACE_SECRET" not in messages
+
+
@pytest.mark.asyncio
async def test_openai_compat_stream_failure_default_logs_exclude_exception_str(caplog):
config = ProviderConfig(
@@ -231,7 +281,7 @@ async def test_openai_compat_stream_failure_default_logs_exclude_exception_str(c
_noop_slot,
),
caplog.at_level(logging.ERROR),
- pytest.raises(ProviderError),
+ pytest.raises(ExecutionFailure),
):
[e async for e in provider.stream_response(req)]
@@ -273,7 +323,7 @@ async def test_openai_compat_stream_failure_default_logs_cause_types_only(caplog
_noop_slot,
),
caplog.at_level(logging.ERROR),
- pytest.raises(ProviderError),
+ pytest.raises(ExecutionFailure),
):
[e async for e in provider.stream_response(req)]
@@ -304,7 +354,9 @@ async def test_openai_compat_stream_failure_respects_verbose_flag(caplog):
provider,
"_create_stream",
new_callable=AsyncMock,
- side_effect=RuntimeError("SECRET_OPENAI_COMPAT"),
+ side_effect=RuntimeError(
+ "api_key=SECRET_OPENAI_COMPAT useful traceback detail"
+ ),
),
patch.object(
provider._rate_limiter,
@@ -312,9 +364,11 @@ async def test_openai_compat_stream_failure_respects_verbose_flag(caplog):
_noop_slot,
),
caplog.at_level(logging.ERROR),
- pytest.raises(ProviderError),
+ pytest.raises(ExecutionFailure),
):
[e async for e in provider.stream_response(req)]
messages = " | ".join(r.getMessage() for r in caplog.records)
- assert "SECRET_OPENAI_COMPAT" in messages
+ assert "api_key=<redacted>" in messages
+ assert "useful traceback detail" in messages
+ assert "SECRET_OPENAI_COMPAT" not in messages
diff --git a/tests/core/anthropic/test_stream_recovery.py b/tests/providers/test_stream_recovery.py
similarity index 65%
rename from tests/core/anthropic/test_stream_recovery.py
rename to tests/providers/test_stream_recovery.py
index 9e9815e8..f0ad6170 100644
--- a/tests/core/anthropic/test_stream_recovery.py
+++ b/tests/providers/test_stream_recovery.py
@@ -1,18 +1,15 @@
-"""Unit tests for resilient stream recovery helpers."""
+"""Provider-owned stream retry and holdback policy."""
import httpx
import openai
-from free_claude_code.core.anthropic.streaming import (
+from free_claude_code.providers.stream_recovery import (
EARLY_TRANSPARENT_MAX_RETRIES,
EARLY_TRANSPARENT_TOTAL_ATTEMPTS,
MIDSTREAM_RECOVERY_ATTEMPTS,
RecoveryController,
RecoveryFailureAction,
RecoveryHoldbackBuffer,
- ToolSchema,
- accept_tool_json_repair,
- continuation_suffix,
is_retryable_stream_error,
)
@@ -52,6 +49,17 @@ def test_retryable_stream_error_classifies_transport_and_http_status() -> None:
)
+def test_stream_retry_preserves_timeout_scope() -> None:
+ request = httpx.Request("POST", "https://provider.test/messages")
+
+ assert is_retryable_stream_error(httpx.ReadTimeout("read", request=request))
+ assert not is_retryable_stream_error(
+ httpx.ConnectTimeout("connect", request=request)
+ )
+ assert not is_retryable_stream_error(httpx.WriteTimeout("write", request=request))
+ assert not is_retryable_stream_error(httpx.PoolTimeout("pool", request=request))
+
+
def test_retryable_stream_error_classifies_statusless_api_error_body_status() -> None:
assert is_retryable_stream_error(
_statusless_openai_api_error(
@@ -90,11 +98,11 @@ def test_retryable_stream_error_does_not_retry_bad_request_status() -> None:
)
-def test_stream_recovery_session_advances_early_retry_and_discards_holdback() -> None:
- session = RecoveryController(provider_name="TEST", request_id="REQ")
+def test_recovery_controller_advances_early_retry_and_discards_holdback() -> None:
+ controller = RecoveryController(provider_name="TEST", request_id="REQ")
- assert session.push("hidden") == []
- decision = session.advance_failure(
+ assert controller.push("hidden") == []
+ decision = controller.advance_failure(
httpx.ReadError("early cutoff"),
stream_opened=True,
generated_output=True,
@@ -103,16 +111,16 @@ def test_stream_recovery_session_advances_early_retry_and_discards_holdback() ->
assert decision.action == RecoveryFailureAction.EARLY_RETRY
assert decision.early_retry_attempt == 1
- assert session.early_retries == 1
- assert not session.committed
- assert not session.has_buffered
- assert session.flush() == []
+ assert controller.early_retries == 1
+ assert not controller.committed
+ assert not controller.has_buffered
+ assert controller.flush() == []
-def test_stream_recovery_session_retries_statusless_transient_api_error() -> None:
- session = RecoveryController(provider_name="TEST", request_id="REQ")
+def test_recovery_controller_retries_statusless_transient_api_error() -> None:
+ controller = RecoveryController(provider_name="TEST", request_id="REQ")
- decision = session.advance_failure(
+ decision = controller.advance_failure(
_statusless_openai_api_error(
"ResourceExhausted: limit reached while generating response",
{"error": {"message": "ResourceExhausted: limit reached"}},
@@ -127,11 +135,11 @@ def test_stream_recovery_session_retries_statusless_transient_api_error() -> Non
assert decision.early_retry_attempt == 1
-def test_stream_recovery_session_respects_early_retry_limit() -> None:
- session = RecoveryController(provider_name="TEST", request_id=None)
+def test_recovery_controller_respects_early_retry_limit() -> None:
+ controller = RecoveryController(provider_name="TEST", request_id=None)
for attempt in range(1, EARLY_TRANSPARENT_MAX_RETRIES + 1):
- decision = session.advance_failure(
+ decision = controller.advance_failure(
httpx.ReadError("cutoff"),
stream_opened=True,
generated_output=False,
@@ -140,7 +148,7 @@ def test_stream_recovery_session_respects_early_retry_limit() -> None:
assert decision.action == RecoveryFailureAction.EARLY_RETRY
assert decision.early_retry_attempt == attempt
- decision = session.advance_failure(
+ decision = controller.advance_failure(
httpx.ReadError("cutoff"),
stream_opened=True,
generated_output=False,
@@ -148,15 +156,15 @@ def test_stream_recovery_session_respects_early_retry_limit() -> None:
)
assert decision.action == RecoveryFailureAction.FINAL_ERROR
- assert session.early_retries == EARLY_TRANSPARENT_MAX_RETRIES
+ assert controller.early_retries == EARLY_TRANSPARENT_MAX_RETRIES
-def test_stream_recovery_session_classifies_midstream_recovery_after_commit() -> None:
- session = RecoveryController(provider_name="TEST", request_id=None)
+def test_recovery_controller_classifies_midstream_recovery_after_commit() -> None:
+ controller = RecoveryController(provider_name="TEST", request_id=None)
- assert session.push("event: content_block_delta\n\n") == []
- assert session.flush() == ["event: content_block_delta\n\n"]
- decision = session.advance_failure(
+ assert controller.push("event: content_block_delta\n\n") == []
+ assert controller.flush() == ["event: content_block_delta\n\n"]
+ decision = controller.advance_failure(
httpx.ReadError("midstream cutoff"),
stream_opened=True,
generated_output=True,
@@ -166,14 +174,14 @@ def test_stream_recovery_session_classifies_midstream_recovery_after_commit() ->
assert decision.action == RecoveryFailureAction.MIDSTREAM_RECOVERY
assert decision.retryable
assert decision.committed
- assert session.flush_uncommitted(decision) == []
+ assert controller.flush_uncommitted(decision) == []
-def test_stream_recovery_session_flushes_uncommitted_midstream_decision() -> None:
- session = RecoveryController(provider_name="TEST", request_id=None)
+def test_recovery_controller_flushes_uncommitted_midstream_decision() -> None:
+ controller = RecoveryController(provider_name="TEST", request_id=None)
- assert session.push("event: content_block_delta\n\n") == []
- decision = session.advance_failure(
+ assert controller.push("event: content_block_delta\n\n") == []
+ decision = controller.advance_failure(
httpx.ReadError("midstream cutoff"),
stream_opened=True,
generated_output=True,
@@ -183,26 +191,26 @@ def test_stream_recovery_session_flushes_uncommitted_midstream_decision() -> Non
assert decision.action == RecoveryFailureAction.MIDSTREAM_RECOVERY
assert not decision.committed
assert decision.has_buffered
- assert not session.committed
- assert session.has_buffered
+ assert not controller.committed
+ assert controller.has_buffered
- assert session.flush_uncommitted(decision) == ["event: content_block_delta\n\n"]
+ assert controller.flush_uncommitted(decision) == ["event: content_block_delta\n\n"]
assert not decision.committed
assert decision.has_buffered
- assert session.committed
- assert not session.has_buffered
+ assert controller.committed
+ assert not controller.has_buffered
-def test_stream_recovery_session_non_retryable_error_is_final() -> None:
+def test_recovery_controller_non_retryable_error_is_final() -> None:
request = httpx.Request("POST", "https://example.test/messages")
error = httpx.HTTPStatusError(
"bad request",
request=request,
response=httpx.Response(400, request=request),
)
- session = RecoveryController(provider_name="TEST", request_id=None)
+ controller = RecoveryController(provider_name="TEST", request_id=None)
- decision = session.advance_failure(
+ decision = controller.advance_failure(
error,
stream_opened=True,
generated_output=True,
@@ -211,47 +219,7 @@ def test_stream_recovery_session_non_retryable_error_is_final() -> None:
assert decision.action == RecoveryFailureAction.FINAL_ERROR
assert not decision.retryable
- assert session.early_retries == 0
-
-
-def test_continuation_suffix_trims_overlap() -> None:
- assert continuation_suffix("hello wor", "world") == "ld"
- assert continuation_suffix("alpha", "alpha beta") == " beta"
- assert continuation_suffix("", "fresh") == "fresh"
-
-
-def test_tool_json_repair_requires_append_only_schema_valid_json() -> None:
- schemas = {
- "Echo": ToolSchema(
- name="Echo",
- input_schema={
- "type": "object",
- "properties": {"message": {"type": "string"}},
- "required": ["message"],
- "additionalProperties": False,
- },
- )
- }
-
- accepted = accept_tool_json_repair(
- '{"message":',
- '"ok"}',
- tool_name="Echo",
- schemas=schemas,
- )
- assert accepted is not None
- assert accepted.suffix == '"ok"}'
- assert accepted.parsed_input == {"message": "ok"}
-
- assert (
- accept_tool_json_repair(
- '{"message":',
- "1}",
- tool_name="Echo",
- schemas=schemas,
- )
- is None
- )
+ assert controller.early_retries == 0
def test_holdback_buffers_until_delay_then_commits() -> None:
diff --git a/tests/providers/test_streaming_errors.py b/tests/providers/test_streaming_errors.py
index 04a88154..1db10e65 100644
--- a/tests/providers/test_streaming_errors.py
+++ b/tests/providers/test_streaming_errors.py
@@ -13,14 +13,16 @@ from free_claude_code.core.anthropic.stream_contracts import (
parse_sse_text,
)
from free_claude_code.core.anthropic.streaming import (
- MIDSTREAM_RECOVERY_ATTEMPTS,
AnthropicStreamLedger,
- TruncatedProviderStreamError,
make_text_recovery_body,
)
+from free_claude_code.core.failures import ExecutionFailure
from free_claude_code.providers.base import ProviderConfig
-from free_claude_code.providers.exceptions import ProviderError
from free_claude_code.providers.nvidia_nim import NvidiaNimProvider
+from free_claude_code.providers.stream_recovery import (
+ MIDSTREAM_RECOVERY_ATTEMPTS,
+ TruncatedProviderStreamError,
+)
from free_claude_code.providers.transports.openai_chat.recovery import (
OpenAIChatRecovery,
)
@@ -151,12 +153,22 @@ async def _collect_stream(provider, request):
return [e async for e in provider.stream_response(request)]
-async def _collect_stream_error(provider, request, **kwargs) -> ProviderError:
- with pytest.raises(ProviderError) as exc_info:
+async def _collect_stream_error(provider, request, **kwargs) -> ExecutionFailure:
+ with pytest.raises(ExecutionFailure) as exc_info:
[e async for e in provider.stream_response(request, **kwargs)]
return exc_info.value
+async def _collect_stream_and_error(
+ provider, request, **kwargs
+) -> tuple[list[str], ExecutionFailure]:
+ events: list[str] = []
+ with pytest.raises(ExecutionFailure) as exc_info:
+ async for event in provider.stream_response(request, **kwargs):
+ events.extend((event,))
+ return events, exc_info.value
+
+
def _assert_no_content_deltas_after_error_text(
events: list[str], error_substr: str
) -> None:
@@ -282,8 +294,8 @@ class TestStreamingExceptionHandling:
assert "Connection lost" in error.message
@pytest.mark.asyncio
- async def test_error_after_native_tool_call_uses_top_level_error_event(self):
- """After a streamed tool_call, do not append error text as a new assistant text block."""
+ async def test_error_after_native_tool_call_closes_block_then_raises(self):
+ """A provider closes tool state, then leaves terminal serialization to API."""
provider = _make_provider()
request = _make_request()
tool_chunk = _make_tool_calls_chunk(
@@ -306,11 +318,14 @@ class TestStreamingExceptionHandling:
return_value=False,
),
):
- events = await _collect_stream(provider, request)
+ events, error = await _collect_stream_and_error(provider, request)
event_text = "".join(events)
+ parsed = parse_sse_text(event_text)
assert "tool_use" in event_text
- assert "Connection lost after tool" in event_text
- assert "event: error\n" in event_text
+ assert parsed[-1].event == "content_block_stop"
+ assert "Connection lost after tool" in error.message
+ assert "Connection lost after tool" not in event_text
+ assert "event: error\n" not in event_text
assert "message_stop" not in event_text
_assert_error_not_in_text_deltas_after_tool(
events, "Connection lost after tool"
@@ -629,8 +644,8 @@ class TestStreamingExceptionHandling:
assert "Request ID: REQ_BODY" in stream_error.message
@pytest.mark.asyncio
- async def test_error_after_native_tool_call_top_level_error_includes_body(self):
- """After a tool_use block, detailed provider errors remain top-level SSE errors."""
+ async def test_error_after_native_tool_call_failure_includes_body(self):
+ """Detailed failure data survives after the provider closes tool state."""
provider = _make_provider()
request = _make_request()
tool_chunk = _make_tool_calls_chunk(
@@ -650,22 +665,22 @@ class TestStreamingExceptionHandling:
new_callable=AsyncMock,
return_value=stream_mock,
):
- events = [
- e
- async for e in provider.stream_response(
- request,
- request_id="REQ_TOOL_BODY",
- )
- ]
+ events, stream_error = await _collect_stream_and_error(
+ provider,
+ request,
+ request_id="REQ_TOOL_BODY",
+ )
event_text = "".join(events)
+ parsed = parse_sse_text(event_text)
assert "tool_use" in event_text
- assert "event: error\n" in event_text
- assert "bad after tool" in event_text
- assert "Request ID: REQ_TOOL_BODY" in event_text
+ assert parsed[-1].event == "content_block_stop"
+ assert "event: error\n" not in event_text
+ assert "bad after tool" not in event_text
+ assert "Request ID: REQ_TOOL_BODY" not in event_text
assert "message_stop" not in event_text
- terminal_error = parse_sse_text(event_text)[-1]
- assert terminal_error.data["error"]["type"] == "invalid_request_error"
+ assert "bad after tool" in stream_error.message
+ assert "Request ID: REQ_TOOL_BODY" in stream_error.message
_assert_error_not_in_text_deltas_after_tool(events, "bad after tool")
@pytest.mark.asyncio
@@ -955,8 +970,8 @@ class TestStreamingExceptionHandling:
assert "provider stream failed" in error.message.lower()
@pytest.mark.asyncio
- async def test_truncated_recovery_stream_falls_back_to_error_tail(self):
- """Partial recovery bytes are not converted into a successful response."""
+ async def test_truncated_recovery_stream_closes_block_then_raises(self):
+ """Partial recovery bytes never become success or provider-owned wire errors."""
provider = _make_provider()
request = _make_request()
original_text = "hello wor" + ("x" * 70_000)
@@ -978,16 +993,18 @@ class TestStreamingExceptionHandling:
),
) as mock_collect,
):
- events = await _collect_stream(provider, request)
+ events, error = await _collect_stream_and_error(provider, request)
event_text = "".join(events)
assert mock_create.await_count == 1
assert mock_collect.await_count == 1
assert original_text in event_text
assert "world" not in event_text
- assert "Provider stream ended without finish_reason." in event_text
+ assert "Provider stream ended without finish_reason." in error.message
+ assert "Provider stream ended without finish_reason." not in event_text
parsed = parse_sse_text(event_text)
- assert parsed[-1].event == "error"
+ assert parsed[-1].event == "content_block_stop"
+ assert not any(event.event == "error" for event in parsed)
assert not any(event.event == "message_stop" for event in parsed)
assert not any(
event.event == "content_block_delta"
diff --git a/tests/providers/test_zai.py b/tests/providers/test_zai.py
index b5df3722..8045dea2 100644
--- a/tests/providers/test_zai.py
+++ b/tests/providers/test_zai.py
@@ -4,11 +4,11 @@ from unittest.mock import AsyncMock, MagicMock
import pytest
+from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
from free_claude_code.core.anthropic.models import Message, MessagesRequest
from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.defaults import ZAI_DEFAULT_BASE
-from free_claude_code.providers.exceptions import InvalidRequestError
from free_claude_code.providers.transports.openai_chat import OpenAIChatTransport
from free_claude_code.providers.zai import ZaiProvider
from tests.providers.support import passthrough_rate_limiter
diff --git a/tests/runtime/test_provider_manager.py b/tests/runtime/test_provider_manager.py
index 7cbc8365..ccf76d04 100644
--- a/tests/runtime/test_provider_manager.py
+++ b/tests/runtime/test_provider_manager.py
@@ -4,10 +4,10 @@ from unittest.mock import AsyncMock, MagicMock, patch
import pytest
+from free_claude_code.application.errors import ApplicationUnavailableError
from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.settings import Settings
from free_claude_code.providers.base import BaseProvider
-from free_claude_code.providers.exceptions import ServiceUnavailableError
from free_claude_code.providers.nvidia_nim import NvidiaNimProvider
from free_claude_code.providers.runtime import ProviderRuntime
from free_claude_code.runtime.provider_manager import ProviderRuntimeManager
@@ -74,7 +74,7 @@ async def test_startup_generation_lease_and_shutdown_close_exactly_once() -> Non
await manager.close()
assert factory.runtimes[0].cleanup_calls == 1
- with pytest.raises(ServiceUnavailableError, match="shutting down"):
+ with pytest.raises(ApplicationUnavailableError, match="shutting down"):
await manager.acquire()
@@ -473,7 +473,7 @@ async def test_shutdown_waits_for_active_lease_then_rejects_new_work() -> None:
await asyncio.sleep(0)
assert not close_task.done()
- with pytest.raises(ServiceUnavailableError, match="shutting down"):
+ with pytest.raises(ApplicationUnavailableError, match="shutting down"):
await manager.acquire()
await lease.release()
await close_task
@@ -495,9 +495,9 @@ async def test_cancelled_shutdown_retains_generation_for_retry() -> None:
with pytest.raises(asyncio.CancelledError):
await close_task
- with pytest.raises(ServiceUnavailableError, match="shutting down"):
+ with pytest.raises(ApplicationUnavailableError, match="shutting down"):
await manager.acquire()
- with pytest.raises(ServiceUnavailableError, match="shutting down"):
+ with pytest.raises(ApplicationUnavailableError, match="shutting down"):
await manager.replace(_settings("nvidia_nim/two"), commit=lambda: None)
assert factory.runtimes[0].cleanup_calls == 0
diff --git a/uv.lock b/uv.lock
index 8af27754..727a2e0b 100644
--- a/uv.lock
+++ b/uv.lock
@@ -561,7 +561,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "3.4.20"
+version = "3.4.21"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },