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
13.0 KB
Raw Blame
"""Claude Messages API product flow."""

import asyncio
import sys
from collections.abc import AsyncIterator, Mapping
from dataclasses import replace

from fastapi.responses import JSONResponse, Response

from free_claude_code.api.detection import detect_safety_classifier_stop_sequence
from free_claude_code.api.request_errors import (
    http_status_for_unexpected_api_exception,
    log_unexpected_api_exception,
    ordinary_application_error_response,
    require_non_empty_messages,
    unexpected_http_exception,
)
from free_claude_code.api.request_ids import new_request_id
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.application.errors import ApplicationError
from free_claude_code.application.execution import ProviderExecutor, TokenCounter
from free_claude_code.application.ports import ModelInfoLookup, ProviderResolver
from free_claude_code.application.routing import (
    ModelRouter,
    RoutedMessagesRequest,
    RoutedNativeMessagesRequest,
)
from free_claude_code.application.web_tools.ports import WebToolsPort
from free_claude_code.application.web_tools.service import WebToolService
from free_claude_code.config.settings import Settings
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,
)
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.reasoning import ReasoningControl, ReasoningPolicy
from free_claude_code.core.request_outcomes import record_request_route
from free_claude_code.core.trace import close_stream_input, trace_event

from .classifier_response import classifier_response


class MessagesHandler:
    """Handle Anthropic-compatible Messages requests."""

    def __init__(
        self,
        settings: Settings,
        provider_resolver: ProviderResolver,
        *,
        web_tools: WebToolsPort,
        model_router: ModelRouter | None = None,
        token_counter: TokenCounter = get_token_count,
        provider_executor: ProviderExecutor | None = None,
        generation_id: int | None = None,
        request_headers: Mapping[str, str] | None = None,
        model_info_lookup: ModelInfoLookup | None = None,
    ) -> None:
        self._settings = settings
        self._model_router = model_router or ModelRouter(settings)
        self._provider_executor = provider_executor or ProviderExecutor(
            provider_resolver,
            progress_timeout_seconds=settings.provider_progress_timeout,
            token_counter=token_counter,
            generation_id=generation_id,
            log_raw_payloads=settings.log_raw_api_payloads,
            request_headers=request_headers,
            model_info_lookup=model_info_lookup,
        )
        self._web_tools = WebToolService(
            settings=settings,
            client=web_tools,
            executor=self._provider_executor,
            token_counter=token_counter,
        )

    async def create_native(
        self, routed: RoutedNativeMessagesRequest, *, request_id: str
    ) -> object:
        body = self._provider_executor.stream_native_messages(
            routed, request_id=request_id
        )
        if routed.request.stream:
            return await anthropic_sse_streaming_response(
                body,
                pre_start_error_response=lambda exc: self._pre_start_error_response(
                    exc, request_id=request_id
                ),
                request_id=request_id,
            )
        try:
            chunks = [chunk async for chunk in body]
            return Response(content="".join(chunks), media_type="application/json")
        except (Exception, BaseExceptionGroup) as error:
            return self._pre_start_error_response(error, request_id=request_id)
        finally:
            await close_stream_input(
                body,
                owner="native_messages_json",
                source="api",
                preserved_error=sys.exception(),
            )

    async def create(
        self, request_data: MessagesRequest, *, request_id: str | None = None
    ) -> object:
        """Create an Anthropic-compatible message response."""
        request_id = request_id or new_request_id()
        try:
            require_non_empty_messages(request_data.messages)
            routed = self._model_router.resolve_messages_request(request_data)
            routed = self._apply_message_routing_policies(routed)
            record_request_route(
                routed.resolved.primary.provider_id,
                routed.resolved.primary.provider_model,
            )
            body = self._web_tools.try_stream_messages(routed, request_id=request_id)
            if body is None:
                body = self._provider_executor.stream_messages(
                    routed,
                    raw_log_payload=routed.request.model_dump,
                    request_id=request_id,
                )
            return await self._to_public_response(
                body,
                stream=request_data.stream,
                request_id=request_id,
                hide_reasoning=routed.reasoning.control is ReasoningControl.PREFER_OFF,
            )
        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

    async def _to_public_response(
        self,
        body: AsyncIterator[str],
        *,
        stream: bool,
        request_id: str,
        hide_reasoning: bool = False,
    ) -> object:
        if not stream:
            # Non-streaming clients (e.g. Claude Code utility calls) need a
            # complete JSON Message; the internal pipeline is always SSE, so
            # serving that raw here breaks the client SDK's response parse.
            try:
                message, error, _complete = await aggregate_anthropic_sse_to_message(
                    classifier_response(body) if hide_reasoning else body
                )
            except GeneratorExit:
                raise
            except asyncio.CancelledError:
                raise
            except ApplicationError:
                raise
            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,
                    context="CREATE_MESSAGE_NON_STREAM_ERROR",
                )
            except Exception as exc:
                return self._unexpected_execution_error_response(
                    exc,
                    request_id=request_id,
                    context="CREATE_MESSAGE_NON_STREAM_ERROR",
                )
            if error is not None:
                error_type, message_text = _stream_error_fields(error)
                status_code = anthropic_status_for_error_type(error_type)
                trace_terminal_execution_error(
                    wire_api="messages",
                    request_id=request_id,
                    status_code=status_code,
                    error_type=error_type,
                )
                return terminal_execution_error_response(
                    status_code=status_code,
                    content=anthropic_error_payload(
                        error_type=error_type,
                        message=message_text,
                        request_id=request_id,
                    ),
                )
            return JSONResponse(content=message)
        return await anthropic_sse_streaming_response(
            body,
            pre_start_error_response=lambda exc: self._pre_start_error_response(
                exc, request_id=request_id
            ),
            request_id=request_id,
            hide_reasoning=hide_reasoning,
        )

    def _pre_start_error_response(
        self, exc: BaseException, *, request_id: str
    ) -> Response:
        if isinstance(exc, ApplicationError):
            return ordinary_application_error_response(
                exc,
                wire_api="messages",
                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)
            else "CREATE_MESSAGE_STREAM_START_ERROR"
        )
        return self._unexpected_execution_error_response(
            exc,
            request_id=request_id,
            context=context,
        )

    def _execution_failure_response(
        self, failure: ExecutionFailure, *, request_id: str
    ) -> JSONResponse:
        error_type = anthropic_error_type_for_failure(failure)
        trace_terminal_execution_error(
            wire_api="messages",
            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=anthropic_failure_payload(failure, request_id=request_id),
        )

    def _unexpected_execution_error_response(
        self,
        exc: BaseException,
        *,
        request_id: str,
        context: str,
    ) -> JSONResponse:
        log_unexpected_api_exception(
            self._settings,
            exc,
            context=context,
            request_id=request_id,
        )
        status_code = http_status_for_unexpected_api_exception(exc)
        trace_terminal_execution_error(
            wire_api="messages",
            request_id=request_id,
            status_code=status_code,
            error_type="api_error",
            error=exc,
        )
        return terminal_execution_error_response(
            status_code=status_code,
            content=anthropic_error_payload(
                error_type="api_error",
                message=safe_exception_message(exc),
                request_id=request_id,
            ),
        )

    def _apply_message_routing_policies(
        self, routed: RoutedMessagesRequest
    ) -> RoutedMessagesRequest:
        classifier_stop_sequence = detect_safety_classifier_stop_sequence(
            routed.request
        )
        if classifier_stop_sequence is None:
            return routed

        reasoning_changed = routed.reasoning.control is not ReasoningControl.PREFER_OFF
        stop_sequences = routed.request.stop_sequences
        remaining_stop_sequences = (
            [
                stop_sequence
                for stop_sequence in stop_sequences
                if stop_sequence != classifier_stop_sequence
            ]
            if stop_sequences is not None
            else None
        )
        stop_sequence_removed = remaining_stop_sequences != stop_sequences
        trace_event(
            stage="routing",
            event="free_claude_code.api.route.safety_classifier_policy",
            source="api",
            model=routed.resolved.original_model,
            classifier_stop_sequence=classifier_stop_sequence,
            reasoning_changed=reasoning_changed,
            stop_sequence_removed=stop_sequence_removed,
        )
        if not reasoning_changed and not stop_sequence_removed:
            return routed

        request = routed.request
        if stop_sequence_removed:
            request = request.model_copy(
                update={"stop_sequences": remaining_stop_sequences or None}
            )
        return replace(
            routed,
            request=request,
            reasoning=(
                ReasoningPolicy.prefer_off() if reasoning_changed else routed.reasoning
            ),
        )


def _stream_error_fields(error: dict[str, object]) -> tuple[str, str]:
    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 = (
        raw_message.strip()
        if isinstance(raw_message, str) and raw_message.strip()
        else "Provider request failed unexpectedly."
    )
    return error_type, message