free-claude-code 6.2.64__py3-none-any.whl

free_claude_code/core/anthropic/native_stream.py

@@ -0,0 +1,306 @@
+"""Native Messages event validation and identity-preserving relay."""
+
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass, field, replace
+from typing import cast
+
+from free_claude_code.core.history_replay import (
+    ReplayOrigin,
+    ReplayRecord,
+    encode_replay,
+)
+from free_claude_code.core.json_types import JsonObject, JsonValue
+
+from .native import NativeMessagesError
+
+_STOP_REASONS = {
+    "end_turn",
+    "stop_sequence",
+    "tool_use",
+    "max_tokens",
+    "refusal",
+    "pause_turn",
+    "model_context_window_exceeded",
+}
+
+
+@dataclass(slots=True)
+class _Block:
+    body: JsonObject
+    parts: list[str] = field(default_factory=list)
+    fragments: dict[str, list[str]] = field(default_factory=dict)
+
+
+class NativeMessagesStreamState:
+    """Validate one upstream lifecycle without rewriting protocol identities."""
+
+    def __init__(self) -> None:
+        self.started = False
+        self.completed = False
+        self.stop_reason: str | None = None
+        self._blocks: dict[int, _Block] = {}
+        self._seen: set[int] = set()
+        self._tool_ids: set[str] = set()
+
+    def accept(
+        self, event_type: str, payload: Mapping[str, JsonValue]
+    ) -> JsonObject | None:
+        if self.completed:
+            raise NativeMessagesError("Messages event arrived after message_stop.")
+        try:
+            json.dumps(dict(payload), ensure_ascii=False, allow_nan=False).encode(
+                "utf-8"
+            )
+        except (ValueError, UnicodeError, RecursionError) as exc:
+            raise NativeMessagesError(
+                "Native Messages event is not representable JSON."
+            ) from exc
+        if payload.get("type") != event_type:
+            raise NativeMessagesError("Messages event type disagrees with its payload.")
+        if event_type == "ping":
+            return None
+        if event_type == "message_start":
+            if self.started:
+                raise NativeMessagesError("Duplicate message_start.")
+            message = payload.get("message")
+            if (
+                not isinstance(message, Mapping)
+                or not isinstance(message.get("id"), str)
+                or not message["id"]
+                or message.get("role") != "assistant"
+                or message.get("content", []) != []
+            ):
+                raise NativeMessagesError("Invalid native message_start.")
+            self.started = True
+            return None
+        if not self.started:
+            raise NativeMessagesError("Messages event arrived before message_start.")
+        if event_type == "message_delta":
+            delta = payload.get("delta")
+            if not isinstance(delta, Mapping):
+                raise NativeMessagesError("Native message_delta requires an object.")
+            reason = delta.get("stop_reason")
+            if reason is not None:
+                if self._blocks:
+                    raise NativeMessagesError(
+                        "Stop reason arrived with open content blocks."
+                    )
+                if not isinstance(reason, str) or reason not in _STOP_REASONS:
+                    raise NativeMessagesError(
+                        "Unsupported native Messages stop reason."
+                    )
+                if self.stop_reason is not None:
+                    raise NativeMessagesError("Duplicate native Messages stop reason.")
+                self.stop_reason = reason
+            return None
+        if event_type == "message_stop":
+            if self._blocks or self.stop_reason is None:
+                raise NativeMessagesError(
+                    "message_stop arrived before content or stop reason completed."
+                )
+            self.completed = True
+            return None
+        if event_type not in {
+            "content_block_start",
+            "content_block_delta",
+            "content_block_stop",
+        }:
+            raise NativeMessagesError(
+                f"Unsupported native Messages event: {event_type!r}."
+            )
+        if self.stop_reason is not None:
+            raise NativeMessagesError("Content arrived after the message stop reason.")
+        index = payload.get("index")
+        if not isinstance(index, int) or isinstance(index, bool) or index < 0:
+            raise NativeMessagesError(
+                "Messages block index must be a nonnegative integer."
+            )
+        if event_type == "content_block_start":
+            if index in self._seen:
+                raise NativeMessagesError("Duplicate Messages content block index.")
+            body = payload.get("content_block")
+            if not isinstance(body, Mapping) or not isinstance(body.get("type"), str):
+                raise NativeMessagesError("Invalid native content block.")
+            kind = body["type"]
+            if kind == "text" and not isinstance(body.get("text"), str):
+                raise NativeMessagesError("Native text block requires text.")
+            if kind == "thinking" and not isinstance(body.get("thinking"), str):
+                raise NativeMessagesError(
+                    "Native thinking block requires thinking text."
+                )
+            if (
+                kind == "thinking"
+                and "signature" in body
+                and not isinstance(body["signature"], str)
+            ):
+                raise NativeMessagesError("Native thinking signature must be a string.")
+            if kind == "redacted_thinking" and (
+                not isinstance(body.get("data"), str) or not body["data"]
+            ):
+                raise NativeMessagesError("Redacted native thinking requires its data.")
+            if kind == "tool_use":
+                tool_id = body.get("id")
+                if (
+                    not isinstance(tool_id, str)
+                    or not tool_id
+                    or tool_id in self._tool_ids
+                    or not isinstance(body.get("name"), str)
+                    or not body["name"]
+                    or not isinstance(body.get("input"), Mapping)
+                ):
+                    raise NativeMessagesError(
+                        "Invalid or duplicate native tool identity/input."
+                    )
+                self._tool_ids.add(tool_id)
+            self._blocks[index] = _Block(dict(body))
+            self._seen.add(index)
+            return None
+        block = self._blocks.get(index)
+        if block is None:
+            raise NativeMessagesError(
+                "Messages content event refers to a closed or unknown block."
+            )
+        if event_type == "content_block_delta":
+            delta = payload.get("delta")
+            if not isinstance(delta, Mapping):
+                raise NativeMessagesError("Native content delta must be an object.")
+            kind = delta.get("type")
+            target = (
+                {
+                    "text_delta": ("text", "text"),
+                    "thinking_delta": ("thinking", "thinking"),
+                    "signature_delta": ("thinking", "signature"),
+                    "input_json_delta": ("tool_use", "partial_json"),
+                }.get(kind)
+                if isinstance(kind, str)
+                else None
+            )
+            if target is None:
+                if kind == "citations_delta" and block.body["type"] == "text":
+                    citation = delta.get("citation")
+                    citations = block.body.get("citations")
+                    if citations is None:
+                        citations = []
+                    if not isinstance(citation, Mapping) or not isinstance(
+                        citations, list
+                    ):
+                        raise NativeMessagesError("Invalid native citation delta.")
+                    block.body["citations"] = [*citations, dict(citation)]
+                    return None
+                raise NativeMessagesError("Unsupported native content delta.")
+            block_type, key = target
+            value = delta.get(key)
+            if block.body["type"] != block_type or not isinstance(value, str):
+                raise NativeMessagesError(
+                    "Native content delta does not match its block."
+                )
+            if key == "partial_json":
+                if block.body.get("input"):
+                    raise NativeMessagesError(
+                        "Tool input mixes eager content and JSON deltas."
+                    )
+                block.parts.append(value)
+            else:
+                existing = block.body.get(key, "")
+                if not isinstance(existing, str):
+                    raise NativeMessagesError("Native content field must be a string.")
+                block.fragments.setdefault(key, []).append(value)
+            return None
+        for key, parts in block.fragments.items():
+            initial = block.body.get(key, "")
+            if not isinstance(initial, str):
+                raise AssertionError("Validated native content fields must be strings.")
+            block.body[key] = initial + "".join(parts)
+        if block.body["type"] == "thinking" and not block.body.get("signature"):
+            raise NativeMessagesError(
+                "Completed native thinking requires its signature."
+            )
+        if block.body["type"] == "tool_use" and block.parts:
+            try:
+                value = cast(JsonValue, json.loads("".join(block.parts)))
+                if not isinstance(value, Mapping):
+                    raise NativeMessagesError(
+                        "Native tool arguments must decode to an object."
+                    )
+                json.dumps(value, ensure_ascii=False, allow_nan=False).encode("utf-8")
+            except (ValueError, UnicodeError, RecursionError) as exc:
+                raise NativeMessagesError(
+                    "Native tool arguments are incomplete or invalid JSON."
+                ) from exc
+            block.body["input"] = dict(value)
+        self._blocks.pop(index)
+        return block.body
+
+
+class NativeMessagesRelay:
+    """Preserve upstream IDs, indexes, fields and event order for Messages clients."""
+
+    def __init__(
+        self, *, public_model: str, replay_origin: ReplayOrigin | None = None
+    ) -> None:
+        self._public_model = public_model
+        self._replay_origin = replay_origin
+        self._state = NativeMessagesStreamState()
+
+    @property
+    def completed(self) -> bool:
+        return self._state.completed
+
+    @property
+    def stop_reason(self) -> str | None:
+        return self._state.stop_reason
+
+    def feed(self, event_type: str, payload: Mapping[str, JsonValue]) -> str:
+        completed = self._state.accept(event_type, payload)
+        body = dict(payload)
+        if event_type == "message_start":
+            message = body.get("message")
+            if not isinstance(message, dict):
+                raise AssertionError("Validated message_start must contain a message.")
+            body["message"] = {**message, "model": self._public_model}
+            if (
+                self._replay_origin is not None
+                and isinstance(message.get("model"), str)
+                and message["model"]
+            ):
+                self._replay_origin = replace(
+                    self._replay_origin, model=message["model"]
+                )
+        prefix = ""
+        if self._replay_origin is not None:
+            block = body.get("content_block")
+            if event_type == "content_block_start" and isinstance(block, dict):
+                if block.get("type") == "thinking":
+                    body["content_block"] = {**block, "signature": ""}
+                elif block.get("type") == "redacted_thinking":
+                    body["content_block"] = {
+                        **block,
+                        "data": encode_replay(ReplayRecord(self._replay_origin, block)),
+                    }
+            delta = body.get("delta")
+            if (
+                event_type == "content_block_delta"
+                and isinstance(delta, dict)
+                and delta.get("type") == "signature_delta"
+            ):
+                return ""
+            if (
+                completed is not None
+                and completed.get("type") == "thinking"
+                and completed.get("signature")
+            ):
+                signature = encode_replay(ReplayRecord(self._replay_origin, completed))
+                prefix = _event(
+                    "content_block_delta",
+                    {
+                        "type": "content_block_delta",
+                        "index": body["index"],
+                        "delta": {"type": "signature_delta", "signature": signature},
+                    },
+                )
+        return prefix + _event(event_type, body)
+
+
+def _event(kind: str, payload: JsonObject) -> str:
+    return f"event: {kind}\ndata: {json.dumps(payload, ensure_ascii=False)}\n\n"

free_claude_code/core/anthropic/request_serialization.py

@@ -0,0 +1,57 @@
+"""Shared Anthropic request serialization helpers."""
+
+import json
+from typing import Any
+
+from .models import MessagesRequest
+
+_MESSAGES_REQUEST_FIELDS = (
+    "model",
+    "messages",
+    "system",
+    "max_tokens",
+    "stop_sequences",
+    "stream",
+    "temperature",
+    "top_p",
+    "top_k",
+    "metadata",
+    "tools",
+    "tool_choice",
+    "thinking",
+    "context_management",
+    "output_config",
+    "mcp_servers",
+    "extra_body",
+)
+
+
+def dump_messages_request(request: MessagesRequest) -> dict[str, Any]:
+    """Return JSON-ready public Messages fields without FCC routing state."""
+    raw = request.model_dump(exclude_none=True)
+    return {
+        field: raw[field]
+        for field in _MESSAGES_REQUEST_FIELDS
+        if field in raw and raw[field] is not None
+    }
+
+
+def serialize_tool_result_content(content: Any) -> str:
+    """Serialize Anthropic ``tool_result.content`` into provider-safe text."""
+    if content is None:
+        return ""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, dict):
+        return json.dumps(content, ensure_ascii=False)
+    if isinstance(content, list):
+        parts: list[str] = []
+        for item in content:
+            if isinstance(item, dict) and item.get("type") == "text":
+                parts.append(str(item.get("text", "")))
+            elif isinstance(item, dict):
+                parts.append(json.dumps(item, ensure_ascii=False))
+            else:
+                parts.append(str(item))
+        return "\n".join(parts)
+    return str(content)

free_claude_code/core/anthropic/request_snapshot.py

@@ -0,0 +1,35 @@
+"""Trace-safe snapshots of Anthropic protocol requests."""
+
+from typing import Any
+
+from free_claude_code.core.trace import sanitize_trace_value
+
+from .models import MessagesRequest, TokenCountRequest
+
+
+def anthropic_request_snapshot(
+    request: MessagesRequest | TokenCountRequest,
+) -> dict[str, Any]:
+    """Return the traceable public fields of an Anthropic request."""
+    data = request.model_dump(mode="python")
+    snapshot = {
+        key: data[key]
+        for key in (
+            "model",
+            "messages",
+            "system",
+            "tools",
+            "tool_choice",
+            "max_tokens",
+            "thinking",
+            "temperature",
+            "top_p",
+            "top_k",
+            "stop_sequences",
+            "metadata",
+            "stream",
+        )
+        if key in data and data[key] is not None
+    }
+    sanitized = sanitize_trace_value(snapshot)
+    return sanitized if isinstance(sanitized, dict) else {}

free_claude_code/core/anthropic/server_tool_sse.py

@@ -0,0 +1,234 @@
+"""Anthropic representation of completed local web-tool operations."""
+
+from collections.abc import Iterator, Mapping, Sequence
+from dataclasses import dataclass
+
+from free_claude_code.core.json_types import JsonObject
+from free_claude_code.core.web_tools import WebFetchResult, WebSearchResult
+
+from .server_tool_types import (
+    SERVER_TOOL_USE,
+    WEB_FETCH_TOOL_ERROR,
+    WEB_FETCH_TOOL_RESULT,
+    WEB_SEARCH_TOOL_RESULT,
+    WEB_SEARCH_TOOL_RESULT_ERROR,
+)
+from .streaming import format_sse_event
+
+
+@dataclass(frozen=True, slots=True)
+class ServerToolResponseContext:
+    message_id: str
+    tool_id: str
+    model: str
+    tool_name: str
+    tool_input: Mapping[str, str]
+    input_tokens: int
+    provider_usage: Mapping[str, object] | None = None
+
+
+def server_tool_start_frames(context: ServerToolResponseContext) -> Iterator[str]:
+    yield from server_tool_message_start_frames(context)
+    yield from server_tool_use_frames(context, index=0)
+
+
+def server_tool_message_start_frames(
+    context: ServerToolResponseContext,
+) -> Iterator[str]:
+    yield format_sse_event(
+        "message_start",
+        {
+            "type": "message_start",
+            "message": {
+                "id": context.message_id,
+                "type": "message",
+                "role": "assistant",
+                "content": [],
+                "model": context.model,
+                "stop_reason": None,
+                "stop_sequence": None,
+                "usage": _message_start_usage(
+                    context.input_tokens, context.provider_usage
+                ),
+            },
+        },
+    )
+
+
+def server_tool_use_frames(
+    context: ServerToolResponseContext, *, index: int
+) -> Iterator[str]:
+    yield format_sse_event(
+        "content_block_start",
+        {
+            "type": "content_block_start",
+            "index": index,
+            "content_block": {
+                "type": SERVER_TOOL_USE,
+                "id": context.tool_id,
+                "name": context.tool_name,
+                "input": context.tool_input,
+            },
+        },
+    )
+    yield format_sse_event(
+        "content_block_stop", {"type": "content_block_stop", "index": index}
+    )
+
+
+def web_search_result_block(
+    context: ServerToolResponseContext, results: Sequence[WebSearchResult]
+) -> JsonObject:
+    return {
+        "type": WEB_SEARCH_TOOL_RESULT,
+        "tool_use_id": context.tool_id,
+        "content": [
+            {"type": "web_search_result", "title": result.title, "url": result.url}
+            for result in results
+        ],
+    }
+
+
+def web_fetch_result_block(
+    context: ServerToolResponseContext,
+    result: WebFetchResult,
+    *,
+    retrieved_at: str,
+) -> JsonObject:
+    return {
+        "type": WEB_FETCH_TOOL_RESULT,
+        "tool_use_id": context.tool_id,
+        "content": {
+            "type": "web_fetch_result",
+            "url": result.url,
+            "content": {
+                "type": "document",
+                "source": {
+                    "type": "text",
+                    "media_type": result.media_type,
+                    "data": result.data,
+                },
+                "title": result.title,
+                "citations": {"enabled": True},
+            },
+            "retrieved_at": retrieved_at,
+        },
+    }
+
+
+def web_tool_error_block(
+    context: ServerToolResponseContext, *, error_code: str = "unavailable"
+) -> JsonObject:
+    search = context.tool_name == "web_search"
+    return {
+        "type": WEB_SEARCH_TOOL_RESULT if search else WEB_FETCH_TOOL_RESULT,
+        "tool_use_id": context.tool_id,
+        "content": {
+            "type": WEB_SEARCH_TOOL_RESULT_ERROR if search else WEB_FETCH_TOOL_ERROR,
+            "error_code": error_code,
+        },
+    }
+
+
+def server_tool_completion_frames(
+    context: ServerToolResponseContext,
+    result_block: JsonObject,
+    *,
+    summary: str,
+) -> Iterator[str]:
+    yield from server_tool_result_frames(result_block, index=1)
+    yield from server_tool_finish_frames(context, summary=summary, index=2)
+
+
+def server_tool_result_frames(result_block: JsonObject, *, index: int) -> Iterator[str]:
+    yield format_sse_event(
+        "content_block_start",
+        {"type": "content_block_start", "index": index, "content_block": result_block},
+    )
+    yield format_sse_event(
+        "content_block_stop", {"type": "content_block_stop", "index": index}
+    )
+
+
+def server_tool_finish_frames(
+    context: ServerToolResponseContext,
+    *,
+    summary: str,
+    index: int,
+    request_count: int = 1,
+) -> Iterator[str]:
+    yield format_sse_event(
+        "content_block_start",
+        {
+            "type": "content_block_start",
+            "index": index,
+            "content_block": {"type": "text", "text": ""},
+        },
+    )
+    yield format_sse_event(
+        "content_block_delta",
+        {
+            "type": "content_block_delta",
+            "index": index,
+            "delta": {"type": "text_delta", "text": summary},
+        },
+    )
+    yield format_sse_event(
+        "content_block_stop", {"type": "content_block_stop", "index": index}
+    )
+    yield format_sse_event(
+        "message_delta",
+        {
+            "type": "message_delta",
+            "delta": {"stop_reason": "end_turn", "stop_sequence": None},
+            "usage": _completion_usage(
+                context.input_tokens,
+                summary,
+                context.provider_usage,
+                usage_key=f"{context.tool_name}_requests",
+                request_count=request_count,
+            ),
+        },
+    )
+    yield format_sse_event("message_stop", {"type": "message_stop"})
+
+
+def _message_start_usage(
+    input_tokens: int,
+    provider_usage: Mapping[str, object] | None,
+) -> dict[str, object]:
+    if provider_usage is None:
+        return {"input_tokens": input_tokens, "output_tokens": 1}
+    usage = _integer_usage(provider_usage)
+    usage.setdefault("input_tokens", input_tokens)
+    usage["output_tokens"] = 1
+    return usage
+
+
+def _completion_usage(
+    input_tokens: int,
+    summary: str,
+    provider_usage: Mapping[str, object] | None,
+    *,
+    usage_key: str,
+    request_count: int,
+) -> dict[str, object]:
+    if provider_usage is None:
+        usage: dict[str, object] = {
+            "input_tokens": input_tokens,
+            "output_tokens": max(1, len(summary) // 4),
+        }
+    else:
+        usage = _integer_usage(provider_usage)
+        usage.setdefault("input_tokens", input_tokens)
+        usage.setdefault("output_tokens", max(1, len(summary) // 4))
+    usage["server_tool_use"] = {usage_key: request_count}
+    return usage
+
+
+def _integer_usage(usage: Mapping[str, object]) -> dict[str, object]:
+    return {
+        key: value
+        for key, value in usage.items()
+        if isinstance(value, int) and not isinstance(value, bool)
+    }

free_claude_code/core/anthropic/server_tool_types.py

@@ -0,0 +1,9 @@
+"""Anthropic server-tool block types shared by decoders and formatters."""
+
+from typing import Final
+
+SERVER_TOOL_USE: Final = "server_tool_use"
+WEB_SEARCH_TOOL_RESULT: Final = "web_search_tool_result"
+WEB_FETCH_TOOL_RESULT: Final = "web_fetch_tool_result"
+WEB_SEARCH_TOOL_RESULT_ERROR: Final = "web_search_tool_result_error"
+WEB_FETCH_TOOL_ERROR: Final = "web_fetch_tool_error"