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
20.2 KB
Raw Blame
"""Bounded, request-local evidence of output released to a stream consumer."""

from copy import deepcopy
from typing import Any, Literal

import simplejson

from .history_replay import (
    readable_reasoning,
    unencrypted_responses_replay,
)
from .openai_responses import is_client_search
from .stream_recovery import DeliveredPrefix
from .token_estimation import estimate_text_tokens

RECOVERY_RETENTION_BYTES = 1_048_576

CLIENT_CALL_TYPES = frozenset(
    {
        "function_call",
        "custom_tool_call",
        "computer_call",
        "local_shell_call",
        "apply_patch_call",
    }
)


def client_call(item: dict[str, Any]) -> bool:
    kind = item.get("type")
    if kind == "tool_search_call":
        return is_client_search(item)
    return kind in CLIENT_CALL_TYPES or (
        kind == "shell_call"
        and isinstance(item.get("environment"), dict)
        and item["environment"].get("type") == "local"
    )


def is_structured_text_format(value: object) -> bool:
    return isinstance(value, dict) and value.get("type") in (
        "json_schema",
        "json_object",
    )


def responses_text_constraint(data: dict[str, Any]) -> str | None:
    """Identify public text contracts that cannot survive synthetic completion."""
    response = data.get("response")
    response = response if isinstance(response, dict) else {}
    text = response.get("text")
    if isinstance(text, dict) and is_structured_text_format(text.get("format")):
        return "structured_output"
    part = data.get("part")
    if data.get("logprobs") or (isinstance(part, dict) and part.get("logprobs")):
        return "text_logprobs"
    items = [data.get("item"), *(response.get("output") or [])]
    if any(
        part.get("logprobs")
        for item in items
        if isinstance(item, dict)
        for part in item.get("content") or []
    ):
        return "text_logprobs"
    return None


class DeliveredResponse:
    """Track this response only; the harness continues to own conversation history."""

    def __init__(self, wire_api: Literal["messages", "responses"]) -> None:
        self.wire_api = wire_api
        self.items: dict[int, dict[str, Any]] = {}
        self.closed: set[int] = set()
        self._text_closed: set[tuple[int, str, int]] = set()
        self._part_closed: set[tuple[int, str, int]] = set()
        self.header: dict[str, Any] = {}
        self.sequence = -1
        self.unsafe_reason: str | None = None
        self._text_constraint: str | None = None
        self._bytes = 0
        self._limited = False
        self._limited_output_tokens = 0
        self.progress = 0

    def _retain(self, value: object) -> bool:
        if self._limited:
            return False
        self._bytes += len(
            simplejson.dumps(value, use_decimal=True, ensure_ascii=False).encode(
                "utf-8"
            )
        )
        if self._bytes > RECOVERY_RETENTION_BYTES:
            self._limited_output_tokens = self.output_tokens()
            self._limited = True
            self.unsafe_reason = "retention_limit"
            self.items.clear()
            self.closed.clear()
            self._text_closed.clear()
            self._part_closed.clear()
            return False
        return True

    @property
    def retention_exhausted(self) -> bool:
        return self._limited

    def observe(self, data: dict[str, Any], *, count_progress: bool = True) -> None:
        kind = data.get("type", "")
        if not isinstance(kind, str):
            self.unsafe_reason = "unknown_event"
            return
        sequence = data.get("sequence_number")
        if isinstance(sequence, int):
            self.sequence = max(self.sequence, sequence)
        if kind in {"message_start", "response.created"} and not self.header:
            self.header = deepcopy(data.get("message", data.get("response", {})))
        delta = data.get("delta", "")
        text = (
            delta
            if isinstance(delta, str)
            else "".join(
                delta.get(field, "") for field in ("text", "thinking", "partial_json")
            )
            if isinstance(delta, dict)
            else ""
        )
        block = data.get("content_block", {})
        if kind == "content_block_start":
            text += block.get("text", "") + block.get("thinking", "")
            if (
                block.get("type") == "redacted_thinking"
                and (record := unencrypted_responses_replay(block.get("data")))
                is not None
            ):
                text += "".join(text for text, _ in readable_reasoning(record.native))
        if count_progress and (
            text
            or self._new_snapshot_text(data)
            or data.get("part", {}).get("refusal")
            or (kind == "response.refusal.done" and data.get("refusal"))
            or (kind == "content_block_start" and block.get("type") == "tool_use")
            or (
                kind == "response.output_item.done"
                and client_call(data.get("item", {}))
            )
        ):
            self.progress += 1
        if not self._limited:
            if self.wire_api == "messages":
                self._messages(kind, data)
            else:
                self._responses(kind, data)
        if self._limited:
            self._limited_output_tokens += estimate_text_tokens(text)

    def _new_snapshot_text(self, data: dict[str, Any]) -> bool:
        """Cumulative text is progress only when it adds published characters."""
        kind = data.get("type")
        recorded = self.items.get(data.get("output_index"), {})
        previous = recorded.get("content") or []
        if kind in {"response.output_item.added", "response.output_item.done"}:
            item = data.get("item", {})
            if item.get("type") != "message":
                return False
            parts = enumerate(item.get("content") or [])
        elif kind in {"response.content_part.added", "response.content_part.done"}:
            parts = [(data.get("content_index", 0), data.get("part", {}))]
        elif kind == "response.output_text.done":
            parts = [
                (
                    data.get("content_index", 0),
                    {"type": "output_text", "text": data.get("text", "")},
                )
            ]
        else:
            return False
        return any(
            part.get("type") == "output_text"
            and len(part.get("text", ""))
            > len(previous[index].get("text", "") if index < len(previous) else "")
            for index, part in parts
        )

    def _messages(self, kind: str, data: dict[str, Any]) -> None:
        index = data.get("index")
        if not isinstance(index, int):
            if kind not in {
                "message_start",
                "message_delta",
                "message_stop",
                "ping",
                "error",
            }:
                self.unsafe_reason = "unknown_event"
            return
        if kind == "content_block_start":
            block = data.get("content_block", {})
            if not self._retain(block):
                return
            self.items[index] = deepcopy(block)
            if block.get("type") not in {
                "text",
                "thinking",
                "redacted_thinking",
                "tool_use",
            }:
                self.unsafe_reason = "native_content"
            if block.get("signature") or block.get("type") == "redacted_thinking":
                value = (
                    block.get("data")
                    if block.get("type") == "redacted_thinking"
                    else block.get("signature")
                )
                if unencrypted_responses_replay(value) is None:
                    self.unsafe_reason = "opaque_reasoning"
        elif kind == "content_block_delta":
            delta = data.get("delta", {})
            if not self._retain(delta):
                return
            block = self.items.get(index)
            if block is None:
                self.unsafe_reason = "missing_block"
                return
            field = {
                "text_delta": "text",
                "thinking_delta": "thinking",
                "input_json_delta": "partial_json",
            }.get(delta.get("type"))
            if field:
                block[field] = block.get(field, "") + delta.get(field, "")
            elif delta.get("type") == "signature_delta":
                block["signature"] = block.get("signature", "") + delta.get(
                    "signature", ""
                )
                if unencrypted_responses_replay(block["signature"]) is None:
                    self.unsafe_reason = "opaque_delta"
            else:
                self.unsafe_reason = "opaque_delta"
        elif kind == "content_block_stop":
            self.closed.add(index)

    def _responses(self, kind: str, data: dict[str, Any]) -> None:
        self._text_constraint = self._text_constraint or responses_text_constraint(data)
        index = data.get("output_index")
        if not isinstance(index, int):
            if kind not in {
                "response.created",
                "response.in_progress",
                "response.completed",
                "response.incomplete",
                "response.failed",
                "response.error",
                "error",
                "ping",
            }:
                self.unsafe_reason = "unknown_event"
            return
        if kind in {"response.output_item.added", "response.output_item.done"}:
            item = data.get("item", {})
            if not self._retain(item):
                return
            self.items[index] = deepcopy(item)
            if item.get("type") not in {"message", "reasoning"} and not client_call(
                item
            ):
                self.unsafe_reason = "native_content"
            if (
                item.get("encrypted_content")
                and unencrypted_responses_replay(item["encrypted_content"]) is None
            ):
                self.unsafe_reason = "opaque_reasoning"
            if any(part.get("type") == "refusal" for part in item.get("content") or []):
                self.unsafe_reason = "refusal"
            if kind.endswith(".done"):
                self.closed.add(index)
        elif kind in {
            "response.content_part.added",
            "response.reasoning_summary_part.added",
            "response.content_part.done",
            "response.reasoning_summary_part.done",
        }:
            part = data.get("part", {})
            if not self._retain(part) or (
                kind.endswith(".done")
                and not self._retain(
                    (
                        kind,
                        index,
                        data.get("content_index", data.get("summary_index", 0)),
                    )
                )
            ):
                return
            item = self.items.get(index)
            if item is None:
                self.unsafe_reason = "missing_item"
                return
            field = "summary" if "reasoning" in kind else "content"
            position = data.get(
                "summary_index" if field == "summary" else "content_index", 0
            )
            parts = item[field] = item.get(field) or []
            while len(parts) <= position:
                parts.append({})
            parts[position] = deepcopy(part)
            if kind.endswith(".done"):
                self._part_closed.add((index, field, position))
            if part.get("type") == "refusal":
                self.unsafe_reason = "refusal"
            elif part.get("type") not in {
                "output_text",
                "summary_text",
                "reasoning_text",
            }:
                self.unsafe_reason = "native_content"
        elif kind in {
            "response.output_text.delta",
            "response.reasoning_summary_text.delta",
            "response.reasoning_text.delta",
            "response.refusal.delta",
            "response.output_text.done",
            "response.reasoning_summary_text.done",
            "response.reasoning_text.done",
            "response.refusal.done",
        }:
            done = kind.endswith(".done")
            text_field = "refusal" if "refusal" in kind else "text"
            delta = data.get(text_field if done else "delta", "")
            if not self._retain(delta) or (
                done
                and not self._retain(
                    (
                        kind,
                        index,
                        data.get("content_index", data.get("summary_index", 0)),
                    )
                )
            ):
                return
            item = self.items.get(index)
            if item is None:
                self.unsafe_reason = "missing_item"
                return
            field = "summary" if "reasoning_summary" in kind else "content"
            position = data.get(
                "summary_index" if field == "summary" else "content_index", 0
            )
            parts = item[field] = item.get(field) or []
            while len(parts) <= position:
                parts.append(
                    {
                        "type": "summary_text"
                        if field == "summary"
                        else "reasoning_text"
                        if "reasoning" in kind
                        else "refusal"
                        if text_field == "refusal"
                        else "output_text",
                        text_field: "",
                    }
                )
            parts[position][text_field] = (
                delta if done else parts[position].get(text_field, "") + delta
            )
            if done:
                self._text_closed.add((index, field, position))
            if text_field == "refusal":
                self.unsafe_reason = "refusal"
        elif kind.endswith(".delta") and kind not in {
            "response.function_call_arguments.delta",
            "response.custom_tool_call_input.delta",
        }:
            self.unsafe_reason = "native_delta"
        elif kind not in {
            "response.function_call_arguments.delta",
            "response.function_call_arguments.done",
            "response.custom_tool_call_input.delta",
            "response.custom_tool_call_input.done",
        }:
            self.unsafe_reason = "unknown_event"

    def snapshot(self) -> DeliveredPrefix:
        text: list[str] = []
        thinking: list[str] = []
        has_calls = False
        for index, item in sorted(self.items.items()):
            kind = item.get("type")
            if self.wire_api == "messages":
                if kind == "text":
                    text.append(item.get("text", ""))
                elif kind == "thinking":
                    thinking.append(item.get("thinking", ""))
                elif kind == "redacted_thinking":
                    if (
                        record := unencrypted_responses_replay(item.get("data"))
                    ) is not None:
                        thinking.extend(
                            text for text, _ in readable_reasoning(record.native)
                        )
                elif kind == "tool_use" and index in self.closed:
                    has_calls = True
            elif kind == "message":
                text.extend(part.get("text", "") for part in item.get("content") or [])
            elif kind == "reasoning":
                thinking.extend(
                    part.get("text", "")
                    for part in [
                        *(item.get("summary") or []),
                        *(item.get("content") or []),
                    ]
                )
            elif client_call(item) and index in self.closed:
                has_calls = True
        unsafe_reason = self._text_constraint or self.unsafe_reason
        return DeliveredPrefix(
            "".join(text),
            "".join(thinking),
            has_calls,
            unsafe_reason is None,
            self.can_handoff,
            unsafe_reason,
        )

    def output_tokens(self, output: list[dict[str, Any]] | None = None) -> int:
        if output is None and self._limited:
            return self._limited_output_tokens
        return estimate_text_tokens(
            simplejson.dumps(
                list(self.items.values()) if output is None else output,
                use_decimal=True,
                ensure_ascii=False,
            )
        )

    @property
    def can_handoff(self) -> bool:
        if self._text_constraint or self.unsafe_reason not in {
            None,
            "opaque_reasoning",
            "opaque_delta",
        }:
            return False
        return all(
            index in self.closed
            for index, item in self.items.items()
            if item.get("type") in {"thinking", "redacted_thinking", "reasoning"}
        )

    def closing_events(self) -> list[dict[str, Any]]:
        events: list[dict[str, Any]] = []
        for index, item in sorted(self.items.items()):
            if index in self.closed:
                continue
            if self.wire_api == "messages":
                events.append({"type": "content_block_stop", "index": index})
            else:
                for field in ("content", "summary"):
                    for position, part in enumerate(item.get(field) or []):
                        key = (index, field, position)
                        if key in self._part_closed:
                            continue
                        summary = field == "summary"
                        identity = {
                            "item_id": item["id"],
                            "output_index": index,
                            "summary_index" if summary else "content_index": position,
                        }
                        if key not in self._text_closed:
                            text_kind = (
                                "response.reasoning_summary_text.done"
                                if summary
                                else "response.reasoning_text.done"
                                if part.get("type") == "reasoning_text"
                                else "response.output_text.done"
                            )
                            events.append(
                                {
                                    "type": text_kind,
                                    **identity,
                                    "text": part.get("text", ""),
                                }
                            )
                        if part.get("type") != "reasoning_text":
                            events.append(
                                {
                                    "type": "response.reasoning_summary_part.done"
                                    if summary
                                    else "response.content_part.done",
                                    **identity,
                                    "part": deepcopy(part),
                                }
                            )
                closed_item = {**deepcopy(item), "status": "completed"}
                events.append(
                    {
                        "type": "response.output_item.done",
                        "output_index": index,
                        "item": closed_item,
                    }
                )
        return events

    def handoff_events(self) -> list[dict[str, Any]]:
        """Signal handoff; the public writer fills output and usage after closure."""
        if self.wire_api == "messages":
            return [
                {
                    "type": "message_delta",
                    "delta": {"stop_reason": "tool_use", "stop_sequence": None},
                    "usage": {},
                },
                {"type": "message_stop"},
            ]
        response = {
            **deepcopy(self.header),
            "status": "completed",
        }
        return [{"type": "response.completed", "response": response}]

    def usage(self, output: list[dict[str, Any]] | None = None) -> dict[str, Any]:
        initial = deepcopy(self.header.get("usage") or {})
        input_tokens = initial.get("input_tokens", 0)
        output_tokens = self.output_tokens(output)
        return {
            **initial,
            "input_tokens": input_tokens,
            "output_tokens": output_tokens,
            "total_tokens": input_tokens + output_tokens,
        }