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
12.6 KB
Raw Blame
"""Same-provider continuation using evidence from the public delivery boundary."""

from copy import deepcopy
from dataclasses import dataclass, replace
from typing import Any, Literal

from free_claude_code.core.delivered_response import (
    client_call,
    is_structured_text_format,
)
from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.core.json_types import JsonObject
from free_claude_code.core.stream_recovery import (
    ContinuationSeed,
    RecoveryAction,
    SourceRecoverySnapshot,
    StreamFailureContext,
    assess_recovery,
)
from free_claude_code.core.trace import trace_event

from .admission import ProviderExecution

type UpstreamProtocol = Literal["chat", "messages", "responses"]


class SourceRecoveryState:
    """Native source evidence cannot be inferred from buffered public events."""

    def __init__(
        self,
        execution: ProviderExecution,
        *,
        previous: SourceRecoveryState | None = None,
    ) -> None:
        self._execution = execution
        self._prior_unsafe_reason = (
            previous.unsafe_reason or previous._prior_unsafe_reason
            if previous is not None
            else None
        )
        self.unsafe_reason: str | None = None
        self._pending_reasoning: set[int | str] = set()
        self._signed: set[int | str] = set()
        self._handoff_blocked = False

    @property
    def can_handoff(self) -> bool:
        return not self._handoff_blocked and not self._pending_reasoning

    def snapshot(
        self,
        *,
        body: dict[str, Any],
        protocol: UpstreamProtocol,
        normal_stop_seen: bool,
        for_model_fallback: bool = False,
    ) -> SourceRecoverySnapshot:
        return SourceRecoverySnapshot(
            normal_stop_seen=normal_stop_seen,
            structured_output=_structured_output(body, protocol),
            unsafe_reason=self.unsafe_reason
            or (self._prior_unsafe_reason if for_model_fallback else None),
            can_handoff=self.can_handoff,
        )

    def observe(
        self,
        protocol: UpstreamProtocol,
        payload: dict[str, Any],
        *,
        continuing: bool = False,
    ) -> None:
        kind = str(payload.get("type", ""))
        usage = payload.get("usage")
        if protocol == "messages" and kind == "message_start":
            usage = payload.get("message", {}).get("usage")
        elif protocol == "responses":
            usage = payload.get("response", {}).get("usage")
        if isinstance(usage, dict) and usage:
            trace_event(
                stage="provider",
                event="provider.attempt.usage",
                source="provider",
                request_id=self._execution.request_id,
                execution_id=self._execution.execution_id,
                attempt=self._execution.attempts_started,
                usage=usage,
            )
        if protocol == "chat":
            for choice in payload.get("choices", []):
                delta = choice.get("delta") or {}
                if delta.get("reasoning_details") or delta.get("audio"):
                    self.unsafe_reason = "native_content"
                    self._handoff_blocked = True
        elif protocol == "messages":
            block = payload.get("content_block")
            index = payload.get("index", -1)
            if isinstance(block, dict) and block.get("type") in {
                "thinking",
                "redacted_thinking",
            }:
                self.unsafe_reason = "signed_thinking"
                self._pending_reasoning.add(index)
                if block.get("signature") or block.get("data"):
                    self._signed.add(index)
            if isinstance(block, dict) and block.get("type") not in {
                "text",
                "tool_use",
                "thinking",
                "redacted_thinking",
            }:
                self.unsafe_reason = "native_content"
                self._handoff_blocked = True
            delta = payload.get("delta") or {}
            if (isinstance(block, dict) and block.get("citations")) or delta.get(
                "type"
            ) == "citations_delta":
                self.unsafe_reason = "native_content"
                self._handoff_blocked = True
            if delta.get("type") in {"thinking_delta", "signature_delta"}:
                self.unsafe_reason = "signed_thinking"
                if delta.get("signature"):
                    self._signed.add(index)
            if kind == "content_block_stop" and index in self._signed:
                self._pending_reasoning.discard(index)
        else:
            item = payload.get("item")
            if isinstance(item, dict):
                self._response_item(item, completed=kind == "response.output_item.done")
            response = payload.get("response")
            if isinstance(response, dict):
                for item in response.get("output", []):
                    if isinstance(item, dict):
                        self._response_item(
                            item, completed=item.get("status") == "completed"
                        )
            part = payload.get("part")
            if (
                kind in {"response.content_part.added", "response.content_part.done"}
                and isinstance(part, dict)
                and part.get("annotations")
            ):
                self.unsafe_reason = "native_content"
                self._handoff_blocked = True
            if kind.startswith(
                (
                    "response.web_search",
                    "response.code_interpreter",
                    "response.mcp_",
                    "response.image_generation",
                    "response.audio",
                )
            ):
                self.unsafe_reason = "hosted_or_native_content"
                self._handoff_blocked = True
            if kind == "response.output_text.annotation.added":
                self.unsafe_reason = "native_content"
                self._handoff_blocked = True
        if continuing and self.unsafe_reason:
            raise ExecutionFailure(
                kind=FailureKind.UPSTREAM,
                status_code=502,
                message="The continuation returned native state that cannot be combined with the delivered response.",
                retryable=False,
            )

    def _response_item(self, item: dict[str, Any], *, completed: bool) -> None:
        if item.get("type") not in {"message", "reasoning"} and not client_call(item):
            self.unsafe_reason = "hosted_or_native_content"
            self._handoff_blocked = True
        if item.get("encrypted_content"):
            self.unsafe_reason = "opaque_reasoning"
            if not completed:
                self._pending_reasoning.add(item.get("id", ""))
        if completed:
            self._pending_reasoning.discard(item.get("id", ""))
        if any(
            part.get("annotations")
            or part.get("type")
            not in {"output_text", "refusal", "reasoning_text", "summary_text"}
            for part in [*(item.get("content") or []), *(item.get("summary") or [])]
        ):
            self.unsafe_reason = "native_content"
            self._handoff_blocked = True


@dataclass(frozen=True, slots=True)
class PublicRecovery:
    body: dict[str, Any] | None = None


class ContinuationRequest:
    """Replace our private history suffix while retaining accepted corrections."""

    def __init__(self, protocol: UpstreamProtocol) -> None:
        self.protocol = protocol
        self._injected_rows = 0

    def build(self, body: dict[str, Any], text: str, thinking: str) -> dict[str, Any]:
        result = deepcopy(body)
        responses = self.protocol == "responses"
        field = "input" if responses else "messages"
        history = result.get(field, [])
        if responses and isinstance(history, str):
            history = [{"role": "user", "content": history}]
        if self._injected_rows:
            # Request corrections preserve these trailing plain-text turns.
            history = history[: -self._injected_rows]
        tail = continuation_tail(
            ContinuationSeed(text, thinking), tools=bool(result.get("tools"))
        )
        if responses:
            tail = [
                {
                    "role": row["role"],
                    "content": [
                        {
                            "type": "output_text"
                            if row["role"] == "assistant"
                            else "input_text",
                            "text": row["content"],
                        }
                    ],
                }
                for row in tail
            ]
        result[field] = [*history, *tail]
        self._injected_rows = len(tail)
        return result


def continuation_tail(seed: ContinuationSeed, *, tools: bool) -> list[dict[str, Any]]:
    """Materialize the same private context for construction and estimation."""
    instruction = "The previous provider stream was interrupted. Continue the assistant response exactly where it stopped. Do not repeat text already written."
    if tools:
        instruction += " No tool calls from this interrupted assistant turn were delivered or executed. Any unfinished calls were discarded. Emit the required tool calls using the provided tools."
    if seed.thinking:
        instruction = f"{seed.thinking}\n\n{instruction}"
    tail = [{"role": "assistant", "content": seed.text}] if seed.text else []
    return [*tail, {"role": "user", "content": instruction}]


def public_stream_failure(
    failure: ExecutionFailure,
    *,
    source: SourceRecoveryState,
    body: dict[str, Any],
    protocol: UpstreamProtocol,
    normal_stop_seen: bool,
    responses_failure_payload: JsonObject | None = None,
) -> ExecutionFailure:
    """Retain source evidence until routing has decided the public outcome."""
    return replace(
        failure,
        stream_context=StreamFailureContext(
            source.snapshot(
                body=body,
                protocol=protocol,
                normal_stop_seen=normal_stop_seen,
                for_model_fallback=True,
            ),
            responses_failure_payload,
        ),
    )


def _structured_output(body: dict[str, Any], protocol: UpstreamProtocol) -> bool:
    if protocol == "chat":
        extra = body.get("extra_body") or {}
        value = extra.get("response_format", body.get("response_format"))
    else:
        options = body.get("text" if protocol == "responses" else "output_config") or {}
        value = options.get("format")
    return is_structured_text_format(value)


def public_recovery(
    execution: ProviderExecution,
    *,
    body: dict[str, Any],
    request: ContinuationRequest,
    retryable: bool,
    normal_stop_seen: bool,
    source: SourceRecoveryState,
) -> PublicRecovery | None:
    delivery = execution.delivery
    if delivery is None or not delivery.content_released:
        return None
    if not retryable:
        return None
    assessment = assess_recovery(
        content_released=True,
        prefix=delivery.prefix,
        source=source.snapshot(
            body=body, protocol=request.protocol, normal_stop_seen=normal_stop_seen
        ),
        retryable=retryable,
    )
    if assessment.action is RecoveryAction.STOP:
        trace_event(
            stage="provider",
            event="provider.recovery.ineligible",
            source="provider",
            request_id=execution.request_id,
            reason=assessment.reason,
        )
        return None
    if assessment.action is RecoveryAction.HANDOFF:
        delivery.begin_continuation(handoff=True)
        trace_event(
            stage="provider",
            event="provider.recovery.tool_handoff",
            source="provider",
            request_id=execution.request_id,
            usage_estimated=True,
        )
        return PublicRecovery()
    if not execution.can_attempt:
        trace_event(
            stage="provider",
            event="provider.recovery.exhausted",
            source="provider",
            request_id=execution.request_id,
            attempts_started=execution.attempts_started,
            max_attempts=execution.max_attempts,
        )
        return None
    seed = assessment.seed
    if seed is None:
        return None
    replacement = request.build(body, seed.text, seed.thinking)
    delivery.begin_continuation()
    trace_event(
        stage="provider",
        event="provider.recovery.continuation",
        source="provider",
        request_id=execution.request_id,
        attempts_started=execution.attempts_started,
        max_attempts=execution.max_attempts,
        usage_estimated=True,
    )
    return PublicRecovery(body=replacement)