Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

100 KB
Raw Blame
"""Shared HTTP, origin, and wire-content helpers for native adapters."""

from __future__ import annotations

import asyncio
import base64
import copy
import io
import inspect
import json
import re
import time
from collections.abc import AsyncIterator, Awaitable, Callable, Hashable, Mapping
from dataclasses import asdict, dataclass, field, fields, is_dataclass, replace
from typing import Any, TypeVar
from urllib.parse import parse_qsl, unquote, unquote_to_bytes, urlencode, urlsplit, urlunsplit

import httpx

from core.agent_core.ai.errors import (
    ProviderStalled,
    _is_sensitive_key,
    classify_error,
    parse_retry_after,
    redact_provider_error,
    redact_provider_text,
)
from core.agent_core.ai.hosted import MAX_HOSTED_COUNTERS
from core.agent_core.ai.image_limits import LoadedImage, fit_image
from core.agent_core.ai.request_artifacts import (
    ARTIFACT_WAIT_S,
    RequestAttempt,
    ResponseCapture,
    begin_attempt,
    note_slow_artifact_write,
)
from core.agent_core.ai.sse import SSEEvent, SSEParseError, SSEParser
from core.agent_core.cancel import CancelToken
from core.agent_core.messages import (
    AssistantContent,
    AssistantMessage,
    HOSTED_RENDER_EPOCH,
    HOSTED_RENDER_RULE,
    Citation,
    HostedCost,
    HostedSource,
    HostedSummary,
    HostedToolBlock,
    ImageBlock,
    Origin,
    TextBlock,
    ThinkingBlock,
    ToolCallBlock,
    ToolResultMessage,
    UserContent,
)
from core.agent_core.ai.provider import (
    OPAQUE_PAYLOADS,
    RETRYABLE_ERROR_KINDS,
    THINKING_DROP_RETRY_KINDS,
    BlockEnd,
    Done,
    HostedToolRoute,
    MediaLoader,
    MalformedToolCall,
    ModelEndpoint,
    ModelRequest,
    OpaquePayload,
    ProviderError,
    Refusal,
    TextDelta,
    ThinkingDelta,
    ToolCallDelta,
    ToolCallStart,
)


@dataclass(frozen=True)
class ServedHop:
    """The C-6 served-hop report: the message origin and the serving Source."""

    origin: Origin
    source_id: str


@dataclass(frozen=True)
class ServedResolution:
    """The response origin, whether its signature data is verified, and its Source.

    ``source_id`` is the endpoint's own Source in direct mode (``None`` when it names none), and ``None`` for a
    missing or invalid served-hop report. ``source_identity`` is the endpoint's identity when its own Source served
    the response, else ``None``: the identity of another Source is unknown here.
    """

    origin: Origin
    verified: bool
    source_id: str | None
    source_identity: str | None = None


ServedHopResolver = Callable[
    [Mapping[str, str]], ServedHop | None | Awaitable[ServedHop | None]
]
_SOURCE_ID = re.compile(r"src_[a-z0-9]{8,}")
_T = TypeVar("_T")
WireTranslator = Callable[[AsyncIterator[SSEEvent]], AsyncIterator[Any]]


@dataclass(frozen=True)
class WireField:
    """Declarative JSON field shape used at native protocol boundaries."""

    name: str
    expected: type | tuple[type, ...]
    required: bool = False
    nullable: bool = True
    children: tuple["WireField", ...] = ()
    item_children: tuple["WireField", ...] = ()

# A provider that never answers or stops sending mid-stream must not hold an
# agent turn forever, but a healthy one can stay silent for minutes: a
# reasoning model before its first token, or a relay that buffers a long tool
# call's arguments. One bound covers every wait on the provider: response
# headers, the first chunk, and each next chunk. Codex, Claude Code, Pi, and
# OpenCode allow 300s of silence; Avibe allows 600s (owner decision,
# 2026-10-10). Connecting stays separately short, so an unreachable provider
# still fails fast. Both bounds are shared by every native adapter; the loop
# may retry the resulting error only when no model output has been emitted.
#
# Through the Model Hub gateway the wait for response headers is not this
# bound's: the gateway withholds the headers, and every upstream byte with them
# (Anthropic's pings included), until the first model output, so a model that
# thinks without streaming its thinking is silent here however healthy it is.
# Only the gateway sees the upstream until then, so the gateway bounds that
# wait on every attempt: 120 s of byte silence for the Sources whose streams
# keep sending, this bound for the rest (docs/plans/model-hub-inference-
# deadlines.md, "Vibey's wait before output"). Once headers arrive the gateway
# forwards every byte, and this bound covers each next chunk again.
CONNECT_TIMEOUT_S = 10.0
PROVIDER_SILENCE_TIMEOUT_S = 600.0
CLEANUP_TIMEOUT_S = 10.0
MAX_CUMULATIVE_OUTPUT_CHARS = 32 * 1024 * 1024
# Conservative structural allowances, not a one-byte item counter. These cover
# block/tool objects and their indexing sets/maps in addition to payload bytes.
BLOCK_SLOT_OVERHEAD_BYTES = 2048
#: What one retained citation costs beyond its text fields.
CITATION_OVERHEAD_BYTES = 256
#: What one kept hosted counter costs beyond its name.
COUNTER_OVERHEAD_BYTES = 64
TOOL_ALIAS_OVERHEAD_BYTES = 512
# Only late response closes are detached; retain them until bounded cleanup
# completes. The driver registers their ownership in its single finally.
_response_cleanup_tasks: set[asyncio.Task[None]] = set()


class OutputBudgetExceeded(ValueError):
    """A provider exceeded the shared cumulative assembled-output budget."""


class WireDispatchError(ValueError):
    """A known wire frame has an invalid or missing type discriminator."""


class ToolIdentityError(ValueError):
    """A wire frame attempts to rebind an open tool slot to another call."""


def _string_buffer(value: str = "") -> io.StringIO:
    buffer = io.StringIO()
    buffer.write(value)
    return buffer


def usage_counter_error(
    value: Any,
    *,
    label: str,
    fields: tuple[str, ...],
    nested_fields: Mapping[str, tuple[str, ...]] | None = None,
) -> str | None:
    """Return an error for present usage counters with the wrong JSON shape."""

    if value is None:
        return None
    if not isinstance(value, Mapping):
        return f"{label} must be an object"
    for field in fields:
        raw = value.get(field)
        if raw is not None and (not isinstance(raw, int) or isinstance(raw, bool) or raw < 0):
            return f"{label} {field} must be a non-negative integer"
    for parent, child_fields in (nested_fields or {}).items():
        nested = value.get(parent)
        if nested is None:
            continue
        if not isinstance(nested, Mapping):
            return f"{label} {parent} must be an object"
        for field in child_fields:
            raw = nested.get(field)
            if raw is not None and (not isinstance(raw, int) or isinstance(raw, bool) or raw < 0):
                return f"{label} {parent}.{field} must be a non-negative integer"
    return None


class StreamAssembler:
    """Own canonical stream state shared by every native protocol adapter.

    Adapter modules translate wire events into these operations. This class
    owns visible-output accounting, tool-call identity, partial construction,
    and the exactly-one-terminal invariant.
    """

    def __init__(
        self,
        *,
        origin: Origin,
        protocol: str,
        verified_origin: bool = True,
        endpoint_url: str | None = None,
        sensitive_values: tuple[str, ...] = (),
    ) -> None:
        self.origin = origin
        self.protocol = protocol
        self.verified_origin = verified_origin
        self._endpoint_url = endpoint_url
        self._sensitive_values = tuple(value for value in sensitive_values if value)
        self.content: list[AssistantContent] = []
        self.usage: Any = None
        #: The Source that served the response (the served-hop report): the ``native.source_id`` of its hosted calls.
        self.source_id: str | None = None
        self.source_identity: str | None = None
        # Evidence from this stream's first prepared request; pause continuations must preserve its wire prefix.
        self.hosted_render_omitted: tuple[str, ...] = ()
        self._citations: dict[int, list[Citation]] = {}
        self._hosted_inputs: dict[Hashable, io.StringIO] = {}
        self._hosted_counts: dict[str, int] = {}
        self._hosted_cited: tuple[HostedSource, ...] = ()
        self._hosted_cost: HostedCost | None = None
        #: Whether the response was paused and continues (``pause``).
        self._continuing = False
        self._terminal_seen = False
        self._emitted_output = False
        # Text or a tool call: output past which a dropped response is never retried.
        self._emitted_visible = False
        self._closed_indices: set[int] = set()
        self._slots: dict[tuple[str, Hashable], int] = {}
        self._block_kinds: dict[Hashable, str] = {}
        self._thinking_key_by_index: dict[int, Hashable] = {}
        self._visible_blocks: set[int] = set()
        self._tools: dict[Hashable, dict[str, Any]] = {}
        self._tool_order: list[Hashable] = []
        self._tool_order_set: set[Hashable] = set()
        self._tool_id_owners: dict[str, set[Hashable]] = {}
        self._allocated_tool_ids: set[str] = set()
        self._next_tool_id = 0
        self._tool_keys_by_native_id: dict[str, Hashable] = {}
        self._charged_native_ids: set[str] = set()
        self._fallback_tool_sequence = 0
        self._latest_fallback_tool_key: Hashable | None = None
        self._driver_mode = False
        self._output_chars = 0
        self._text_buffers: dict[int, io.StringIO] = {}
        self._thinking_buffers: dict[int, io.StringIO] = {}
        self._thinking_signature_buffers: dict[int, io.StringIO] = {}
        self._thinking_details: dict[Hashable, list[dict[str, Any]]] = {}
        self._thinking_detail_buffers: dict[tuple[Hashable, int, str], io.StringIO] = {}
        self._reasoning_items: dict[Hashable, dict[str, Any]] = {}
        self._reasoning_key_by_id: dict[str, Hashable] = {}
        self._closed_reasoning_keys: set[Hashable] = set()
        self._tool_argument_buffers: dict[Hashable, io.StringIO] = {}

    @property
    def streamed(self) -> bool:
        """Whether a non-empty model output was exposed to the loop."""

        return self._emitted_output

    def set_origin(
        self,
        origin: Origin,
        verified_origin: bool,
        source_id: str | None = None,
        source_identity: str | None = None,
    ) -> None:
        if self._continuing:
            # A continued response is one message (§4.3): verified only when every response in it was, from one origin
            # and one Source identity, and its usage is the latest response's, none if that reports none.
            verified_origin = (
                verified_origin
                and self.verified_origin
                and origin == self.origin
                and source_identity == self.source_identity
            )
            self.usage = None
        self.origin = origin
        self.verified_origin = verified_origin
        self.source_id = source_id
        self.source_identity = source_identity

    def begin_driver(self) -> None:
        """Defer terminal marking while the shared lifecycle driver runs."""

        self._driver_mode = True

    def end_driver(self) -> None:
        self._driver_mode = False

    def set_usage(self, usage: Any) -> None:
        if usage is not None:
            self.usage = usage

    def _account_output(self, value: str | bytes | int) -> None:
        """Account every byte retained by the canonical stream state."""

        if isinstance(value, int):
            size = value
        elif isinstance(value, bytes):
            size = len(value)
        else:
            size = len(value.encode("utf-8"))
        if size <= 0:
            return
        if self._output_chars + size > MAX_CUMULATIVE_OUTPUT_CHARS:
            raise OutputBudgetExceeded(
                "provider cumulative output budget exceeded "
                f"({MAX_CUMULATIVE_OUTPUT_CHARS} bytes)"
            )
        self._output_chars += size

    def _account_replacement(self, previous: str, value: str) -> None:
        """Charge the bytes newly retained by a snapshot replacement."""

        if value.startswith(previous):
            self._account_output(value[len(previous) :])
        else:
            self._account_output(value)

    def _text_value(self, index: int) -> str:
        buffer = self._text_buffers.get(index)
        if buffer is not None:
            return buffer.getvalue()
        block = self.content[index]
        return block.text or "" if isinstance(block, TextBlock) else ""

    def _thinking_value(self, index: int) -> str:
        buffer = self._thinking_buffers.get(index)
        if buffer is not None:
            return buffer.getvalue()
        block = self.content[index]
        return block.text if isinstance(block, ThinkingBlock) else ""

    def _thinking_signature_value(self, index: int) -> str:
        key = self._thinking_key_by_index.get(index)
        if key is not None:
            self._materialize_thinking_details(key)
        buffer = self._thinking_signature_buffers.get(index)
        if buffer is not None:
            return buffer.getvalue()
        block = self.content[index]
        return block.signature or "" if isinstance(block, ThinkingBlock) else ""

    def _tool_arguments_value(self, key: Hashable) -> str:
        buffer = self._tool_argument_buffers.get(key)
        return buffer.getvalue() if buffer is not None else ""

    def _materialize_thinking_details(self, key: Hashable) -> None:
        details = self._thinking_details.get(key)
        if details is None:
            return
        index = self._slots.get(("thinking", key))
        if index is None:
            return
        values = [dict(item) for item in details]
        for (owner, item_index, field), buffer in self._thinking_detail_buffers.items():
            if owner == key and item_index < len(values):
                values[item_index][field] = buffer.getvalue()
        signature = json.dumps(values, ensure_ascii=False, separators=(",", ":"))
        block = self.content[index]
        if isinstance(block, ThinkingBlock):
            self._thinking_signature_buffers[index] = _string_buffer(signature)
            self.content[index] = ThinkingBlock(
                text=self._thinking_value(index),
                signature=signature,
                redacted=block.redacted,
            )
        self._thinking_details.pop(key, None)
        for detail_key in tuple(self._thinking_detail_buffers):
            if detail_key[0] == key:
                del self._thinking_detail_buffers[detail_key]

    def _materialize_content(self) -> None:
        """Publish buffered fragments into canonical blocks at a stream boundary."""

        for key in tuple(self._thinking_details):
            self._materialize_thinking_details(key)
        for index, block in enumerate(self.content):
            if isinstance(block, TextBlock):
                text = self._text_value(index)
                self.content[index] = TextBlock(text=text, citations=self._text_citations(index, text))
            elif isinstance(block, ThinkingBlock):
                self.content[index] = ThinkingBlock(
                    text=self._thinking_value(index),
                    signature=self._thinking_signature_value(index) or None,
                    redacted=block.redacted,
                )

    def _text_citations(self, index: int, text: str) -> tuple[Citation, ...] | None:
        """A text block's citations; a range that does not lie in its final text keeps its source, not the range."""

        citations = tuple(
            item if item.end is None or item.end <= len(text) else replace(item, start=None, end=None)
            for item in self._citations.get(index, ())
        )
        return citations or None

    def add_text_citation(self, key: Hashable, citation: Citation) -> None:
        """A provider citation on the text slot ``key`` (presentation only, never replayed)."""

        index = self._ensure_slot("text", key, TextBlock(text=""))
        self._account_output(CITATION_OVERHEAD_BYTES)
        for value in (citation.url, citation.title, citation.cited_text):
            if value:
                self._account_output(value)
        self._citations.setdefault(index, []).append(citation)

    def has_text_citations(self, key: Hashable) -> bool:
        index = self._slots.get(("text", key))
        return index is not None and bool(self._citations.get(index))

    def text_citations(self) -> tuple[Citation, ...]:
        return tuple(item for index in sorted(self._citations) for item in self._citations[index])

    def hosted_block(self, key: Hashable, block: HostedToolBlock) -> None:
        """Place a hosted call in stream order at its slot ``key``, or replace the call already there: a result
        arriving later finalizes the same block.

        This is the hosted calls' one boundary. The request's own credentials are removed from every string the block
        retains, payload included, as exact literals: a replayed payload must stay byte-exact, so no pattern touches
        it. The record's error is also redacted as a provider error is. Everything the block retains is charged, a
        replacement by its growth.
        """

        if self._sensitive_values:
            block = _without_literals(block, self._sensitive_values)
        if block.record.error is not None:
            redacted = redact_provider_text(
                block.record.error, literal_secrets=self._sensitive_values, endpoint_url=self._endpoint_url
            )
            block = replace(block, record=replace(block.record, error=redacted or block.record.error))
        index = self._slots.get(("hosted", key))
        if index is None:
            self._account_output(_retained_bytes(block))
            self._ensure_slot("hosted", key, block)
        else:
            previous = self.content[index]
            growth = _retained_bytes(block) - (
                _retained_bytes(previous) if isinstance(previous, HostedToolBlock) else 0
            )
            self._account_output(max(0, growth))
            self.content[index] = block
        self._emitted_output = True
        self._emitted_visible = True

    def hosted_input_delta(self, key: Hashable, value: str) -> None:
        """A fragment of a hosted call's streamed input, charged like any other retained output."""

        self._account_output(value)
        buffer = self._hosted_inputs.get(key)
        if buffer is None:
            buffer = self._hosted_inputs[key] = _string_buffer()
        buffer.write(value)

    def hosted_input(self, key: Hashable) -> str:
        """The hosted call's whole streamed input, once its block ends."""

        buffer = self._hosted_inputs.pop(key, None)
        return buffer.getvalue() if buffer is not None else ""

    def hosted_block_at(self, key: Hashable) -> HostedToolBlock | None:
        index = self._slots.get(("hosted", key))
        block = self.content[index] if index is not None else None
        return block if isinstance(block, HostedToolBlock) else None

    def set_hosted_facts(
        self,
        *,
        counts: Mapping[str, int] | None = None,
        cost: HostedCost | None = None,
        cited: tuple[HostedSource, ...] | None = None,
    ) -> None:
        """The response-scoped hosted facts the provider reported (§4.2 ``hosted_summary``), each charged as it is
        kept. A summary holds a small fixed set of counters, so at most ``MAX_HOSTED_COUNTERS`` are kept."""

        if counts is not None:
            kept = dict(list(counts.items())[:MAX_HOSTED_COUNTERS])
            for name in kept:
                self._account_output(COUNTER_OVERHEAD_BYTES)
                self._account_output(name)
            self._hosted_counts = kept
        if cost is not None:
            self._hosted_cost = cost
        if cited is not None:
            for item in cited:
                self._account_output(CITATION_OVERHEAD_BYTES)
                self._account_output(item.url)
                self._account_output(item.title or "")
            self._hosted_cited = cited

    def _hosted_summary(self, content: list[AssistantContent]) -> HostedSummary | None:
        if not any(isinstance(block, HostedToolBlock) for block in content):
            return None
        return HostedSummary(counts=self._hosted_counts, cited_sources=self._hosted_cited, cost=self._hosted_cost)

    def text_delta(self, key: Hashable, value: str) -> TextDelta | None:
        if not value:
            return None
        index = self._ensure_slot("text", key, TextBlock(text=""))
        if index in self._closed_indices:
            return None
        block = self.content[index]
        if not isinstance(block, TextBlock):
            return None
        self._account_output(value)
        buffer = self._text_buffers.setdefault(index, _string_buffer(block.text or ""))
        buffer.write(value)
        self._visible_blocks.add(index)
        self._emitted_output = True
        self._emitted_visible = True
        return TextDelta(index=index, delta=value)

    def ensure_text_slot(self, key: Hashable) -> int:
        return self._ensure_slot("text", key, TextBlock(text=""))

    def merge_text_snapshot(self, key: Hashable, value: str) -> TextDelta | None:
        if not value:
            return None
        index = self._ensure_slot("text", key, TextBlock(text=""))
        if index in self._closed_indices:
            return None
        block = self.content[index]
        if not isinstance(block, TextBlock):
            return None
        previous = self._text_value(index)
        self._account_replacement(previous, value)
        self._text_buffers[index] = _string_buffer(value)
        self._visible_blocks.add(index)
        self._emitted_output = True
        self._emitted_visible = True
        suffix = value[len(previous) :] if value.startswith(previous) else ""
        return TextDelta(index=index, delta=suffix) if suffix else None

    def thinking_delta(
        self,
        key: Hashable,
        value: str,
        *,
        signature: str | None = None,
    ) -> ThinkingDelta | None:
        if not value:
            return None
        if ("thinking", key) not in self._slots and signature:
            self._account_output(signature)
        index = self._ensure_slot(
            "thinking",
            key,
            ThinkingBlock(text="", signature=signature),
        )
        block = self.content[index]
        if index in self._closed_indices:
            return None
        if not isinstance(block, ThinkingBlock):
            return None
        self._account_output(value)
        buffer = self._thinking_buffers.setdefault(index, _string_buffer(block.text))
        buffer.write(value)
        self._visible_blocks.add(index)
        self._emitted_output = True
        return ThinkingDelta(index=index, delta=value)

    def replace_thinking(self, key: Hashable, value: str) -> ThinkingDelta | None:
        index = self._slots.get(("thinking", key))
        if index is None:
            index = self._ensure_slot("thinking", key, ThinkingBlock(text=""))
        if index in self._closed_indices:
            return None
        block = self.content[index]
        if isinstance(block, ThinkingBlock):
            previous = self._thinking_value(index)
            self._account_replacement(previous, value)
            self._thinking_buffers[index] = _string_buffer(value)
            if value:
                self._visible_blocks.add(index)
                self._emitted_output = True
            suffix = value[len(previous) :] if value.startswith(previous) else ""
            return ThinkingDelta(index=index, delta=suffix) if suffix else None
        return None

    def ensure_thinking_slot(
        self,
        key: Hashable,
        *,
        signature: str | None = None,
        redacted: bool = False,
    ) -> int:
        if ("thinking", key) not in self._slots and signature:
            self._account_output(signature)
        return self._ensure_slot(
            "thinking",
            key,
            ThinkingBlock(text="", signature=signature, redacted=redacted),
        )

    def redacted_thinking(self, key: Hashable, signature: str) -> int | None:
        # C-1 removes unverifiable opaque blocks. Do so before allocating an
        # index, otherwise final sanitization shifts already-published deltas.
        if not self.verified_origin:
            return None
        index = self.ensure_thinking_slot(key, signature=signature, redacted=True)
        block = self.content[index]
        if isinstance(block, ThinkingBlock):
            previous = self._thinking_signature_value(index)
            if signature != previous:
                self._account_replacement(previous, signature)
            self._thinking_buffers.pop(index, None)
            self._thinking_signature_buffers[index] = _string_buffer(signature)
            self.content[index] = ThinkingBlock(text="", signature=signature, redacted=True)
        return index

    def set_thinking_signature(self, key: Hashable, signature: str) -> None:
        index = self._slots.get(("thinking", key))
        if index is None:
            index = self._ensure_slot("thinking", key, ThinkingBlock(text=""))
        self._materialize_thinking_details(key)
        block = self.content[index]
        if isinstance(block, ThinkingBlock):
            previous_signature = self._thinking_signature_value(index)
            self._account_replacement(previous_signature, signature)
            self._thinking_signature_buffers[index] = _string_buffer(signature)

    def append_thinking_signature(self, key: Hashable, value: str) -> None:
        if not value:
            return
        index = self._slots.get(("thinking", key))
        if index is None:
            index = self._ensure_slot("thinking", key, ThinkingBlock(text=""))
        self._materialize_thinking_details(key)
        block = self.content[index]
        if isinstance(block, ThinkingBlock):
            self._account_output(value)
            buffer = self._thinking_signature_buffers.get(index)
            if buffer is None:
                buffer = _string_buffer(block.signature or "")
                self._thinking_signature_buffers[index] = buffer
            buffer.write(value)

    def merge_thinking_details(self, key: Hashable, details: list[Any]) -> None:
        valid = [detail for detail in details if isinstance(detail, Mapping)]
        if not valid:
            return
        index = self._ensure_slot("thinking", key, ThinkingBlock(text=""))
        accumulated = self._thinking_details.get(key)
        if accumulated is None:
            block = self.content[index]
            accumulated = []
            existing_signature = self._thinking_signature_value(index)
            if isinstance(block, ThinkingBlock) and existing_signature:
                try:
                    previous = json.loads(existing_signature)
                except (TypeError, ValueError):
                    previous = []
                if isinstance(previous, list):
                    accumulated.extend(item for item in previous if isinstance(item, Mapping))
            self._thinking_details[key] = accumulated
        if accumulated is None:
            return
        for detail in valid:
            item = dict(detail)
            previous = accumulated[-1] if accumulated else None
            if (
                isinstance(previous, dict)
                and previous.get("type") == item.get("type")
                and item.get("type") in {"reasoning.text", "reasoning.summary"}
                and isinstance(previous.get("text" if item["type"] == "reasoning.text" else "summary"), str)
                and isinstance(item.get("text" if item["type"] == "reasoning.text" else "summary"), str)
            ):
                field = "text" if item["type"] == "reasoning.text" else "summary"
                detail_index = len(accumulated) - 1
                buffer = self._thinking_detail_buffers.setdefault(
                    (key, detail_index, field),
                    _string_buffer(str(previous[field])),
                )
                self._account_output(
                    json.dumps(item, ensure_ascii=False, separators=(",", ":"))
                )
                buffer.write(item[field])
                previous[field] = ""
                for name in ("id", "format", "index", "signature"):
                    if previous.get(name) in (None, "") and name in item:
                        previous[name] = item[name]
                continue
            self._account_output(
                json.dumps(item, ensure_ascii=False, separators=(",", ":"))
            )
            accumulated.append(item)

    def merge_reasoning_item(
        self, key: Hashable, item: Mapping[str, Any], *, terminal_backfill: bool = False,
    ) -> None:
        """Budget and serialize changed reasoning once, including terminal backfill."""

        if key in self._closed_reasoning_keys and not terminal_backfill:
            return
        state = self._reasoning_items.get(key, {"type": "reasoning", "id": "", "encrypted_content": ""})
        changed = key not in self._reasoning_items
        for name, value in item.items():
            if name == "encrypted_content" and not value:
                continue
            if state.get(name) != value:
                changed = True
                break
        if not changed:
            return
        merged = dict(state)
        for name, value in item.items():
            if name == "encrypted_content" and not value:
                continue
            merged[name] = value
        merged["type"] = "reasoning"
        after = json.dumps(merged, ensure_ascii=False, separators=(",", ":"))
        self._account_output(after)
        previous_id = state.get("id")
        state = merged
        self._reasoning_items[key] = state
        if isinstance(previous_id, str) and previous_id and self._reasoning_key_by_id.get(previous_id) == key:
            del self._reasoning_key_by_id[previous_id]
        item_id = state.get("id")
        if isinstance(item_id, str) and item_id:
            self._reasoning_key_by_id[item_id] = key
        self.ensure_thinking_slot(key)
        if state["encrypted_content"]:
            self.set_thinking_signature(key, after)

    def reasoning_key_for_id(self, item_id: str | None) -> Hashable | None:
        if not item_id:
            return None
        return self._reasoning_key_by_id.get(item_id)

    def has_tools(self) -> bool:
        return any(isinstance(block, ToolCallBlock) for block in self.content)

    def has_content(self) -> bool:
        return bool(self.content)

    def has_text_slot(self, key: Hashable) -> bool:
        return ("text", key) in self._slots

    def set_block_kind(self, key: Hashable, kind: str) -> None:
        if key not in self._block_kinds:
            self._account_output(BLOCK_SLOT_OVERHEAD_BYTES)
        self._block_kinds[key] = kind

    def block_kind(self, key: Hashable) -> str | None:
        return self._block_kinds.get(key)

    def tool_count(self) -> int:
        return len(self._tool_order)

    def tool_start(
        self,
        key: Hashable,
        *,
        name: str | None = None,
        call_id: str | None = None,
        native_id: str | None = None,
        signature: str | None = None,
        defer_start: bool = False,
    ) -> ToolCallStart | None:
        state = self.tool_state(key)
        if "content_index" in state and state["content_index"] in self._closed_indices:
            return None
        self.bind_tool_identity(key, native_id)
        if call_id:
            # Canonical identity is immutable after ToolCallStart. A late wire
            # ID is an alias, never a new allocated canonical ID.
            if "content_index" not in state:
                self._set_tool_id(key, state, call_id)
            self.bind_tool_alias(key, call_id)
        if name and not state["name"]:
            self._account_pending_tool_identity(state, "name", name)
            state["name"] = name
            native_id = state["native_id"]
            owners = self._tool_id_owners.get(native_id or "", set())
            native_is_unique = bool(native_id) and (not owners or (len(owners) == 1 and key in owners))
            if "content_index" not in state and not state["id"] and native_is_unique:
                self._set_tool_id(key, state, state["native_id"])
        if signature and signature != state.get("signature"):
            previous_signature = state.get("signature") or ""
            self._account_replacement(previous_signature, signature)
            state["signature"] = signature
        if not state["name"] or defer_start:
            return None
        if "content_index" not in state:
            if not state["id"]:
                self._set_tool_id(key, state, self._new_tool_id())
            native = state["native_id"]
            state["content_index"] = len(self.content)
            self.content.append(
                ToolCallBlock(
                    id=state["id"],
                    native_id=native,
                    name=state["name"],
                    arguments={},
                    signature=state["signature"],
                )
            )
            self._visible_blocks.add(state["content_index"])
            self._emitted_output = True
            self._emitted_visible = True
            self._account_output(BLOCK_SLOT_OVERHEAD_BYTES)
            self._account_tool_identity_block(state)
            if native:
                self.bind_tool_alias(key, native)
            return ToolCallStart(
                index=state["content_index"],
                id=state["id"],
                name=state["name"],
            )
        index = state["content_index"]
        if index in self._closed_indices:
            return None
        block = self.content[index]
        if isinstance(block, ToolCallBlock):
            self.content[index] = ToolCallBlock(
                id=block.id,
                native_id=state["native_id"] or block.native_id,
                name=state["name"] or block.name,
                arguments=dict(block.arguments),
                signature=state["signature"] or block.signature,
            )
        return None

    def _account_pending_tool_identity(
        self,
        state: dict[str, Any],
        field: str,
        value: str,
    ) -> None:
        charged = state.setdefault("_charged_identity", set())
        previous = str(state.get(field) or "")
        if field not in charged:
            self._account_output(value)
            charged.add(field)
        elif previous != value:
            self._account_replacement(previous, value)

    def _account_tool_identity_block(self, state: dict[str, Any]) -> None:
        for field in ("id", "name", "native_id"):
            value = state.get(field)
            if value:
                self._account_pending_tool_identity(state, field, str(value))

    def bind_tool_identity(self, key: Hashable, native_id: str | None) -> None:
        """Bind once to the stream slot; aliases never override an explicit index."""

        if not native_id:
            return
        state = self.tool_state(key)
        if "content_index" in state and state["content_index"] in self._closed_indices:
            return
        previous = state["native_id"]
        if previous and previous != native_id:
            raise ToolIdentityError("tool slot received a conflicting native ID")
        if not previous:
            self._account_pending_tool_identity(state, "native_id", native_id)
            state["native_id"] = native_id
        self.bind_tool_alias(key, native_id)

    def bind_tool_alias(self, key: Hashable, native_id: str | None) -> None:
        if native_id:
            if native_id not in self._charged_native_ids:
                self._account_output(native_id)
                self._account_output(TOOL_ALIAS_OVERHEAD_BYTES)
                self._charged_native_ids.add(native_id)
            self._tool_keys_by_native_id[native_id] = key

    def fallback_tool_key(
        self,
        *,
        native_id: str | None = None,
        allocate: bool,
    ) -> Hashable | None:
        if native_id:
            existing = self._tool_keys_by_native_id.get(native_id)
            if existing is not None:
                self._latest_fallback_tool_key = existing
                return existing
        if not allocate:
            key = self._latest_fallback_tool_key
            if key is None:
                return None
            state = self._tools.get(key)
            if (
                state is not None
                and not state.get("finished")
                and (
                    "content_index" not in state
                    or state["content_index"] not in self._closed_indices
                )
            ):
                return key
            return None
        key = ("tool-fallback", self._fallback_tool_sequence)
        self._fallback_tool_sequence += 1
        self._latest_fallback_tool_key = key
        self.bind_tool_alias(key, native_id)
        return key

    def tool_arguments(self, key: Hashable, value: str, *, replace: bool = False) -> ToolCallDelta | None:
        state = self._tools.get(key)
        if state is not None and "content_index" in state and state["content_index"] in self._closed_indices:
            return None
        if value:
            state = self.tool_state(key)
            if replace:
                previous = self._tool_arguments_value(key)
                self._account_replacement(previous, value)
                self._tool_argument_buffers[key] = _string_buffer(value)
            else:
                self._account_output(value)
                buffer = self._tool_argument_buffers.get(key)
                if buffer is None:
                    buffer = _string_buffer()
                    self._tool_argument_buffers[key] = buffer
                buffer.write(value)
        state = self._tools.get(key)
        if not value or state is None or "content_index" not in state:
            return None
        self._emitted_output = True
        self._emitted_visible = True
        return ToolCallDelta(index=state["content_index"], arguments_delta=value)

    def tool_arguments_snapshot(self, key: Hashable, value: str) -> ToolCallDelta | None:
        """Replace a provider's final argument snapshot and emit only its suffix."""

        state = self._tools.get(key)
        if state is None:
            return None
        if "content_index" not in state:
            self.tool_arguments(key, value, replace=True)
            return None
        if state["content_index"] in self._closed_indices:
            return None
        previous = self._tool_arguments_value(key)
        if not value:
            return None
        if not value.startswith(previous):
            self._account_replacement(previous, value)
            self._tool_argument_buffers[key] = _string_buffer(value)
            return None
        self._account_replacement(previous, value)
        self._tool_argument_buffers[key] = _string_buffer(value)
        suffix = value[len(previous) :]
        if not suffix:
            return None
        self._emitted_output = True
        self._emitted_visible = True
        return ToolCallDelta(index=state["content_index"], arguments_delta=suffix)

    def pending_tool_arguments(self, key: Hashable) -> ToolCallDelta | None:
        state = self._tools.get(key)
        if state is None or "content_index" not in state:
            return None
        if state["content_index"] in self._closed_indices:
            return None
        arguments = self._tool_arguments_value(key)
        if not arguments:
            return None
        if state.get("arguments_emitted"):
            return None
        state["arguments_emitted"] = True
        return ToolCallDelta(
            index=state["content_index"],
            arguments_delta=arguments,
        )

    def set_tool_arguments_object(self, key: Hashable, value: Mapping[str, Any]) -> None:
        """Store an initial object without corrupting later JSON deltas."""

        encoded = json.dumps(value, ensure_ascii=False, separators=(",", ":"))
        self._account_output(encoded)
        self.tool_state(key)["arguments_obj"] = dict(value)

    def tool_state(self, key: Hashable) -> dict[str, Any]:
        state = self._tools.get(key)
        if state is None:
            state = self._new_tool_state()
            self._tools[key] = state
            self._account_output(BLOCK_SLOT_OVERHEAD_BYTES)
        if key not in self._tool_order_set:
            self._tool_order_set.add(key)
            self._tool_order.append(key)
        return state

    @staticmethod
    def _new_tool_state() -> dict[str, Any]:
        return {
            "id": "",
            "native_id": None,
            "name": "",
            "arguments": "",
            "signature": None,
            "_charged_identity": set(),
        }

    def tool_item_id(self, key: Hashable) -> str:
        return str(self._tools.get(key, {}).get("native_id") or "")

    def tool_name(self, key: Hashable) -> str:
        return str(self._tools.get(key, {}).get("name", ""))

    def has_tool(self, key: Hashable) -> bool:
        state = self._tools.get(key)
        return state is not None and "content_index" in state

    def finish_tool(self, key: Hashable) -> None:
        state = self._tools.get(key)
        if state is not None and "content_index" in state:
            state["finished"] = True

    def unfinished_tool_calls(self) -> tuple[ToolCallBlock, ...]:
        unfinished: list[ToolCallBlock] = []
        for state in self._tools.values():
            if "content_index" not in state or state.get("finished"):
                continue
            block = self.content[state["content_index"]]
            if isinstance(block, ToolCallBlock):
                unfinished.append(block)
        return tuple(unfinished)

    def interrupted_tool_events(self) -> tuple[ToolCallStart | ToolCallDelta, ...]:
        """Expose pending calls for a non-tool stop so the loop can settle them."""

        events: list[ToolCallStart | ToolCallDelta] = []
        for key, state in self._tools.items():
            if "content_index" in state or not state.get("name"):
                continue
            start = self.tool_start(key)
            if start is not None:
                events.append(start)
            arguments = self.pending_tool_arguments(key)
            if arguments is not None:
                events.append(arguments)
        return tuple(events)

    def block_end_events(self) -> tuple[BlockEnd, ...]:
        events: list[BlockEnd] = []
        for index in sorted(self._visible_blocks):
            if index in self._closed_indices:
                continue
            self._closed_indices.add(index)
            key = self._thinking_key_by_index.get(index)
            if key is not None:
                self._closed_reasoning_keys.add(key)
            events.append(BlockEnd(index=index))
        return tuple(events)

    def block_end(self, key: Hashable) -> BlockEnd | None:
        for kind in ("text", "thinking"):
            index = self._slots.get((kind, key))
            if index is not None:
                if index in self._closed_indices:
                    return None
                if index not in self._visible_blocks:
                    self._closed_indices.add(index)
                    if kind == "thinking":
                        self._closed_reasoning_keys.add(key)
                    return None
                self._closed_indices.add(index)
                if kind == "thinking":
                    self._closed_reasoning_keys.add(key)
                return BlockEnd(index=index)
        state = self._tools.get(key)
        if state is not None and "content_index" in state:
            index = state["content_index"]
            if index in self._closed_indices:
                return None
            self._closed_indices.add(index)
            return BlockEnd(index=index)
        return None

    def finalize(self, stop_reason: str, *, error_message: str | None = None) -> AssistantMessage | ProviderError:
        self._materialize_content()
        for state in self._tools.values():
            if not state.get("name"):
                return self.error("tool call name is missing", kind="invalid_request")
            if "content_index" not in state:
                return self.error("tool call ended before its identity was complete", kind="invalid_request")
        if stop_reason == "stop" and self.has_tools():
            stop_reason = "tool_use"
        final: list[AssistantContent] = []
        state_by_index = {
            state.get("content_index"): state
            for state in self._tools.values()
            if "content_index" in state
        }
        key_by_index = {
            state.get("content_index"): key
            for key, state in self._tools.items()
            if "content_index" in state
        }
        malformed: list[MalformedToolCall] = []
        for index, block in enumerate(self.content):
            if not isinstance(block, ToolCallBlock):
                final.append(block)
                continue
            state = state_by_index.get(index, {})
            raw_arguments = self._tool_arguments_value(key_by_index[index])
            if not raw_arguments and isinstance(state.get("arguments_obj"), Mapping):
                arguments: dict[str, Any] | ProviderError = dict(state["arguments_obj"])
            else:
                arguments = parsed_arguments(raw_arguments, tool_name=block.name)
            if isinstance(arguments, ProviderError):
                if stop_reason == "tool_use":
                    malformed.append(MalformedToolCall(id=block.id, name=block.name))
                # A length, safety, refusal, or error stop must still carry
                # every model-emitted call so the loop can settle it as an
                # unsuccessful tool result. The arguments are incomplete and
                # must not turn a provider stop into a malformed-request
                # failure.
                arguments = {}
            final.append(
                ToolCallBlock(
                    id=block.id,
                    native_id=state.get("native_id") or block.native_id,
                    name=block.name,
                    arguments=arguments,
                    signature=state.get("signature") or block.signature,
                )
            )
        if malformed:
            message = "malformed tool arguments: expected a JSON object"
            partial = assistant_message(
                final,
                origin=self.origin,
                stop_reason="error",
                usage=self.usage,
                error_message=message,
                verified_origin=self.verified_origin,
                hosted_summary=self._hosted_summary(final),
                source_identity=self.source_identity,
            )
            return ProviderError(
                kind="invalid_request",
                message=message,
                retryable=False,
                partial=self._rendered_response(partial),
                continuable=True,
                malformed_tool_calls=tuple(malformed),
            )
        return self._rendered_response(assistant_message(
            final,
            origin=self.origin,
            stop_reason=stop_reason,
            usage=self.usage,
            error_message=error_message,
            verified_origin=self.verified_origin,
            hosted_summary=self._hosted_summary(final),
            source_identity=self.source_identity,
        ))

    def _rendered_response(self, message: AssistantMessage) -> AssistantMessage:
        if not self.hosted_render_omitted:
            return message
        return replace(
            message, hosted_render_epoch=HOSTED_RENDER_EPOCH, hosted_render_rule=HOSTED_RENDER_RULE,
            hosted_render_omitted=self.hosted_render_omitted,
        )

    def pause(self) -> AssistantMessage | ProviderError:
        """The response so far, as the assistant turn its continuation sends back (§4.3). The continuation's output
        joins the same content, so the response stays one message."""

        self._continuing = True
        return self.finalize("tool_use")

    def partial(self, *, stop_reason: str = "error") -> AssistantMessage | None:
        if self.usage is None and not self._emitted_output:
            return None
        self._materialize_content()
        content = list(self.content)
        if not self._emitted_output:
            content = []
        return self._rendered_response(partial_message(
            content,
            origin=self.origin,
            usage=self.usage,
            verified_origin=self.verified_origin,
            stop_reason=stop_reason,
            hosted_summary=self._hosted_summary(content),
            source_identity=self.source_identity,
        ))

    def error(
        self,
        message: str,
        *,
        kind: str | None = None,
        code: str | None = None,
        status: int | None = None,
        headers: Mapping[str, str] | None = None,
    ) -> ProviderError:
        partial = (
            self.partial()
            if self.streamed or self.usage is not None
            else None
        )
        if kind == "invalid_request":
            error = ProviderError(
                kind="invalid_request",
                message=message,
                retryable=False,
                status=status,
                partial=partial,
            )
            return error
        if kind is not None:
            error = ProviderError(
                kind=kind,
                message=message,
                retryable=kind in RETRYABLE_ERROR_KINDS and not self.streamed,
                continuable=kind in RETRYABLE_ERROR_KINDS,
                retry_after_s=parse_retry_after((headers or {}).get("retry-after")),
                status=status,
                partial=partial,
            )
            return self._after_thinking(error, allow_unknown=True)
        error = classify_error(
            body=message,
            code=code,
            status=status,
            headers=headers,
            streamed=self.streamed,
            partial=partial,
            protocol=self.protocol,
        )
        return self._after_thinking(error, allow_unknown=True)

    def exception(
        self,
        exc: BaseException,
        *,
        status: int | None = None,
        headers: Mapping[str, str] | None = None,
    ) -> ProviderError:
        error = classify_error(
            exc=exc,
            status=status,
            headers=headers,
            streamed=self.streamed,
            partial=self.partial() if self.streamed or self.usage is not None else None,
        )
        return self._after_thinking(error)

    def aborted(self, reason: str | None = None) -> ProviderError:
        return ProviderError(
            kind="aborted",
            message=reason or "provider request aborted",
            retryable=False,
            partial=self.partial(stop_reason="aborted"),
        )

    def incomplete(self) -> ProviderError:
        return self.error(
            f"{self.protocol} stream ended before terminal event",
            kind="network",
        )

    def terminal(self, event: Done | ProviderError) -> Done | ProviderError | None:
        if self._driver_mode:
            return event
        if self._terminal_seen:
            return None
        if isinstance(event, ProviderError):
            event = _bounded_partial_error(self._sanitize_error(_partial_with_error(event)))
        self._terminal_seen = True
        return event

    def _after_thinking(self, error: ProviderError, *, allow_unknown: bool = False) -> ProviderError:
        """The producer alone grants thinking-drop replay, never terminal sanitization or error kind alone.

        Unknown wire failures retain their one request retry; an unknown local exception does not. Neither
        recovery exhaustion nor a refusal can regain permissions just because it names a transient kind.
        """
        if (
            self._emitted_output
            and not self._emitted_visible
            and error.refusal is None
            and error.kind in THINKING_DROP_RETRY_KINDS
            and (error.continuable or (allow_unknown and error.kind == "unknown"))
        ):
            return replace(error, retryable=True, after_thinking=True)
        return error

    def _sanitize_error(self, error: ProviderError) -> ProviderError:
        return redact_provider_error(
            error,
            literal_secrets=self._sensitive_values,
            endpoint_url=self._endpoint_url,
        )

    def _ensure_slot(self, kind: str, key: Hashable, block: AssistantContent) -> int:
        slot = (kind, key)
        index = self._slots.get(slot)
        if index is not None:
            return index
        self._account_output(BLOCK_SLOT_OVERHEAD_BYTES)
        index = len(self.content)
        self._slots[slot] = index
        if kind == "thinking":
            self._thinking_key_by_index[index] = key
        self.content.append(block)
        return index

    def _new_tool_id(self) -> str:
        self._next_tool_id = max(self._next_tool_id, len(self._tool_order) - 1)
        candidate = f"call_{self._next_tool_id}"
        while candidate in self._allocated_tool_ids:
            self._next_tool_id += 1
            candidate = f"call_{self._next_tool_id}"
        self._next_tool_id += 1
        return candidate

    def _set_tool_id(
        self,
        key: Hashable,
        state: dict[str, Any],
        value: str | None,
    ) -> None:
        owners = self._tool_id_owners.get(value or "")
        if owners and (len(owners) != 1 or key not in owners):
            value = self._new_tool_id()
        previous = state.get("id") or ""
        if previous == (value or ""):
            return
        if value:
            self._account_pending_tool_identity(state, "id", value)
        if previous:
            owners = self._tool_id_owners.get(previous)
            if owners is not None:
                owners.discard(key)
                if not owners:
                    del self._tool_id_owners[previous]
                    self._allocated_tool_ids.discard(previous)
        state["id"] = value or ""
        if value:
            self._tool_id_owners.setdefault(value, set()).add(key)
            self._allocated_tool_ids.add(value)


def _without_literals(value: Any, secrets: tuple[str, ...]) -> Any:
    """``value`` with each of ``secrets`` replaced in every string it holds, dataclass fields included."""

    if isinstance(value, str):
        for secret in secrets:
            value = value.replace(secret, "[redacted]")
        return value
    if isinstance(value, tuple):
        return tuple(_without_literals(item, secrets) for item in value)
    if isinstance(value, list):
        return [_without_literals(item, secrets) for item in value]
    if isinstance(value, dict):
        scrubbed: dict[Any, Any] = {}
        for key, item in value.items():
            name = _without_literals(key, secrets)
            while name in scrubbed:  # two keys that differed only by a credential keep both, in order
                name = f"{name}#"
            scrubbed[name] = _without_literals(item, secrets)
        return scrubbed
    if is_dataclass(value) and not isinstance(value, type):
        return replace(value, **{f.name: _without_literals(getattr(value, f.name), secrets) for f in fields(value)})
    return value


def _retained_bytes(block: HostedToolBlock) -> int:
    """What a hosted call keeps: its action, record and native payload, serialized once."""

    return len(json.dumps(asdict(block), ensure_ascii=False, default=str).encode("utf-8"))


def endpoint_origin(endpoint: ModelEndpoint) -> Origin:
    provider = endpoint.provider or f"endpoint:{credential_free_endpoint_identity(endpoint.base_url)}"
    if provider == "endpoint:":
        provider = f"endpoint:{endpoint.protocol}:{endpoint.model_id}"
    return Origin(
        provider=provider,
        api=endpoint.protocol,
        model=endpoint.model_id,
    )


def credential_free_endpoint_identity(base_url: str) -> str:
    """Return the endpoint location without userinfo, query, or fragment data."""

    try:
        parsed = urlsplit(base_url)
    except ValueError:
        return _fallback_endpoint_identity(base_url)
    if parsed.scheme and parsed.hostname:
        host = parsed.hostname
        if ":" in host and not host.startswith("["):
            host = f"[{host}]"
        try:
            port = parsed.port
        except ValueError:
            port = None
        if port is not None:
            host = f"{host}:{port}"
        path = parsed.path or "/"
        return f"{parsed.scheme}://{host}{path.rstrip('/') or '/'}"
    return _fallback_endpoint_identity(base_url)


def join_endpoint_url(base_url: str, suffix: str) -> str:
    """Append a protocol path while preserving the endpoint's query string.

    The endpoint may already be a complete protocol URL (useful for custom
    gateways), and the protocol suffix may add its own query parameters, as
    Some protocols add query parameters to their stream endpoint. URL parsing
    keeps credentials out of this operation's string manipulation and prevents
    a base query from becoming part of the request path.
    """

    base = urlsplit(base_url)
    extra = urlsplit(suffix)
    base_path = base.path.rstrip("/")
    suffix_path = extra.path.strip("/")
    base_leaf = base_path.rsplit("/", 1)[-1]
    suffix_leaf = suffix_path.rsplit("/", 1)[-1]
    same_operation = (
        ":" in base_leaf
        and ":" in suffix_leaf
        and base_leaf.split(":", 1)[1] == suffix_leaf.split(":", 1)[1]
    )
    already_joined = suffix_path and (
        base_path == suffix_path
        or base_path.endswith(f"/{suffix_path}")
        or same_operation
    )
    if suffix_path and not already_joined:
        path = f"{base_path}/{suffix_path}" if base_path else f"/{suffix_path}"
    else:
        path = base_path or "/"
    query = list(parse_qsl(base.query, keep_blank_values=True))
    query_keys = {key for key, _ in query}
    for key, value in parse_qsl(extra.query, keep_blank_values=True):
        if key in query_keys:
            continue
        query.append((key, value))
        query_keys.add(key)
    return urlunsplit((base.scheme, base.netloc, path, urlencode(query), ""))


def _fallback_endpoint_identity(base_url: str) -> str:
    value = base_url.split("?", 1)[0].split("#", 1)[0]
    scheme, separator, rest = value.partition("://")
    if not separator:
        return value.rstrip("/") or "unknown"
    authority, slash, path = rest.partition("/")
    authority = authority.rsplit("@", 1)[-1]
    return f"{scheme}://{authority}{('/' + path) if slash else '/'}"


def dispatch_wire_event(
    event: Any,
    *,
    known: frozenset[str],
    event_name: str | None = None,
    default: str | None = None,
    aliases: Mapping[str, str] | None = None,
) -> str | None:
    """Return a normalized known event type, ignoring unknown wire events like Pi.

    Native adapters use this at the protocol boundary before validating the
    shape of a known event. A missing ``type`` is allowed only for protocols
    whose stream frames are implicitly typed (Chat Completions).
    """

    if not isinstance(event, Mapping):
        return None
    named_type = (aliases or {}).get(event_name, event_name)
    if "type" in event:
        raw_type = event["type"]
        if not isinstance(raw_type, str):
            if named_type not in known:
                return None
            raise WireDispatchError(f"{event_name}.type must be a string")
    elif named_type in known:
        raise WireDispatchError(f"{event_name}.type is required")
    else:
        raw_type = default
    if not isinstance(raw_type, str):
        return None
    normalized = (aliases or {}).get(raw_type, raw_type)
    return normalized if normalized in known else None


def validate_wire_shape(
    event: Mapping[str, Any],
    event_type: str,
    table: Mapping[str, tuple[WireField, ...]],
) -> str | None:
    """Validate one known event against its declarative protocol row."""

    fields = table.get(event_type)
    if fields is None:
        return None
    return _validate_wire_fields(event, fields, event_type)


def _validate_wire_fields(
    value: Mapping[str, Any],
    fields: tuple[WireField, ...],
    path: str,
) -> str | None:
    for field in fields:
        field_path = f"{path}.{field.name}"
        if field.name not in value:
            if field.required:
                return f"{field_path} is required"
            continue
        current = value[field.name]
        if current is None:
            if field.nullable:
                continue
            return f"{field_path} must not be null"
        if not _wire_value_matches(current, field.expected):
            return f"{field_path} must be {_wire_type_name(field.expected)}"
        if field.children:
            child_error = _validate_wire_fields(current, field.children, field_path)
            if child_error is not None:
                return child_error
        if field.item_children:
            for index, item in enumerate(current):
                item_path = f"{field_path}[{index}]"
                if not isinstance(item, Mapping):
                    return f"{item_path} must be an object"
                item_error = _validate_wire_fields(item, field.item_children, item_path)
                if item_error is not None:
                    return item_error
    return None


def _wire_value_matches(value: Any, expected: type | tuple[type, ...]) -> bool:
    expected_types = expected if isinstance(expected, tuple) else (expected,)
    for expected_type in expected_types:
        if expected_type is int:
            if isinstance(value, int) and not isinstance(value, bool):
                return True
        elif expected_type is Mapping:
            if isinstance(value, Mapping):
                return True
        elif isinstance(value, expected_type):
            return True
    return False


def _wire_type_name(expected: type | tuple[type, ...]) -> str:
    expected_types = expected if isinstance(expected, tuple) else (expected,)
    names = [
        "object" if item is Mapping else "integer" if item is int else item.__name__
        for item in expected_types
    ]
    return " or ".join(names)


async def resolve_served_origin(
    endpoint: ModelEndpoint,
    headers: Mapping[str, str],
    resolver: ServedHopResolver | None,
    *,
    gateway: bool,
    cancel: CancelToken,
) -> ServedResolution | None:
    """Return the served origin, whether its signature data is verified, and its Source."""

    direct = endpoint_origin(endpoint)
    if not gateway:
        # Without a gateway the endpoint is the served hop, and its Source, when it names one, served the response.
        return ServedResolution(direct, True, endpoint.source_id, endpoint.source_identity)
    candidate = resolver(headers) if resolver is not None else default_served_hop_resolver(headers)
    if inspect.isawaitable(candidate):
        try:
            served = await _await_injected(candidate, cancel)
        except _CancelledDependency:
            return None
    else:
        served = candidate
    if cancel.cancelled:
        return None
    if served is None:
        return ServedResolution(direct, False, None)
    identity = endpoint.source_identity if served.source_id == endpoint.source_id else None
    return ServedResolution(served.origin, True, served.source_id, identity)


def default_served_hop_resolver(headers: Mapping[str, str]) -> ServedHop | None:
    """Read the exact C-6 served-hop header."""

    normalized = {key.lower(): value for key, value in headers.items()}
    report = normalized.get("x-avibe-served-hop")
    if not report or not report.isascii():
        return None
    try:
        value = json.loads(report, object_pairs_hook=_unique_json_object)
    except (TypeError, ValueError):
        return None
    if not isinstance(value, Mapping):
        return None
    if set(value) != {"provider", "api", "model", "source"} or any(not isinstance(value[key], str) for key in value):
        return None
    if not _SOURCE_ID.fullmatch(value["source"]):
        return None
    try:
        origin = Origin(provider=value["provider"], api=value["api"], model=value["model"])
    except (KeyError, TypeError, ValueError):
        return None
    return ServedHop(origin=origin, source_id=value["source"])


def _unique_json_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
    value = dict(pairs)
    if len(value) != len(pairs):
        raise ValueError("served-hop report contains duplicate keys")
    return value


def auth_headers(endpoint: ModelEndpoint, *, provider: str, gateway: bool) -> dict[str, str]:
    headers = {str(key): str(value) for key, value in endpoint.request_headers.items()}
    if any(key.lower() in {"authorization", "x-api-key", "x-goog-api-key"} for key in headers):
        return headers
    if gateway or provider in {"openai", "openai_chat", "openai_responses"}:
        headers["Authorization"] = f"Bearer {endpoint.token}"
    elif provider == "anthropic":
        headers["x-api-key"] = endpoint.token
    elif provider == "google":
        headers["x-goog-api-key"] = endpoint.token
    else:
        headers["Authorization"] = f"Bearer {endpoint.token}"
    return headers


def request_credential_values(endpoint: ModelEndpoint) -> tuple[str, ...]:
    """Return endpoint credentials that may appear in transport diagnostics."""

    values = [endpoint.token] if endpoint.token else []
    for name, value in endpoint.request_headers.items():
        if _is_sensitive_key(str(name)):
            values.append(str(value))
    try:
        parsed = urlsplit(endpoint.base_url)
    except ValueError:
        parsed = None
    if parsed is not None:
        values.extend(unquote(value) for value in (parsed.username, parsed.password) if value)
        values.extend(
            value for name, value in parse_qsl(parsed.query)
            if _is_sensitive_key(name)
        )
    return tuple(dict.fromkeys(values))


#: Pins a request that carries Source-specific hosted content to one Source (``vibey-hosted-tools.md`` §3.5): the
#: gateway serves it from that Source only, and answers ``pin_unavailable`` where it would otherwise fail over.
PIN_SOURCE_HEADER = "x-avibe-pin-source"
#: With the pin of an in-flight continuation: the served model of the response it continues.
PIN_MODEL_HEADER = "x-avibe-pin-model"


class HandOff:
    """A send that ends without a terminal, because the adapter decides what follows (§3.5, §4.3).
    ``drive_sse_stream`` yields it in place of a terminal and commits nothing."""

    def __init__(self, reason: str) -> None:
        self.reason = reason

    def __repr__(self) -> str:
        return f"HandOff({self.reason!r})"


class PinUnavailable(HandOff):
    """The gateway's answer to a pinned request it cannot serve from the pinned Source (§3.5): HTTP 409
    ``pin_unavailable``, before anything reached a model. ``tool`` and ``aspect`` name the narrow hosted rule that
    fired, when one did (``error.reason``)."""

    def __init__(self, tool: str | None = None, aspect: str | None = None) -> None:
        super().__init__("pin_unavailable")
        self.tool = tool
        self.aspect = aspect


#: A response the provider paused (Anthropic ``pause_turn``, §4.3): the adapter continues it as the same response.
PAUSE_TURN = HandOff("pause_turn")
#: An HTTP error the adapter answers by sending again (``drive_sse_stream``'s ``refused``).
REFUSED = HandOff("refused")


def _pin_unavailable(body: str) -> PinUnavailable | None:
    """The gateway's ``pin_unavailable`` answer, matched on ``type`` and ``code`` alone, with its narrow-rule reason
    when it carries one; None for any other body."""
    try:
        value = json.loads(body)
    except (TypeError, ValueError):
        return None
    error = value.get("error") if isinstance(value, Mapping) else None
    if not (
        isinstance(error, Mapping)
        and error.get("type") == "model_hub_pin_unavailable"
        and error.get("code") == "pin_unavailable"
    ):
        return None
    reason = error.get("reason")
    if isinstance(reason, Mapping) and reason.get("kind") == "hosted_unsupported":
        tool, aspect = reason.get("tool"), reason.get("aspect")
        return PinUnavailable(tool if isinstance(tool, str) else None, aspect if isinstance(aspect, str) else None)
    return PinUnavailable()


#: xAI's plain-text refusal of a replayed ciphertext it cannot read (§3.2); it does not say which one.
_DECRYPT_REFUSAL = re.compile(r"could not decrypt the provided encrypted_content", re.IGNORECASE)
#: Anthropic's refusal of a replayed opaque payload, by kind: an encrypted search result or citation index another
#: account minted, or a thinking signature it does not accept. Each names exactly what it refused.
_OPAQUE_REFUSALS: tuple[tuple[re.Pattern[str], tuple[OpaquePayload, ...]], ...] = (
    (_DECRYPT_REFUSAL, OPAQUE_PAYLOADS),
    (re.compile(r"invalid `?encrypted_(?:content|index)`?", re.IGNORECASE), ("hosted",)),
    (re.compile(r"invalid `?signature`? in `?thinking`? block", re.IGNORECASE), ("signature",)),
)


def opaque_refusal(body: str) -> tuple[OpaquePayload, ...]:
    """The kinds of opaque payload a 400 body says the provider refused; none when it names no such refusal."""

    kinds: list[OpaquePayload] = []
    for pattern, payloads in _OPAQUE_REFUSALS:
        if pattern.search(body):
            kinds.extend(kind for kind in payloads if kind not in kinds)
    return tuple(kinds)


def pin_refusal(assembler: StreamAssembler, endpoint: ModelEndpoint, handed_back: PinUnavailable) -> ProviderError:
    """The terminal of a pinned request the gateway handed back, which the loop answers by rendering the request again
    (§3.5). Nothing reached a model, so nothing is lost."""

    error = assembler.error("the gateway handed the pinned request back (pin_unavailable)", kind="server", status=409)
    refusal = Refusal(
        "pin_unavailable", endpoint.source_id, endpoint.source_identity, handed_back.tool, handed_back.aspect
    )
    return replace(error, retryable=False, continuable=False, after_thinking=False, refusal=refusal)


def search_history_endpoint(endpoint: ModelEndpoint) -> ModelEndpoint:
    """Keep native execution and in-flight exchanges; only completed historical web searches become portable."""
    route = endpoint.hosted_tools.get("web_search")
    if route is None or not route.replay:
        return endpoint
    return replace(endpoint, hosted_tools={**endpoint.hosted_tools, "web_search": replace(route, replay=False)})


def portable_endpoint(endpoint: ModelEndpoint) -> ModelEndpoint:
    """``endpoint`` in portable form (§3.5): never pinned, and every hosted tool as its function, so a request carries
    no native declaration and replays no native payload. The hop's Source and identity stay for attribution: a response
    that Source serves is still its own, and its opaque payloads are bound to that identity."""

    routes = {name: HostedToolRoute("proxy", False) for name in endpoint.hosted_tools}
    return replace(endpoint, portable=True, hosted_tools=routes)


@dataclass(frozen=True)
class WireRequest:
    """One model request exactly as its adapter sends it. A hosted-tool probe sends this request (§3.2)."""

    url: str
    headers: dict[str, str] = field(repr=False)
    body: dict[str, Any]


def native_hosted_tools(request: ModelRequest) -> dict[str, HostedToolRoute]:
    """The request's tools that this hop runs natively: a declared tool whose hosted route here is ``native``."""

    routes = request.endpoint.hosted_tools
    return {
        spec.name: routes[spec.name]
        for spec in request.tools
        if spec.name in routes and routes[spec.name].mode == "native"
    }


def native_declaration(route: HostedToolRoute) -> dict[str, Any]:
    """A native route's wire declaration, verbatim (§4.1), as a fresh object the payload may own."""

    return copy.deepcopy(dict(route.declaration or {}))


def hosted_pin(request: ModelRequest, messages: tuple[Any, ...] = ()) -> dict[str, str]:
    """The pin of a request that carries Source-specific hosted content (§3.5), else nothing.

    ``messages`` are the request's transformed messages; a call goes back verbatim only to the hop's own Source, so
    that is the pin. A continuation whose calls go back verbatim also names the model that served them.

    A model id that is not a legal header value (printable ASCII, no surrounding space) is left out: the pinned Source
    is the hop's, and the gateway takes that hop's own model, which served the continued response.
    """

    from core.agent_core.ai.transform import in_flight_position

    def replays(message: Any) -> bool:
        return isinstance(message, AssistantMessage) and any(isinstance(b, HostedToolBlock) for b in message.content)

    if request.endpoint.portable or (
        not native_hosted_tools(request) and not any(replays(message) for message in messages)
    ):
        return {}
    if not request.endpoint.source_id:
        raise ValueError("native hosted content needs the Source the request is pinned to")
    pin = {PIN_SOURCE_HEADER: request.endpoint.source_id}
    live = in_flight_position(messages)
    continued = messages[live] if live is not None else None
    if replays(continued) and _header_value(continued.origin.model):
        pin[PIN_MODEL_HEADER] = continued.origin.model
    return pin


def _header_value(value: str) -> bool:
    """Whether ``value`` can travel as an HTTP header value as it is: printable ASCII, with no surrounding space."""

    return bool(value) and value == value.strip() and all(" " <= char <= "~" for char in value)


async def iter_sse_events(
    response: httpx.Response,
    cancel: CancelToken,
    *,
    capture: ResponseCapture | None = None,
) -> AsyncIterator[SSEEvent]:
    """Yield SSE events while allowing a CancelToken to interrupt a stalled read. ``capture`` receives the raw bytes
    as they are read."""

    parser = SSEParser()
    iterator = response.aiter_bytes().__aiter__()
    while True:
        if cancel.cancelled:
            return
        try:
            chunk = await _await_network(
                iterator.__anext__(),
                cancel,
                timeout_s=PROVIDER_SILENCE_TIMEOUT_S,
            )
        except StopAsyncIteration:
            if capture is not None:
                capture.finish()
            break
        if chunk is None:
            return
        if capture is not None:
            capture.feed(chunk)
        for event in parser.feed(chunk):
            yield event
    for event in parser.finish():
        yield event


async def drive_sse_stream(
    client: httpx.AsyncClient,
    *,
    method: str,
    url: str,
    json_body: Any,
    headers: Mapping[str, str],
    cancel: CancelToken,
    assembler: StreamAssembler,
    endpoint: ModelEndpoint,
    resolver: ServedHopResolver | None,
    gateway: bool,
    translate: WireTranslator,
    refused: Callable[[ProviderError], bool] | None = None,
) -> AsyncIterator[Any]:
    """Own the complete request/stream/terminal/cleanup lifecycle.

    ``refused`` names an HTTP error the adapter answers by sending again: the driver yields ``REFUSED`` for it in place
    of a terminal, as for ``pin_unavailable``, so nothing the response already holds is lost.

    Protocol adapters provide only ``translate``. It receives the shared SSE
    iterator and yields canonical deltas or a candidate ``Done``/
    ``ProviderError``. The driver commits exactly one terminal event before
    closing the response, including when the transport raises while reading.
    """

    response: httpx.Response | None = None
    opening: asyncio.Task[httpx.Response] | None = None
    candidate: Done | ProviderError | None = None
    sent_at: float | None = None
    # The request's bytes, kept until it succeeds (``request_artifacts``), when a capture scope is active.
    attempt: RequestAttempt | None = None
    assembler.begin_driver()
    try:
        try:
            if not cancel.cancelled:
                # The transport bounds only connecting; the wait for response
                # headers is the provider's silence, bounded below, or the
                # gateway's to bound (``PROVIDER_SILENCE_TIMEOUT_S``).
                request = client.build_request(
                    method,
                    url,
                    json=json_body,
                    headers=headers,
                    timeout=httpx.Timeout(None, connect=CONNECT_TIMEOUT_S),
                )
                # Durable before it is sent: a crash mid-request leaves it pending, never a success. A Stop ends
                # the wait at once and nothing is sent; a write that stalls past its bound is not waited for.
                pending = begin_attempt(request, endpoint=endpoint, protocol=assembler.protocol)
                if pending is not None:
                    try:
                        await _await_artifact(pending.written, cancel)
                    except asyncio.CancelledError:
                        pending.give_up(sent=False)
                        raise
                    attempt = pending.attempt()
                    if attempt is None:
                        pending.give_up(sent=not cancel.cancelled)
            if cancel.cancelled:
                # Stopped before the send, possibly while the pending write ran: nothing goes out.
                if attempt is not None:
                    attempt.not_sent()
                candidate = assembler.aborted(cancel.reason)
            else:
                capture = attempt.capture if attempt is not None else None
                # Retain the opening task even if cancellation wins the await:
                # its successful result still belongs to this driver's finally.
                sent_at = time.monotonic()
                opening = asyncio.create_task(client.send(request, stream=True))
                response = await _await_network(
                    opening,
                    cancel,
                    timeout_s=None if gateway else PROVIDER_SILENCE_TIMEOUT_S,
                )
                if response is not None and capture is not None:
                    capture.response(response.status_code, response.headers)
                if response is None:
                    candidate = assembler.aborted(cancel.reason)
                elif not 200 <= response.status_code < 300:
                    # HTTP errors already identify their outcome. Resolving a
                    # served hop first could mask auth/rate limits (or stall).
                    try:
                        body = await read_response_body(response, cancel, capture=capture)
                    except (GeneratorExit, asyncio.CancelledError):
                        raise
                    except Exception as exc:
                        if attempt is not None:
                            attempt.exception_type = type(exc).__name__
                        candidate = assembler.exception(
                            exc,
                            status=response.status_code,
                            headers=response.headers,
                        )
                    else:
                        if body is None:
                            candidate = assembler.aborted(cancel.reason)
                        elif (
                            gateway
                            and response.status_code == 409
                            and PIN_SOURCE_HEADER in headers
                            and (handed_back := _pin_unavailable(body)) is not None
                        ):
                            # The pinned Source cannot serve this content; nothing reached a model. The adapter
                            # decides what follows (§3.5, §4.3), so no terminal is committed here.
                            if attempt is not None:
                                await _await_artifact(
                                    attempt.failed(kind="pin_unavailable", status=response.status_code), cancel
                                )
                            yield handed_back
                            return
                        else:
                            candidate = assembler.error(
                                body or f"provider endpoint returned HTTP {response.status_code}",
                                status=response.status_code,
                                headers=response.headers,
                            )
                            if refused is not None and refused(candidate):
                                if attempt is not None:
                                    await _await_artifact(
                                        attempt.failed(kind="http_error", error_kind=candidate.kind), cancel
                                    )
                                yield REFUSED
                                return
                            refused_payloads = opaque_refusal(body or "") if response.status_code == 400 else ()
                            if refused_payloads:
                                # A replayed opaque payload this account cannot read, refused before any output: the
                                # loop renders the request again without that identity's payloads of that kind (§3.5).
                                refusal = Refusal(
                                    "opaque_refused",
                                    endpoint.source_id,
                                    endpoint.source_identity,
                                    payloads=refused_payloads,
                                )
                                candidate = replace(
                                    candidate, retryable=False, continuable=False, after_thinking=False, refusal=refusal
                                )
                else:
                    resolved_origin = await resolve_served_origin(
                        endpoint,
                        response.headers,
                        resolver,
                        gateway=gateway,
                        cancel=cancel,
                    )
                    if resolved_origin is None:
                        candidate = assembler.aborted(cancel.reason)
                    else:
                        assembler.set_origin(
                            resolved_origin.origin,
                            resolved_origin.verified,
                            resolved_origin.source_id,
                            resolved_origin.source_identity,
                        )
                        async for item in translate(iter_sse_events(response, cancel, capture=capture)):
                            if isinstance(item, (Done, ProviderError)):
                                candidate = item
                                break
                            if item is PAUSE_TURN and attempt is not None:
                                # A paused response's request ended normally; its continuation is another request.
                                await _await_artifact(attempt.succeeded(), cancel)
                            yield item
                            if isinstance(item, HandOff):
                                return
                        if candidate is None:
                            candidate = (
                                assembler.aborted(cancel.reason)
                                if cancel.cancelled
                                else assembler.incomplete()
                            )
        except (GeneratorExit, asyncio.CancelledError):
            raise
        except (OutputBudgetExceeded, SSEParseError, ToolIdentityError) as exc:
            if attempt is not None:
                attempt.exception_type = type(exc).__name__
            candidate = assembler.error(str(exc), kind="invalid_request")
        except Exception as exc:
            if attempt is not None:
                attempt.exception_type = type(exc).__name__
            candidate = assembler.exception(exc)

        if candidate is not None:
            if (
                isinstance(candidate, ProviderError)
                and sent_at is not None
                and not assembler.streamed
                and time.monotonic() - sent_at >= PROVIDER_SILENCE_TIMEOUT_S
            ):
                # Whatever ended it, the request went at least the whole silence
                # bound without output. Sent again it would most likely wait as
                # long again, so the failure ends the turn: neither replayed nor
                # continued.
                candidate = replace(candidate, retryable=False, continuable=False)
            # Decided before the artifact's write is awaited: diagnostic storage never counts as provider silence.
            if attempt is not None:
                await _await_artifact(
                    attempt.succeeded()
                    if isinstance(candidate, Done)
                    else attempt.failed(
                        kind=_attempt_failure_kind(candidate, response),
                        error_kind=candidate.kind,
                        status=response.status_code if response is not None else None,
                    ),
                    cancel,
                )
            # Translator terminals are candidates, not public errors. Commit
            # and sanitize exactly once at the shared driver boundary.
            assembler.end_driver()
            terminal = assembler.terminal(candidate)
            if terminal is not None:
                yield terminal
    finally:
        assembler.end_driver()
        if attempt is not None:
            # Ended without a terminal (its consumer closed it, or its task was cancelled): out of the active set
            # and its ``unknown`` state queued, synchronously. Nothing here waits for diagnostics.
            attempt.abandon()
        async def close_opened_response() -> None:
            if opening is None:
                return
            try:
                opened_response = opening.result()
            except BaseException:
                # A failed/cancelled open did not transfer a response to us.
                return
            try:
                await _await_network(
                    opened_response.aclose(),
                    CancelToken(),
                    timeout_s=CLEANUP_TIMEOUT_S,
                )
            except Exception:
                # The terminal event has already been delivered. Cleanup is
                # diagnostic only and must never create a second outcome.
                # asyncio.CancelledError remains a BaseException so consumer
                # and task cancellation continues through this cleanup path.
                pass
        if opening is not None:
            if opening.done():
                await close_opened_response()
            else:
                # Non-cooperative opening tasks may outlive the bounded cancel
                # join. Attach disposal here without delaying the terminal.
                def close_late_response(_: asyncio.Future[httpx.Response]) -> None:
                    cleanup = asyncio.create_task(close_opened_response())
                    _response_cleanup_tasks.add(cleanup)
                    cleanup.add_done_callback(_response_cleanup_tasks.discard)
                    cleanup.add_done_callback(_consume_task_result)

                opening.add_done_callback(close_late_response)


async def _await_artifact(written: asyncio.Future[Any] | None, cancel: CancelToken) -> None:
    """Wait for an artifact write: at most ``ARTIFACT_WAIT_S``, and never past a Stop (the CancelToken, or this
    task's cancellation). The write itself always runs to its end on the artifact worker, which retrieves its
    outcome; diagnostics never hold up a request, its terminal, or a Stop."""

    if written is None:
        return
    try:
        await _await_network(asyncio.shield(written), cancel, timeout_s=ARTIFACT_WAIT_S)
    except ProviderStalled:
        note_slow_artifact_write()
    except asyncio.CancelledError:
        raise
    except Exception:
        pass  # logged by the write's done-callback


def _attempt_failure_kind(error: ProviderError, response: httpx.Response | None) -> str:
    """How a kept request ended, as a closed token: never the error's message, which can echo the request."""

    if error.kind == "aborted":
        return "cancelled"
    if response is None:
        return "network_error"
    if not 200 <= response.status_code < 300:
        return "http_error"
    return "stream_error"


async def _await_network(
    awaitable: Awaitable[_T],
    cancel: CancelToken,
    *,
    timeout_s: float | None = None,
) -> _T | None:
    """Own one cancellable network await for opening, reads, and body reads.

    Running out of ``timeout_s`` raises ``ProviderStalled``.
    """

    if cancel.cancelled:
        close = getattr(awaitable, "close", None)
        if close is not None:
            close()
        return None
    operation = asyncio.ensure_future(awaitable)
    cancellation = asyncio.create_task(cancel.wait())
    try:
        done, _ = await asyncio.wait(
            {operation, cancellation},
            timeout=timeout_s,
            return_when=asyncio.FIRST_COMPLETED,
        )
        if not done:
            await _cancel_and_join(operation)
            raise ProviderStalled(timeout_s)
        if cancellation in done and cancel.cancelled:
            await _cancel_and_join(operation)
            return None
        return operation.result()
    except ProviderStalled:
        raise
    except BaseException:
        await _cancel_and_join(operation)
        raise
    finally:
        if not cancellation.done():
            cancellation.cancel()
            with _suppress_cancelled():
                await cancellation


async def _cancel_and_join(operation: asyncio.Future[Any]) -> None:
    """Cancel an I/O task without hanging on a non-cooperative awaitable."""

    if operation.done():
        _consume_task_result(operation)
        return
    operation.cancel()
    try:
        done, _ = await asyncio.wait({operation}, timeout=CLEANUP_TIMEOUT_S)
    except asyncio.CancelledError:
        if not operation.done():
            operation.add_done_callback(_consume_task_result)
        raise
    if operation not in done:
        operation.add_done_callback(_consume_task_result)
    else:
        _consume_task_result(operation)


def _consume_task_result(operation: asyncio.Future[Any]) -> None:
    try:
        operation.result()
    except BaseException:
        pass


class _CancelledDependency(Exception):
    """Internal marker for cancellation while loading or resolving injected data."""


async def _await_injected(awaitable: Awaitable[_T], cancel: CancelToken) -> _T:
    """Await a loader or resolver through the shared cancellation owner."""

    result = await _await_network(awaitable, cancel)
    if result is None and cancel.cancelled:
        raise _CancelledDependency
    return result  # type: ignore[return-value]


async def read_response_body(
    response: httpx.Response,
    cancel: CancelToken,
    *,
    max_bytes: int = 64 * 1024,
    capture: ResponseCapture | None = None,
) -> str | None:
    """Read an error body through the shared cancellation owner with a byte cap.

    ``capture`` sees every chunk this read takes, and nothing more: it never reads on its own, so the text, the
    error's classification, and the time it takes are what they are without capture.
    """

    iterator = response.aiter_bytes().__aiter__()
    chunks: list[bytes] = []
    size = 0
    while size < max_bytes:
        try:
            chunk = await _await_network(
                iterator.__anext__(),
                cancel,
                timeout_s=PROVIDER_SILENCE_TIMEOUT_S,
            )
        except StopAsyncIteration:
            if capture is not None:
                capture.finish()
            break
        if chunk is None:
            return None
        if not chunk:
            continue
        if capture is not None:
            capture.feed(chunk)
        remaining = max_bytes - size
        piece = bytes(chunk[:remaining])
        chunks.append(piece)
        size += len(piece)
        if len(piece) < len(chunk):
            break
    return b"".join(chunks).decode("utf-8", errors="replace")


@dataclass(frozen=True)
class PreparedMessages:
    """The compiled history, its immutable media snapshots, and the legacy rows this exact render omitted."""

    messages: tuple[Any, ...]
    loaded_images: dict[str, LoadedImage]
    hosted_render_omitted: tuple[str, ...]


async def prepare_messages(
    messages: tuple[Any, ...],
    *,
    target: Any,
    supports_images: bool,
    protocol: str,
    media_loader: MediaLoader | None,
    cancel: CancelToken,
    endpoint: ModelEndpoint | None = None,
) -> PreparedMessages | ProviderError:
    """Transform history and resolve immutable media snapshots as one safe boundary."""

    try:
        from core.agent_core.ai.transform import transform_messages

        transformed = transform_messages(
            messages,
            target=target,
            supports_images=supports_images,
            protocol=protocol,
            endpoint=endpoint,
        )
        loaded_images = await load_images(transformed.messages, media_loader, cancel)
    except _CancelledDependency:
        return ProviderError(
            kind="aborted",
            message=cancel.reason or "provider request aborted",
            retryable=False,
        )
    except Exception as exc:
        # Preparation is local: diagnostic text resembling a transient upstream error grants no permission.
        return replace(
            classify_error(body=f"request preparation failed: {type(exc).__name__}: {exc}"),
            retryable=False,
            continuable=False,
        )
    return PreparedMessages(transformed.messages, loaded_images, transformed.hosted_render_omitted)


class _suppress_cancelled:
    def __enter__(self) -> None:
        return None

    def __exit__(self, exception_type: type[BaseException] | None, exception: BaseException | None, traceback: Any) -> bool:
        return exception_type is asyncio.CancelledError


def json_object(data: str) -> dict[str, Any] | None:
    try:
        value = json.loads(data)
    except (TypeError, ValueError):
        return None
    return value if isinstance(value, dict) else None


def image_data(block: ImageBlock) -> str:
    """Resolve the in-memory media token form used by hermetic adapter tests."""

    token = block.media_token
    if token.startswith("data:") and ";base64," in token:
        return token.split(";base64,", 1)[1]
    if token.startswith("data:,"):
        return base64.b64encode(unquote_to_bytes(token[6:])).decode("ascii")
    return token


async def load_image_data(
    block: ImageBlock,
    media_loader: MediaLoader | None,
    cancel: CancelToken | None = None,
) -> tuple[str, str]:
    """Resolve a media token just before the request is sent."""

    if media_loader is not None:
        if cancel is None:
            raw, mime_type = await media_loader.load(block.media_token)
        else:
            raw, mime_type = await _await_injected(media_loader.load(block.media_token), cancel)
        return base64.b64encode(raw).decode("ascii"), mime_type
    return image_data(block), block.mime_type


async def load_images(
    messages: tuple[Any, ...],
    media_loader: MediaLoader | None,
    cancel: CancelToken,
) -> dict[str, LoadedImage]:
    """Load every image token once for a request, fitted to the providers' per-image size limit (``image_limits``)."""

    if media_loader is None:
        return {}
    tokens: list[str] = []
    for message in messages:
        content = getattr(message, "content", ())
        for block in content:
            if isinstance(block, ImageBlock) and block.media_token not in tokens:
                tokens.append(block.media_token)
    loaded: dict[str, LoadedImage] = {}
    for token in tokens:
        raw, mime_type = await _await_injected(media_loader.load(token), cancel)
        loaded[token] = await _await_injected(asyncio.to_thread(fit_image, raw, mime_type), cancel)
    return loaded


def text_from_content(content: tuple[UserContent, ...]) -> str:
    parts: list[str] = []
    for block in content:
        if isinstance(block, TextBlock):
            parts.append(block.text or "")
    return "\n".join(part for part in parts if part)


def content_parts(
    content: tuple[UserContent, ...],
    *,
    include_images: bool = True,
    loaded_images: Mapping[str, LoadedImage] | None = None,
) -> list[dict[str, Any]]:
    result: list[dict[str, Any]] = []
    for block in content:
        if isinstance(block, TextBlock):
            if block.text:
                result.append({"type": "text", "text": block.text})
        elif isinstance(block, ImageBlock) and include_images:
            loaded = (loaded_images or {}).get(block.media_token) or LoadedImage(image_data(block), block.mime_type)
            if loaded.data is not None:
                image = {"type": "image", "mime_type": loaded.mime_type, "data": loaded.data}
                result.append({**image, "media_token": block.media_token})
            if loaded.note:
                result.append({"type": "text", "text": loaded.note})
    return result


def tool_schema(tool: Any) -> dict[str, Any]:
    return {
        "name": tool.name,
        "description": tool.description,
        "input_schema": dict(tool.input_schema),
    }


def parsed_arguments(raw: str, *, tool_name: str = "") -> dict[str, Any] | ProviderError:
    if not raw:
        return {}
    try:
        value = json.loads(raw)
    except (TypeError, ValueError):
        return _malformed_arguments(tool_name)
    if not isinstance(value, dict):
        return _malformed_arguments(tool_name)
    return value


def _malformed_arguments(tool_name: str) -> ProviderError:
    suffix = f" for tool {tool_name}" if tool_name else ""
    return ProviderError(
        kind="invalid_request",
        message=f"malformed tool arguments{suffix}: expected a JSON object",
        retryable=False,
    )


def assistant_message(
    content: list[AssistantContent],
    *,
    origin: Origin,
    stop_reason: str,
    usage: Any = None,
    error_message: str | None = None,
    verified_origin: bool = True,
    hosted_summary: HostedSummary | None = None,
    source_identity: str | None = None,
) -> AssistantMessage:
    if not verified_origin:
        sanitized: list[AssistantContent] = []
        for block in content:
            if isinstance(block, ThinkingBlock):
                if block.redacted:
                    continue
                sanitized.append(replace(block, signature=None))
            elif isinstance(block, ToolCallBlock):
                sanitized.append(replace(block, signature=None))
            elif isinstance(block, HostedToolBlock):
                # A hosted call is its native payload, opaque provider content that no unverified origin replays.
                continue
            else:
                sanitized.append(block)
        content = sanitized
    if not any(isinstance(block, HostedToolBlock) for block in content):
        hosted_summary = None
    return AssistantMessage(
        content=tuple(content),
        origin=origin,
        stop_reason=stop_reason,  # type: ignore[arg-type]
        usage=usage,
        error_message=error_message,
        hosted_summary=hosted_summary,
        # An unverified origin names no Source its opaque payloads could go back to; it keeps none anyway.
        source_identity=source_identity if verified_origin else None,
    )


#: A failed response's committed partial keeps the error it ended with (C-1 ``error_message``), so its transcript row
#: says why the response ended. Bounded after redaction: a non-JSON error body can be a whole page.
PARTIAL_ERROR_MESSAGE_CHARS = 1000


def _partial_with_error(error: ProviderError) -> ProviderError:
    """The provider's error text on the partial it leaves; a Stop's partial needs none."""
    partial = error.partial
    if partial is None or error.kind == "aborted":
        return error
    if partial.error_kind != error.kind:
        partial = replace(partial, error_kind=error.kind)
    if partial.error_message is not None or not error.message:
        return replace(error, partial=partial)
    return replace(error, partial=replace(partial, error_message=error.message))


def _bounded_partial_error(error: ProviderError) -> ProviderError:
    partial = error.partial
    if partial is None or partial.error_message is None or len(partial.error_message) <= PARTIAL_ERROR_MESSAGE_CHARS:
        return error
    text = partial.error_message[: PARTIAL_ERROR_MESSAGE_CHARS - 1] + "…"
    return replace(error, partial=replace(partial, error_message=text))


def partial_message(
    content: list[AssistantContent],
    *,
    origin: Origin,
    usage: Any = None,
    verified_origin: bool = True,
    stop_reason: str = "aborted",
    hosted_summary: HostedSummary | None = None,
    source_identity: str | None = None,
) -> AssistantMessage:
    if stop_reason in {"aborted", "error"}:
        content = [block for block in content if not isinstance(block, ToolCallBlock)]
    return assistant_message(
        content,
        origin=origin,
        stop_reason=stop_reason,
        usage=usage,
        verified_origin=verified_origin,
        hosted_summary=hosted_summary,
        source_identity=source_identity,
    )


def _default_provider(protocol: str) -> str:
    return {
        "anthropic": "anthropic",
        "openai_chat": "openai",
        "openai_responses": "openai",
        "google": "google",
    }.get(protocol, protocol)