Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

67.5 KB
Raw Blame
from __future__ import annotations

import asyncio
import base64
import builtins
import json
from types import SimpleNamespace
from unittest.mock import patch

import httpx
import pytest
from fastapi.responses import StreamingResponse

from headroom.proxy.handlers.anthropic import AnthropicHandlerMixin, _is_googleapis_endpoint
from headroom.proxy.handlers.openai import (
    OpenAIHandlerMixin,
    _decode_openai_bearer_payload,
    _passthrough_usage_from_json,
    _prefers_http1_passthrough,
    prefers_http1_passthrough,
)
from headroom.proxy.handlers.streaming import StreamingMixin
from headroom.proxy.helpers import (
    _headroom_bypass_enabled,
    is_third_party_model,
    relocate_system_messages_to_top_level,
)
from headroom.proxy.outcome import emit_request_outcome
from headroom.proxy.server import HeadroomProxy


def _jwt(payload: object) -> str:
    header = {"alg": "none", "typ": "JWT"}

    def encode(part: object) -> str:
        raw = json.dumps(part, separators=(",", ":")).encode("utf-8")
        return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")

    return f"{encode(header)}.{encode(payload)}."


@pytest.mark.parametrize(
    ("url", "expected"),
    [
        ("https://us-central1-aiplatform.googleapis.com/v1", True),
        ("https://googleapis.com/v1", True),
        ("https://AIPLATFORM.GOOGLEAPIS.COM./v1", True),
        ("https://googleapis.com.example.test/v1", False),
        ("https://notgoogleapis.com/v1", False),
        ("https://[email protected]/v1", False),
        ("not a url", False),
        ("", False),
    ],
)
def test_googleapis_endpoint_gate_uses_hostname_boundary(url: str, expected: bool) -> None:
    assert _is_googleapis_endpoint(url) is expected


class _ImageCompressor:
    def __init__(self, compressed_message):
        self._compressed_message = compressed_message

    def compress(self, messages, provider):  # noqa: ANN001, ANN201
        assert provider == "anthropic"
        return [self._compressed_message]


class _FreshCompressor:
    instances = 0

    def __init__(self):
        type(self).instances += 1


class _TimeoutHttpClient:
    async def request(self, **kwargs):  # noqa: ANN001, ANN201
        raise httpx.ConnectTimeout("connect timed out")


class _RecordingHttpClient:
    def __init__(self, label: str) -> None:
        self.label = label
        self.calls = 0

    async def request(self, **kwargs):  # noqa: ANN001, ANN201
        self.calls += 1
        request = httpx.Request(kwargs["method"], kwargs["url"])
        return httpx.Response(
            200,
            request=request,
            headers={"content-type": "application/json"},
            json={"client": self.label},
        )


class _ChatGPTAccountRequest:
    method = "GET"
    headers = {}
    url = SimpleNamespace(path="/backend-api/me", query="")

    async def body(self) -> bytes:
        return b""


class _PassthroughRequest:
    method = "GET"
    headers = {}
    url = SimpleNamespace(path="/some/other/path", query="")

    async def body(self) -> bytes:
        return b""


class _VertexPassthroughRequest:
    method = "POST"
    headers = {}
    url = SimpleNamespace(
        path="/v1/projects/p/locations/us-central1/publishers/google/models/gemini-2.0-flash:generateContent",
        query="",
    )

    async def body(self) -> bytes:
        return b'{"contents":[]}'


class _VertexStreamPassthroughRequest:
    method = "POST"
    headers = {}
    url = SimpleNamespace(
        path="/v1/projects/p/locations/us-central1/publishers/google/models/gemini-2.0-flash:streamGenerateContent",
        query="alt=sse",
    )

    async def body(self) -> bytes:
        return b'{"contents":[]}'


class _VertexGeminiImageRequest:
    method = "POST"
    headers = {}
    query_params = {}
    scope: dict = {"type": "http", "method": "POST"}
    url = SimpleNamespace(
        path="/v1/projects/p/locations/us-central1/publishers/google/models/gemini-2.0-flash:generateContent",
        query="",
    )

    async def stream(self):
        yield await self.body()

    async def body(self) -> bytes:
        return json.dumps(
            {
                "contents": [
                    {
                        "role": "user",
                        "parts": [
                            {
                                "inlineData": {
                                    "mimeType": "image/png",
                                    "data": "aW1hZ2U=",
                                }
                            }
                        ],
                    }
                ]
            }
        ).encode("utf-8")


class _VertexUsageClient:
    async def request(self, **kwargs):  # noqa: ANN001, ANN201
        request = httpx.Request(kwargs["method"], kwargs["url"], content=kwargs["content"])
        return httpx.Response(
            200,
            request=request,
            headers={"content-type": "application/json"},
            json={
                "candidates": [{"content": {"parts": [{"text": "ok"}]}}],
                "usageMetadata": {
                    "promptTokenCount": 11,
                    "candidatesTokenCount": 7,
                    "cachedContentTokenCount": 3,
                },
            },
        )


class _AsyncChunks(httpx.AsyncByteStream):
    def __init__(self, chunks: list[bytes]) -> None:
        self._chunks = chunks

    async def __aiter__(self):  # noqa: ANN204
        for chunk in self._chunks:
            yield chunk


class _VertexStreamClient:
    def __init__(self) -> None:
        self.sent_url = ""

    def build_request(self, method, url, headers, content):  # noqa: ANN001, ANN201
        self.sent_url = str(url)
        return httpx.Request(method, url, headers=headers, content=content)

    async def send(self, request, stream=False):  # noqa: ANN001, ANN201
        assert stream is True
        return httpx.Response(
            200,
            request=request,
            headers={"content-type": "text/event-stream"},
            stream=_AsyncChunks(
                [
                    b'data: {"candidates":[{"content":{"parts":[{"text":"hello"}]}}]}\n\n',
                    b'data: {"usageMetadata":{"promptTokenCount":13,'
                    b'"candidatesTokenCount":5,"cachedContentTokenCount":2}}\n\n',
                ]
            ),
        )


class _RetryThenSuccessClient:
    def __init__(self) -> None:
        self.attempts = 0

    async def post(self, url, content, headers, timeout=None):  # noqa: ANN001, ANN201
        self.attempts += 1
        if self.attempts == 1:
            raise httpx.ConnectTimeout("connect timed out")
        del timeout
        request = httpx.Request("POST", url, headers=headers, content=content)
        return httpx.Response(200, request=request, content=b"{}")


def test_decode_openai_bearer_payload_handles_missing_and_non_mapping_payloads() -> None:
    assert _decode_openai_bearer_payload({}) is None
    assert _decode_openai_bearer_payload({"authorization": "Basic abc"}) is None
    assert (
        _decode_openai_bearer_payload({"authorization": f"Bearer {_jwt(['not', 'a', 'dict'])}"})
        is None
    )


def test_openai_handler_prefix_helpers_cover_edge_cases() -> None:
    assert OpenAIHandlerMixin._strict_previous_turn_frozen_count([], 2) == 2
    assert (
        OpenAIHandlerMixin._strict_previous_turn_frozen_count(
            [{"role": "assistant"}, {"role": "user"}],
            0,
        )
        == 1
    )
    assert (
        OpenAIHandlerMixin._strict_previous_turn_frozen_count(
            [{"role": "assistant"}, {"role": "tool", "content": "observation"}],
            0,
        )
        == 1
    )
    assert (
        OpenAIHandlerMixin._strict_previous_turn_frozen_count(
            [{"role": "user"}, {"role": "assistant"}, {"role": "tool", "content": "obs"}],
            3,
        )
        == 2
    )
    assert (
        OpenAIHandlerMixin._strict_previous_turn_frozen_count(
            [{"role": "assistant"}, {"role": "function", "content": "legacy observation"}],
            0,
        )
        == 1
    )
    assert (
        OpenAIHandlerMixin._strict_previous_turn_frozen_count(
            [{"role": "user"}, {"role": "assistant"}],
            0,
        )
        == 2
    )

    original = [{"role": "system", "content": "keep"}, {"role": "user", "content": "hello"}]
    restored, changed = OpenAIHandlerMixin._restore_frozen_prefix(
        original,
        [],
        frozen_message_count=1,
    )
    assert restored == [{"role": "system", "content": "keep"}]
    assert changed == 1

    restored, changed = OpenAIHandlerMixin._restore_frozen_prefix(
        original,
        [{"role": "system", "content": "changed"}, {"role": "user", "content": "hello"}],
        frozen_message_count=1,
    )
    assert restored == original
    assert changed == 1


def test_relocate_system_messages_moves_stray_system_into_top_level() -> None:
    # Issue #765: compression relocated the harness system block into
    # messages[0] as a role="system" entry, which Anthropic rejects with a 400.
    # The forwarder guard must move it back to the top-level `system` parameter.
    messages = [
        {"role": "system", "content": "You are a harness."},
        {"role": "user", "content": "hi"},
    ]
    clean, system, changed = relocate_system_messages_to_top_level(messages, None)

    assert changed is True
    # No role="system" entry may survive in messages[] — that is the wire-contract violation.
    assert all(m.get("role") != "system" for m in clean)
    assert clean == [{"role": "user", "content": "hi"}]
    # The relocated content lands in the top-level system parameter.
    assert system == [{"type": "text", "text": "You are a harness."}]


def test_relocate_system_messages_appends_to_existing_system() -> None:
    messages = [
        {"role": "system", "content": [{"type": "text", "text": "B"}]},
        {"role": "user", "content": "hi"},
    ]
    clean, system, changed = relocate_system_messages_to_top_level(messages, "A")

    assert changed is True
    assert clean == [{"role": "user", "content": "hi"}]
    # Existing system first, relocated content after — wire order preserved.
    assert system == [{"type": "text", "text": "A"}, {"type": "text", "text": "B"}]


def test_relocate_system_messages_noop_without_system_entry() -> None:
    messages = [{"role": "user", "content": "hi"}]
    clean, system, changed = relocate_system_messages_to_top_level(messages, "A")

    assert changed is False
    assert clean is messages
    assert system == "A"


@pytest.mark.parametrize(
    "model",
    [
        "claude-opus-5",
        # Claude Haiku 5.5 supports mid-conversation system messages too; it was
        # missing here, so Claude Code's Haiku subagent traffic had every valid
        # section hoisted into the top-level system prompt.
        "claude-haiku-5-5",
    ],
)
def test_relocate_system_messages_preserves_valid_mid_conversation_section(model: str) -> None:
    messages = [
        {"role": "user", "content": "Run the tests."},
        {
            "role": "system",
            "content": "The user added: update the changelog too.",
        },
        {"role": "assistant", "content": "I will do both."},
    ]

    clean, system, changed = relocate_system_messages_to_top_level(messages, "base", model)

    assert changed is False
    assert clean is messages
    assert system == "base"


def test_relocate_system_messages_preserves_consecutive_valid_section_at_end() -> None:
    messages = [
        {"role": "user", "content": [{"type": "tool_result", "content": "ok"}]},
        {"role": "system", "content": "First update."},
        {"role": "system", "content": "Second update."},
    ]

    clean, system, changed = relocate_system_messages_to_top_level(
        messages, None, "global.anthropic.claude-sonnet-5-v1:0"
    )

    assert changed is False
    assert clean is messages
    assert system is None


@pytest.mark.parametrize(
    "messages",
    [
        [
            {"role": "assistant", "content": "answer"},
            {"role": "system", "content": "bad predecessor"},
        ],
        [
            {"role": "user", "content": "question"},
            {"role": "system", "content": "bad successor"},
            {"role": "user", "content": "another question"},
        ],
    ],
)
def test_relocate_system_messages_still_moves_invalid_mid_conversation_placement(
    messages: list[dict],
) -> None:
    clean, system, changed = relocate_system_messages_to_top_level(messages, None, "claude-fable-5")

    assert changed is True
    assert all(message.get("role") != "system" for message in clean)
    assert system == [{"type": "text", "text": messages[1]["content"]}]


@pytest.mark.parametrize("model", ["claude-sonnet-4-6", "claude-haiku-4-5"])
def test_relocate_system_messages_moves_valid_shape_for_unsupported_model(model: str) -> None:
    messages = [
        {"role": "user", "content": "question"},
        {"role": "system", "content": "mid-turn instruction"},
    ]

    clean, system, changed = relocate_system_messages_to_top_level(messages, None, model)

    assert changed is True
    assert clean == [{"role": "user", "content": "question"}]
    assert system == [{"type": "text", "text": "mid-turn instruction"}]


@pytest.mark.parametrize(
    ("model", "third_party_upstream", "expected"),
    [
        ("qwen3.8-flash-next", True, True),
        ("glm-5.3", True, True),
        # Claude-named models behind a gateway keep the conservative hoist.
        ("claude-opus-5", True, False),
        ("anthropic/claude-sonnet-4-6", True, False),
        ("global.anthropic.claude-sonnet-5-v1:0", True, False),
        # Anthropic itself (or Vertex / a backend) keeps the model allow-list.
        ("qwen3.8-flash-next", False, False),
    ],
)
def test_is_third_party_model(model: str, third_party_upstream: bool, expected: bool) -> None:
    assert is_third_party_model(model, third_party_upstream=third_party_upstream) is expected


def test_relocate_system_messages_keeps_valid_sections_for_third_party_model() -> None:
    # #3552 kept non-text blocks in place for third-party upstreams, but text
    # sections were still hoisted for every model there. A client that appends a
    # section most turns changed the top-level system prompt on each request, and
    # the upstream's prefix cache missed the whole conversation every turn.
    messages = [
        {"role": "user", "content": "Run the tests."},
        {"role": "system", "content": "The user added: update the changelog too."},
        {"role": "assistant", "content": "I will do both."},
        {"role": "user", "content": [{"type": "tool_result", "content": "ok"}]},
        {"role": "system", "content": "<system-reminder>todo list changed</system-reminder>"},
    ]

    clean, system, changed = relocate_system_messages_to_top_level(
        messages, "base", "qwen3.8-flash-next", third_party_model=True
    )

    assert changed is False
    assert clean is messages
    assert system == "base"


@pytest.mark.parametrize(
    "messages",
    [
        # The #765 case: a system block left at messages[0] is invalid anywhere.
        [
            {"role": "system", "content": "You are a harness."},
            {"role": "user", "content": "hi"},
        ],
        [
            {"role": "assistant", "content": "answer"},
            {"role": "system", "content": "You are a harness."},
        ],
    ],
)
def test_relocate_system_messages_still_moves_invalid_placement_for_third_party_model(
    messages: list[dict],
) -> None:
    clean, system, changed = relocate_system_messages_to_top_level(
        messages, None, "qwen3.8-flash-next", third_party_model=True
    )

    assert changed is True
    assert all(message.get("role") != "system" for message in clean)
    assert system == [{"type": "text", "text": "You are a harness."}]


def test_relocate_system_messages_keeps_image_blocks_out_of_top_level_system() -> None:
    image_block = {
        "type": "image",
        "source": {"type": "base64", "media_type": "image/png", "data": "aGk="},
    }
    messages = [
        {"role": "user", "content": [{"type": "text", "text": "look at this"}]},
        {
            "role": "system",
            "content": [
                {"type": "text", "text": "<system-reminder>image attached</system-reminder>"},
                image_block,
            ],
        },
        {"role": "assistant", "content": [{"type": "text", "text": "ok"}]},
        {"role": "user", "content": [{"type": "text", "text": "hi"}]},
    ]
    system = [{"type": "text", "text": "You are Claude Code."}]

    clean, new_system, changed = relocate_system_messages_to_top_level(messages, system, None)

    assert changed is True
    assert isinstance(new_system, list)
    assert all(not isinstance(block, dict) or block.get("type") == "text" for block in new_system)
    retained = [
        message.get("content")
        for message in clean
        if isinstance(message, dict) and message.get("role") == "system"
    ]
    assert any(image_block in (content or []) for content in retained)


def test_relocate_system_messages_hoists_only_text_from_mixed_sections() -> None:
    messages = [
        {"role": "user", "content": "question"},
        {
            "role": "system",
            "content": [
                "plain string section",
                {"type": "text", "text": "structured note"},
                {"type": "image", "source": {"type": "url", "url": "https://x/y.png"}},
            ],
        },
        {"role": "assistant", "content": "ok"},
    ]

    clean, new_system, changed = relocate_system_messages_to_top_level(messages, None, None)

    assert changed is True
    assert new_system == [
        {"type": "text", "text": "plain string section"},
        {"type": "text", "text": "structured note"},
    ]
    retained = [
        message
        for message in clean
        if isinstance(message, dict) and message.get("role") == "system"
    ]
    assert retained == [
        {
            "role": "system",
            "content": [{"type": "image", "source": {"type": "url", "url": "https://x/y.png"}}],
        }
    ]


def test_relocate_system_messages_image_only_sections_pass_through_unchanged() -> None:
    image_block = {
        "type": "image",
        "source": {"type": "base64", "media_type": "image/png", "data": "aGk="},
    }
    messages = [
        {"role": "user", "content": "question"},
        {"role": "system", "content": [image_block]},
        {"role": "assistant", "content": "ok"},
    ]
    system = "base"

    clean, new_system, changed = relocate_system_messages_to_top_level(messages, system, None)

    assert changed is False
    assert clean == messages
    assert new_system == system


def test_relocate_system_messages_drops_non_text_from_leading_section(
    caplog: pytest.LogCaptureFixture,
) -> None:
    image_block = {
        "type": "image",
        "source": {"type": "base64", "media_type": "image/png", "data": "aGk="},
    }
    cached_text = {
        "type": "text",
        "text": "leading instruction",
        "cache_control": {"type": "ephemeral"},
    }
    messages: list[dict] = [
        {"role": "system", "content": [cached_text, image_block]},
        {"role": "user", "content": "hi"},
    ]

    caplog.set_level("WARNING", logger="headroom.proxy")
    clean, new_system, changed = relocate_system_messages_to_top_level(
        messages, [{"type": "text", "text": "base"}], "claude-opus-5"
    )

    assert changed is True
    assert clean == [{"role": "user", "content": "hi"}]
    assert new_system == [
        {"type": "text", "text": "base"},
        cached_text,
    ]
    assert "event=system_relocation_block_dropped" in caplog.text
    assert "block_type=image" in caplog.text


def test_relocate_system_messages_drops_all_non_text_leading_section() -> None:
    image_block = {
        "type": "image",
        "source": {"type": "base64", "media_type": "image/png", "data": "aGk="},
    }
    messages: list[dict] = [
        {"role": "system", "content": [image_block]},
        {"role": "user", "content": "hi"},
    ]

    clean, new_system, changed = relocate_system_messages_to_top_level(
        messages, [{"type": "text", "text": "base"}], "claude-opus-5"
    )

    assert changed is True
    assert clean == [{"role": "user", "content": "hi"}]
    assert new_system == [{"type": "text", "text": "base"}]


@pytest.mark.parametrize("block_type", ["text", "image", "tool_use", "tool_result", None])
def test_leading_system_text_uses_only_anthropic_text_block_fields(block_type) -> None:
    from copy import deepcopy

    cache_control = {"type": "ephemeral", "ttl": "1h"}
    citations = [
        {
            "type": "char_location",
            "cited_text": "instruction",
            "document_index": 0,
            "document_title": "source",
            "start_char_index": 0,
            "end_char_index": 11,
        }
    ]
    block = {
        "type": block_type,
        "text": "instruction",
        "cache_control": cache_control,
        "citations": citations,
        "source": {"type": "url", "url": "https://example.invalid/image.png"},
        "id": "tool1",
        "name": "read",
        "input": {"path": "file.txt"},
        "tool_use_id": "tool1",
        "is_error": False,
    }
    messages = [
        {"role": "system", "content": [block]},
        {"role": "user", "content": "hi"},
    ]
    original = deepcopy(messages)
    clean, system, changed = relocate_system_messages_to_top_level(messages, None, None)
    assert changed
    assert clean == [{"role": "user", "content": "hi"}]
    assert system == [
        {
            "type": "text",
            "text": "instruction",
            "cache_control": cache_control,
            "citations": citations,
        }
    ]
    assert messages == original


def test_all_contiguous_leading_system_sections_are_normalized() -> None:
    image = {"type": "image", "source": {"type": "url", "url": "https://example.invalid/a"}}
    clean, system, changed = relocate_system_messages_to_top_level(
        [
            {"role": "system", "content": "first instruction"},
            {"role": "system", "content": [image]},
            {"role": "system", "content": [{"type": "text", "text": "second instruction"}]},
            {"role": "user", "content": "hi"},
        ],
        None,
        None,
    )
    assert changed
    assert clean == [{"role": "user", "content": "hi"}]
    assert system == [
        {"type": "text", "text": "first instruction"},
        {"type": "text", "text": "second instruction"},
    ]


def test_headroom_bypass_helper_is_transport_neutral() -> None:
    assert _headroom_bypass_enabled({"x-headroom-bypass": "true"}) is True
    assert _headroom_bypass_enabled({"x-headroom-bypass": " TRUE "}) is True
    assert _headroom_bypass_enabled({"x-headroom-mode": "passthrough"}) is True
    assert _headroom_bypass_enabled({"x-headroom-mode": " PASSTHROUGH "}) is True
    assert _headroom_bypass_enabled({"x-headroom-bypass": "false"}) is False
    assert _headroom_bypass_enabled({}) is False
    assert _headroom_bypass_enabled(None) is False
    assert OpenAIHandlerMixin._headroom_bypass_enabled({"x-headroom-bypass": "true"}) is True


def test_openai_passthrough_without_config_preserves_generic_request() -> None:
    handler = object.__new__(OpenAIHandlerMixin)
    handler.http_client = _RecordingHttpClient("h2")
    request = _PassthroughRequest()

    response = asyncio.run(handler.handle_passthrough(request, "https://api.openai.com"))

    assert response.status_code == 200
    assert json.loads(response.body)["client"] == "h2"


def test_openai_passthrough_connect_timeout_returns_502() -> None:
    handler = object.__new__(OpenAIHandlerMixin)
    handler.http_client = _TimeoutHttpClient()

    async def run():
        return await handler.handle_passthrough(
            _PassthroughRequest(),
            "https://api.openai.com",
        )

    response = asyncio.run(run())

    assert response.status_code == 502
    payload = json.loads(response.body)
    assert payload["error"]["type"] == "connection_error"
    assert "Failed to connect to upstream API" in payload["error"]["message"]


def test_prefers_http1_passthrough_matches_chatgpt_hosts_only() -> None:
    assert _prefers_http1_passthrough("https://chatgpt.com") is True
    assert _prefers_http1_passthrough("https://chatgpt.com/backend-api/me") is True
    assert _prefers_http1_passthrough("https://api.chatgpt.com") is True
    assert _prefers_http1_passthrough("https://CHATGPT.COM/backend-api/me") is True
    assert _prefers_http1_passthrough("https://api.openai.com") is False
    assert _prefers_http1_passthrough("https://notchatgpt.com") is False
    assert _prefers_http1_passthrough("https://chatgpt.com.evil.com") is False
    assert _prefers_http1_passthrough("") is False


def test_chatgpt_passthrough_uses_http1_client() -> None:
    handler = object.__new__(OpenAIHandlerMixin)
    handler.http_client = _RecordingHttpClient("h2")
    handler.http_client_h1 = _RecordingHttpClient("h1")

    response = asyncio.run(
        handler.handle_passthrough(_ChatGPTAccountRequest(), "https://chatgpt.com")
    )

    assert response.status_code == 200
    assert json.loads(response.body)["client"] == "h1"
    assert handler.http_client.calls == 0
    assert handler.http_client_h1.calls == 1


def test_non_chatgpt_passthrough_uses_default_client() -> None:
    handler = object.__new__(OpenAIHandlerMixin)
    handler.http_client = _RecordingHttpClient("h2")
    handler.http_client_h1 = _RecordingHttpClient("h1")

    response = asyncio.run(
        handler.handle_passthrough(_PassthroughRequest(), "https://api.openai.com")
    )

    assert response.status_code == 200
    assert json.loads(response.body)["client"] == "h2"
    assert handler.http_client.calls == 1
    assert handler.http_client_h1.calls == 0


def test_chatgpt_passthrough_falls_back_when_h1_client_missing() -> None:
    handler = object.__new__(OpenAIHandlerMixin)
    handler.http_client = _RecordingHttpClient("h2")
    handler.http_client_h1 = None

    response = asyncio.run(
        handler.handle_passthrough(_ChatGPTAccountRequest(), "https://chatgpt.com")
    )

    assert response.status_code == 200
    assert json.loads(response.body)["client"] == "h2"
    assert handler.http_client.calls == 1


def test_streaming_client_selection() -> None:
    assert prefers_http1_passthrough("https://chatgpt.com/backend-api/codex/responses") is True
    assert prefers_http1_passthrough("https://api.openai.com/v1/chat/completions") is False

    mixin = object.__new__(StreamingMixin)
    mixin.http_client = "h2"
    mixin.http_client_h1 = "h1"

    assert mixin._select_streaming_client("https://chatgpt.com/backend-api/codex/responses") == "h1"
    assert mixin._select_streaming_client("https://api.openai.com/v1/chat/completions") == "h2"

    mixin.http_client_h1 = None
    assert mixin._select_streaming_client("https://chatgpt.com/backend-api/codex/responses") == "h2"


@pytest.mark.asyncio
async def test_retry_request_selects_http1_for_chatgpt(monkeypatch) -> None:
    calls = []

    class DummyClient:
        def __init__(self, name: str):
            self.name = name

        async def post(self, url, **kwargs):
            calls.append((self.name, url))
            return httpx.Response(200, json={"ok": True})

    proxy = object.__new__(HeadroomProxy)
    proxy.config = type("Config", (), {"retry_max_attempts": 1, "retry_enabled": False})()
    proxy.http_client = DummyClient("h2")
    proxy.http_client_h1 = DummyClient("h1")

    await proxy._retry_request("POST", "https://chatgpt.com/backend-api/codex/responses", {}, {})
    assert calls == [("h1", "https://chatgpt.com/backend-api/codex/responses")]

    calls.clear()
    await proxy._retry_request("POST", "https://api.openai.com/v1/chat/completions", {}, {})
    assert calls == [("h2", "https://api.openai.com/v1/chat/completions")]


@pytest.mark.asyncio
async def test_proxy_routes_openai_responses_subpath_selects_http1(monkeypatch) -> None:
    from fastapi import FastAPI
    from fastapi.testclient import TestClient

    from headroom.providers.openai_responses import OpenAIResponsesSubpathRoute
    from headroom.providers.proxy_routes import _register_openai_responses_subpath_route

    received_clients = []

    async def fake_subpath(http_client, request, sub_path):
        received_clients.append(http_client)
        return httpx.Response(200, json={"ok": True})

    monkeypatch.setattr(
        "headroom.providers.proxy_routes.handle_chatgpt_codex_responses_subpath",
        fake_subpath,
    )

    app = FastAPI()
    proxy = type("Proxy", (), {"http_client": "h2", "http_client_h1": "h1"})()
    spec = OpenAIResponsesSubpathRoute(
        path="/v1/responses/{sub_path:path}",
        methods=("GET", "POST"),
    )
    _register_openai_responses_subpath_route(app, proxy, spec)

    client = TestClient(app)
    client.get("/v1/responses/items/resp_1")
    assert received_clients == ["h1"]


def test_passthrough_usage_normalizes_vertex_usage_metadata() -> None:
    usage = _passthrough_usage_from_json(
        {
            "usageMetadata": {
                "promptTokenCount": 11,
                "candidatesTokenCount": 7,
                "cachedContentTokenCount": 3,
            }
        }
    )

    assert usage == {
        "input_tokens": 11,
        "output_tokens": 7,
        "cache_read_input_tokens": 3,
    }


def test_gemini_output_tokens_includes_thinking_when_exclusive() -> None:
    """Gemini 2.5 thinking: when prompt + candidates != total, thoughtsTokenCount
    is a separate output bucket and must be added, or output cost undercounts."""
    from headroom.proxy.token_counting import gemini_output_tokens

    exclusive = {
        "promptTokenCount": 1000,
        "candidatesTokenCount": 200,
        "thoughtsTokenCount": 500,
        "totalTokenCount": 1700,
    }
    assert gemini_output_tokens(exclusive) == 700  # 200 visible + 500 thinking

    # Inclusive: candidatesTokenCount already covers thoughts (prompt+cand==total).
    inclusive = {
        "promptTokenCount": 1000,
        "candidatesTokenCount": 700,
        "thoughtsTokenCount": 500,
        "totalTokenCount": 1700,
    }
    assert gemini_output_tokens(inclusive) == 700

    # No thinking tokens: just the candidates count (common non-2.5 case).
    assert gemini_output_tokens({"candidatesTokenCount": 42, "totalTokenCount": 100}) == 42
    # Robust to empty / missing fields.
    assert gemini_output_tokens({}) == 0


def test_passthrough_usage_counts_gemini_thinking_tokens() -> None:
    """_passthrough_usage_from_json must include thinking tokens in output_tokens."""
    usage = _passthrough_usage_from_json(
        {
            "usageMetadata": {
                "promptTokenCount": 1000,
                "candidatesTokenCount": 200,
                "thoughtsTokenCount": 500,
                "totalTokenCount": 1700,
                "cachedContentTokenCount": 100,
            }
        }
    )
    assert usage["output_tokens"] == 700
    assert usage["input_tokens"] == 1000


def test_vertex_passthrough_records_usage_metadata_for_dashboard() -> None:
    handler = object.__new__(HeadroomProxy)
    handler.http_client = _VertexUsageClient()
    outcomes = []

    async def next_request_id():  # noqa: ANN202
        return "req_vertex"

    async def record(outcome):  # noqa: ANN001, ANN202
        outcomes.append(outcome)

    handler._next_request_id = next_request_id
    handler._record_request_outcome = record

    response = asyncio.run(
        handler.handle_passthrough(
            _VertexPassthroughRequest(),
            "https://vertex.test",
            "generateContent",
            "vertex:google",
        )
    )

    assert response.status_code == 200
    assert len(outcomes) == 1
    outcome = outcomes[0]
    assert outcome.provider == "vertex:google"
    assert outcome.model == "gemini-2.0-flash"
    assert outcome.optimized_tokens == 11
    assert outcome.output_tokens == 7
    assert outcome.cache_read_tokens == 3


def test_vertex_stream_passthrough_preserves_chunks_and_records_usage() -> None:
    handler = object.__new__(HeadroomProxy)
    handler.http_client = _VertexStreamClient()
    outcomes = []

    async def next_request_id():  # noqa: ANN202
        return "req_vertex_stream"

    async def record(outcome):  # noqa: ANN001, ANN202
        outcomes.append(outcome)

    handler._next_request_id = next_request_id
    handler._record_request_outcome = record

    response = asyncio.run(
        handler.handle_passthrough(
            _VertexStreamPassthroughRequest(),
            "https://vertex.test",
            "streamGenerateContent",
            "vertex:google",
        )
    )

    assert isinstance(response, StreamingResponse)

    async def collect():  # noqa: ANN202
        return [chunk async for chunk in response.body_iterator]

    chunks = asyncio.run(collect())

    assert len(chunks) == 2
    assert chunks[0].startswith(b'data: {"candidates"')
    assert b'"usageMetadata"' in chunks[1]
    assert len(outcomes) == 1
    outcome = outcomes[0]
    assert outcome.provider == "vertex:google"
    assert outcome.model == "gemini-2.0-flash"
    assert outcome.optimized_tokens == 13
    assert outcome.output_tokens == 5
    assert outcome.cache_read_tokens == 2


def test_vertex_stream_passthrough_records_outcome_when_stream_ends_mid_character() -> None:
    closed: list[bool] = []

    class _CountingChunks(_AsyncChunks):
        async def aclose(self) -> None:
            closed.append(True)

    class _TruncatedClient(_VertexStreamClient):
        async def send(self, request, stream=False):  # noqa: ANN001, ANN201
            return httpx.Response(
                200,
                request=request,
                headers={"content-type": "text/event-stream"},
                stream=_CountingChunks(
                    [
                        b'data: {"usageMetadata":{"promptTokenCount":13,'
                        b'"candidatesTokenCount":5}}\n\n',
                        b'data: {"t":"\xe2\x82',  # first 2 bytes of a 3-byte character
                    ]
                ),
            )

    handler = object.__new__(HeadroomProxy)
    handler.http_client = _TruncatedClient()
    outcomes = []

    async def next_request_id():  # noqa: ANN202
        return "req_vertex_truncated"

    async def record(outcome):  # noqa: ANN001, ANN202
        outcomes.append(outcome)

    handler._next_request_id = next_request_id
    handler._record_request_outcome = record

    response = asyncio.run(
        handler.handle_passthrough(
            _VertexStreamPassthroughRequest(),
            "https://vertex.test",
            "streamGenerateContent",
            "vertex:google",
        )
    )

    async def collect():  # noqa: ANN202
        return [chunk async for chunk in response.body_iterator]

    assert len(asyncio.run(collect())) == 2
    assert len(outcomes) == 1
    assert closed == [True]
    # Usage already received is kept, but a stream cut mid-character did not
    # complete: it takes the same failure status as other post-start stream
    # failures, so the outcome funnel books it as failed, not as a success.
    assert outcomes[0].optimized_tokens == 13
    assert outcomes[0].output_tokens == 5
    assert outcomes[0].status_code == 502

    failed: list[str] = []
    requested: list[dict] = []

    class _Metrics:
        async def record_failed(self, provider):  # noqa: ANN001, ANN202
            failed.append(provider)

        async def record_request(self, **kwargs):  # noqa: ANN003, ANN202
            requested.append(kwargs)

    asyncio.run(emit_request_outcome(SimpleNamespace(metrics=_Metrics()), outcomes[0]))
    assert failed == [outcomes[0].provider]
    assert requested == []


def test_stream_finalizer_records_vertex_provider_for_dashboard() -> None:
    handler = object.__new__(HeadroomProxy)
    handler.config = SimpleNamespace(log_full_messages=False)
    outcomes = []

    async def record(outcome):  # noqa: ANN001, ANN202
        outcomes.append(outcome)

    handler._record_request_outcome = record

    asyncio.run(
        handler._finalize_stream_response(
            body={"contents": [{"role": "user", "parts": [{"text": "hello"}]}]},
            provider="gemini",
            outcome_provider="vertex:google",
            model="gemini-2.0-flash",
            request_id="req_vertex_stream_final",
            original_tokens=20,
            optimized_tokens=12,
            tokens_saved=8,
            transforms_applied=["test-transform"],
            optimization_latency=3.0,
            stream_state={
                "input_tokens": 12,
                "output_tokens": 5,
                "cache_read_input_tokens": 2,
                "cache_creation_input_tokens": 0,
                "cache_creation_ephemeral_5m_input_tokens": 0,
                "cache_creation_ephemeral_1h_input_tokens": 0,
                "total_bytes": 100,
                "sse_buffer": bytearray(),
                "ttfb_ms": 4.0,
            },
            start_time=0.0,
            tags={"route": "vertex"},
        )
    )

    assert len(outcomes) == 1
    outcome = outcomes[0]
    assert outcome.provider == "vertex:google"
    assert outcome.model == "gemini-2.0-flash"
    assert outcome.optimized_tokens == 12
    assert outcome.output_tokens == 5
    assert outcome.tokens_saved == 8
    assert outcome.cache_read_tokens == 2


def _finalize_anthropic_stream(optimized_tokens, input_tokens):  # noqa: ANN001, ANN202
    handler = object.__new__(HeadroomProxy)
    handler.config = SimpleNamespace(log_full_messages=False)
    outcomes = []

    async def record(outcome):  # noqa: ANN001, ANN202
        outcomes.append(outcome)

    handler._record_request_outcome = record

    asyncio.run(
        handler._finalize_stream_response(
            body={"messages": [{"role": "user", "content": "hello"}]},
            provider="anthropic",
            model="claude-opus-4-1",
            request_id="req_anthropic_stream_final",
            original_tokens=optimized_tokens + 5,
            optimized_tokens=optimized_tokens,
            tokens_saved=5,
            transforms_applied=[],
            optimization_latency=1.0,
            stream_state={
                "input_tokens": input_tokens,
                "output_tokens": 7,
                "cache_read_input_tokens": 360_949,
                "cache_creation_input_tokens": 840,
                "cache_creation_ephemeral_5m_input_tokens": 0,
                "cache_creation_ephemeral_1h_input_tokens": 840,
                "total_bytes": 100,
                "sse_buffer": bytearray(),
                "ttfb_ms": 4.0,
            },
            start_time=0.0,
        )
    )
    (outcome,) = outcomes
    return outcome


@pytest.mark.parametrize(
    "optimized_tokens",
    [
        # Local count 50k over the provider's (a production turn reported
        # input_tokens=2 while the old derivation logged 50,663 uncached).
        412_452,
        # Local count under the provider's: the old derivation clamped to 0.
        300_000,
    ],
)
def test_stream_finalizer_takes_anthropic_uncached_input_from_usage(optimized_tokens) -> None:  # noqa: ANN001
    outcome = _finalize_anthropic_stream(optimized_tokens, input_tokens=2)

    assert outcome.uncached_input_tokens == 2
    assert outcome.cache_read_tokens == 360_949
    assert outcome.cache_write_tokens == 840


def test_stream_finalizer_derives_anthropic_uncached_input_without_usage() -> None:
    # No message_start usage (an error before the stream began): keep the
    # tokenizer-based derivation.
    outcome = _finalize_anthropic_stream(400_000, input_tokens=None)

    assert outcome.uncached_input_tokens == 400_000 - 360_949 - 840


def test_sse_parser_leaves_absent_anthropic_input_tokens_absent() -> None:
    # A message_start usage without input_tokens must not read as a provider
    # count of 0, or the finalizer books 0 uncached instead of deriving it.
    proxy = object.__new__(HeadroomProxy)
    event = {"type": "message_start", "message": {"usage": {"cache_read_input_tokens": 9}}}
    state = {"sse_buffer": bytearray(f"data: {json.dumps(event)}\n\n".encode())}

    usage = proxy._parse_sse_usage_from_buffer(state, "anthropic")

    assert usage is not None
    assert "input_tokens" not in usage
    assert usage["cache_read_input_tokens"] == 9


def test_vertex_gemini_non_text_generate_records_dashboard_outcome() -> None:
    handler = object.__new__(HeadroomProxy)
    handler.memory_handler = None
    handler.rate_limiter = None
    outcomes = []
    upstream_urls = []

    async def next_request_id():  # noqa: ANN202
        return "req_vertex_image"

    async def record(outcome):  # noqa: ANN001, ANN202
        outcomes.append(outcome)

    async def retry_request(method, url, headers, body):  # noqa: ANN001, ANN202
        upstream_urls.append(url)
        request = httpx.Request(method, url, headers=headers)
        return httpx.Response(
            200,
            request=request,
            headers={"content-type": "application/json"},
            json={
                "usageMetadata": {
                    "promptTokenCount": 31,
                    "candidatesTokenCount": 4,
                    "cachedContentTokenCount": 6,
                }
            },
        )

    handler._next_request_id = next_request_id
    handler._record_request_outcome = record
    handler._retry_request = retry_request

    response = asyncio.run(
        handler.handle_gemini_generate_content(
            _VertexGeminiImageRequest(),
            "gemini-2.0-flash",
            "https://vertex.test",
            "vertex:google",
        )
    )

    assert response.status_code == 200
    assert upstream_urls == [
        "https://vertex.test/v1/projects/p/locations/us-central1/publishers/google/models/gemini-2.0-flash:generateContent"
    ]
    assert response.headers["x-headroom-tokens-before"] == "31"
    assert response.headers["x-headroom-tokens-after"] == "31"
    assert response.headers["x-headroom-tokens-saved"] == "0"
    assert len(outcomes) == 1
    outcome = outcomes[0]
    assert outcome.provider == "vertex:google"
    assert outcome.model == "gemini-2.0-flash"
    assert outcome.original_tokens == 31
    assert outcome.optimized_tokens == 31
    assert outcome.output_tokens == 4
    assert outcome.cache_read_tokens == 6
    assert outcome.num_messages == 1


def test_retry_request_retries_connect_timeout() -> None:
    proxy = object.__new__(HeadroomProxy)
    proxy.http_client = _RetryThenSuccessClient()
    proxy.config = SimpleNamespace(
        retry_enabled=True,
        retry_max_attempts=2,
        retry_base_delay_ms=0,
        retry_max_delay_ms=0,
    )

    response = asyncio.run(
        proxy._retry_request(
            "POST",
            "https://api.openai.com/v1/responses",
            {},
            {"model": "gpt-5"},
        )
    )

    assert response.status_code == 200
    assert proxy.http_client.attempts == 2


def test_retry_request_returns_503_when_shutdown_interrupts_retry_sleep() -> None:
    class _Always429Client:
        def __init__(self) -> None:
            self.attempts = 0

        async def post(self, url, **kwargs):  # type: ignore[no-untyped-def]
            self.attempts += 1
            return httpx.Response(
                429,
                request=httpx.Request("POST", url),
                json={"error": {"message": "slow down"}},
                headers={"retry-after": "30"},
            )

    proxy = object.__new__(HeadroomProxy)
    proxy.http_client = _Always429Client()
    proxy.config = SimpleNamespace(
        retry_enabled=True,
        retry_max_attempts=3,
        retry_base_delay_ms=30000,
        retry_max_delay_ms=30000,
    )
    proxy._shutdown_event = asyncio.Event()
    proxy._shutdown_event.set()

    response = asyncio.run(
        proxy._retry_request(
            "POST",
            "https://api.anthropic.test/v1/messages",
            {},
            {"model": "claude-3-5-sonnet"},
        )
    )

    assert response.status_code == 503
    assert response.json() == {
        "error": {
            "type": "shutdown",
            "message": "Proxy is shutting down; retry backoff cancelled.",
        }
    }
    assert response.headers["retry-after"] == "0"
    assert proxy.http_client.attempts == 1


def test_anthropic_tool_sort_and_context_append_helpers() -> None:
    tools = [
        {"type": "function", "function": {"name": "beta"}},
        {"name": "alpha"},
        {"type": "tool"},
    ]

    sorted_tools = AnthropicHandlerMixin._sort_tools_deterministically(tools)

    assert [AnthropicHandlerMixin._tool_sort_key(tool)[0] for tool in sorted_tools] == [
        "alpha",
        "beta",
        "tool",
    ]
    assert AnthropicHandlerMixin._sort_tools_deterministically(None) is None
    assert AnthropicHandlerMixin._tools_for_forwarding(tools, preserve_order=True) == tools
    assert [
        AnthropicHandlerMixin._tool_sort_key(tool)[0]
        for tool in AnthropicHandlerMixin._tools_for_forwarding(tools, preserve_order=False) or []
    ] == [
        "alpha",
        "beta",
        "tool",
    ]
    assert (
        AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(
            [], "ctx", frozen_message_count=0
        )
        == []
    )
    assert AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(
        [{"role": "user", "content": "hello"}],
        "ctx",
        frozen_message_count=0,
    ) == [{"role": "user", "content": "hello\n\nctx"}]
    # PR-A2 semantics: list-content user messages get the context appended
    # to the first text block (live-zone-tail injection).
    assert AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(
        [{"role": "user", "content": [{"type": "text", "text": "hello"}]}],
        "ctx",
        frozen_message_count=0,
    ) == [{"role": "user", "content": [{"type": "text", "text": "hello\n\nctx"}]}]


def test_append_context_skips_trailing_system_message() -> None:
    # Claude Code 2.1.x request shape: the user turn is followed by a
    # role="system" message carrying the environment and the cache breakpoint.
    trailing_system = {
        "role": "system",
        "content": [
            {"type": "text", "text": "# Environment", "cache_control": {"type": "ephemeral"}}
        ],
    }
    user_turn = {
        "role": "user",
        "content": [
            {"type": "text", "text": "<system-reminder>ctx</system-reminder>"},
            {"type": "text", "text": "question"},
        ],
    }
    inject = AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn

    assert inject([user_turn, trailing_system], "memory", frozen_message_count=0) == [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "<system-reminder>ctx</system-reminder>\n\nmemory"},
                {"type": "text", "text": "question"},
            ],
        },
        trailing_system,
    ]
    # The user turn is still subject to the frozen prefix.
    messages = [user_turn, trailing_system]
    assert inject(messages, "memory", frozen_message_count=1) is messages
    # Skipping system messages never reaches past a non-user turn.
    messages = [user_turn, {"role": "assistant", "content": "ok"}, trailing_system]
    assert inject(messages, "memory", frozen_message_count=0) is messages
    # Tool-result-only turns have no text block to extend.
    messages = [
        {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "t1", "content": "x"}]},
        trailing_system,
    ]
    assert inject(messages, "memory", frozen_message_count=0) is messages
    messages = [trailing_system]
    assert inject(messages, "memory", frozen_message_count=0) is messages


def test_proactive_expansion_appends_after_cached_prefix_without_mutating_it() -> None:
    """CCR expansion must not rewrite a message the provider has already cached (#4287)."""
    from headroom.ccr.context_tracker import (
        PROACTIVE_EXPANSION_CLOSE_TAG,
        PROACTIVE_EXPANSION_OPEN_TAG,
    )

    env_block = {"type": "text", "text": "# Environment", "cache_control": {"type": "ephemeral"}}
    trailing_system = {"role": "system", "content": [env_block]}
    first_user = {
        "role": "user",
        "content": [{"type": "text", "text": "hello from turn 0"}],
    }
    messages = [first_user, trailing_system]
    expansion = f"{PROACTIVE_EXPANSION_OPEN_TAG}\nexpanded\n{PROACTIVE_EXPANSION_CLOSE_TAG}"

    forwarded = AnthropicHandlerMixin._append_proactive_expansion_after_cached_prefix(
        messages, expansion
    )

    assert forwarded[0] == first_user
    assert forwarded[1]["role"] == "system"
    assert forwarded[1]["content"][0] == env_block
    assert forwarded[1]["content"][1] == {"type": "text", "text": expansion}
    assert "cache_control" not in forwarded[1]["content"][1]
    assert AnthropicHandlerMixin._without_proactive_expansion_messages(forwarded) == messages
    assert messages[0]["content"][0]["text"] == "hello from turn 0"
    assert messages[1]["content"] == [env_block]


def test_proactive_expansion_without_cache_control_stays_on_the_live_user_turn() -> None:
    from headroom.ccr.context_tracker import (
        PROACTIVE_EXPANSION_CLOSE_TAG,
        PROACTIVE_EXPANSION_OPEN_TAG,
    )

    messages = [{"role": "user", "content": "hello"}]
    expansion = f"{PROACTIVE_EXPANSION_OPEN_TAG}\nexpanded\n{PROACTIVE_EXPANSION_CLOSE_TAG}"
    forwarded = AnthropicHandlerMixin._append_proactive_expansion_after_cached_prefix(
        messages, expansion
    )
    assert forwarded[0]["content"][0] == {"type": "text", "text": "hello"}
    assert forwarded[0]["content"][1] == {"type": "text", "text": expansion}
    assert AnthropicHandlerMixin._without_proactive_expansion_messages(forwarded) == [
        {"role": "user", "content": [{"type": "text", "text": "hello"}]}
    ]
    assert messages[0]["content"] == "hello"


def test_proactive_expansion_keeps_tool_results_together_and_client_text() -> None:
    from headroom.ccr.context_tracker import (
        PROACTIVE_EXPANSION_CLOSE_TAG,
        PROACTIVE_EXPANSION_OPEN_TAG,
    )

    expansion = f"{PROACTIVE_EXPANSION_OPEN_TAG}\nexample\n{PROACTIVE_EXPANSION_CLOSE_TAG}"
    tool_a = {
        "type": "tool_result",
        "tool_use_id": "A",
        "content": "a",
        "cache_control": {"type": "ephemeral"},
    }
    tool_b = {"type": "tool_result", "tool_use_id": "B", "content": "b"}
    messages = [{"role": "user", "content": [tool_a, tool_b]}]
    forwarded = AnthropicHandlerMixin._append_proactive_expansion_after_cached_prefix(
        messages, expansion
    )
    content = forwarded[0]["content"]
    assert [block.get("type") for block in content] == ["tool_result", "tool_result", "text"]
    assert content[0] is tool_a and content[1] is tool_b and "cache_control" not in content[2]
    assert AnthropicHandlerMixin._without_proactive_expansion_messages(forwarded) == messages
    client = [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Explain this:"},
                {"type": "text", "text": expansion},
            ],
        }
    ]
    assert AnthropicHandlerMixin._without_proactive_expansion_messages(client) == client


def test_anthropic_image_compression_helper_only_rewrites_latest_eligible_turn() -> None:
    image_message = {
        "role": "user",
        "content": [{"type": "image", "source": {"type": "base64", "data": "abc"}}],
    }
    compressed = {
        "role": "user",
        "content": [{"type": "image", "source": {"type": "base64", "data": "xyz"}}],
    }

    assert (
        AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(
            [],
            frozen_message_count=0,
            compressor=_ImageCompressor(compressed),
        )
        == []
    )
    assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(
        [image_message],
        frozen_message_count=1,
        compressor=_ImageCompressor(compressed),
    ) == [image_message]
    assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(
        [{"role": "assistant", "content": image_message["content"]}],
        frozen_message_count=0,
        compressor=_ImageCompressor(compressed),
    ) == [{"role": "assistant", "content": image_message["content"]}]
    assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(
        [{"role": "user", "content": "no-image"}],
        frozen_message_count=0,
        compressor=_ImageCompressor(compressed),
    ) == [{"role": "user", "content": "no-image"}]
    assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(
        [image_message],
        frozen_message_count=0,
        compressor=_ImageCompressor(image_message),
    ) == [image_message]
    assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(
        [image_message],
        frozen_message_count=0,
        compressor=_ImageCompressor(compressed),
    ) == [compressed]


def test_proxy_helper_reuses_a_singleton_image_compressor(monkeypatch) -> None:
    # #2513: the compressor caches heavyweight models, so it must be a
    # process-wide singleton rather than a fresh instance per request.
    from headroom.proxy import helpers

    monkeypatch.setattr(helpers, "_image_compressor_available", None)
    monkeypatch.setattr(helpers, "_image_compressor_instance", None)
    _FreshCompressor.instances = 0

    with patch("headroom.image.ImageCompressor", _FreshCompressor):
        first = helpers._get_image_compressor()
        second = helpers._get_image_compressor()

    assert isinstance(first, _FreshCompressor)
    assert first is second
    assert first._is_singleton is True
    assert _FreshCompressor.instances == 1


def test_proxy_helper_caches_image_stack_import_failure(monkeypatch) -> None:
    from headroom.proxy import helpers

    real_import = builtins.__import__
    calls = 0

    def fake_import(name, *args, **kwargs):  # noqa: ANN001, ANN202
        nonlocal calls
        if name == "headroom.image":
            calls += 1
            raise ImportError("image extras unavailable")
        return real_import(name, *args, **kwargs)

    monkeypatch.setattr(helpers, "_image_compressor_available", None)
    monkeypatch.setattr(helpers, "_image_compressor_instance", None)
    monkeypatch.setattr(builtins, "__import__", fake_import)

    assert helpers._get_image_compressor() is None
    assert helpers._get_image_compressor() is None
    assert calls == 1
    assert helpers._image_compressor_available is False


def test_anthropic_cache_delta_helpers_cover_string_list_and_role_mismatch() -> None:
    previous_original = [{"role": "user", "content": "hello"}]
    previous_forwarded = [{"role": "user", "content": "HELLO"}]

    assert AnthropicHandlerMixin._extract_cache_stable_delta(
        [{"role": "user", "content": "hello"}, {"role": "assistant", "content": "next"}],
        previous_original,
        previous_forwarded,
    ) == (previous_forwarded, [{"role": "assistant", "content": "next"}])
    assert (
        AnthropicHandlerMixin._extract_cache_stable_delta(
            [{"role": "assistant", "content": "hello"}],
            previous_original,
            previous_forwarded,
        )
        is None
    )

    string_suffix = AnthropicHandlerMixin._extract_cache_stable_last_message_suffix(
        [{"role": "user", "content": "hello world"}],
        previous_original,
        previous_forwarded,
    )
    assert string_suffix == ([], previous_forwarded[0], [{"role": "user", "content": " world"}])

    list_suffix = AnthropicHandlerMixin._extract_cache_stable_last_message_suffix(
        [
            {
                "role": "user",
                "content": [{"type": "text", "text": "a"}, {"type": "text", "text": "b"}],
            }
        ],
        [{"role": "user", "content": [{"type": "text", "text": "a"}]}],
        [{"role": "user", "content": [{"type": "text", "text": "A"}]}],
    )
    assert list_suffix == (
        [],
        {"role": "user", "content": [{"type": "text", "text": "A"}]},
        [{"role": "user", "content": [{"type": "text", "text": "b"}]}],
    )

    assert AnthropicHandlerMixin._merge_appended_message_delta(
        {"role": "user", "content": "HELLO"},
        {"role": "user", "content": " world"},
    ) == {"role": "user", "content": "HELLO world"}
    assert AnthropicHandlerMixin._merge_appended_message_delta(
        {"role": "user", "content": [{"type": "text", "text": "A"}]},
        {"role": "user", "content": [{"type": "text", "text": "b"}]},
    ) == {"role": "user", "content": [{"type": "text", "text": "A"}, {"type": "text", "text": "b"}]}
    assert (
        AnthropicHandlerMixin._merge_appended_message_delta(
            {"role": "user", "content": "A"},
            {"role": "assistant", "content": "B"},
        )
        is None
    )


def test_anthropic_assistant_message_helper_requires_assistant_role() -> None:
    assert AnthropicHandlerMixin._assistant_message_from_response_json(None) is None
    assert AnthropicHandlerMixin._assistant_message_from_response_json({"role": "user"}) is None
    assert AnthropicHandlerMixin._assistant_message_from_response_json(
        {"role": "assistant", "content": [{"type": "text", "text": "ok"}]}
    ) == {"role": "assistant", "content": [{"type": "text", "text": "ok"}]}


# ============================================================================
# CCR workspace resolution (cross-project leak fix, 2026-05-26).
#
# These tests pin the `_resolve_ccr_workspace` static helper that the
# anthropic handler uses to scope the proactive-expansion cache by
# project identity. The resolver shares its tier order with the memory
# subsystem's ProjectResolver: x-headroom-project-id → x-headroom-cwd →
# CLI override → system-prompt `cwd:` line. Returns `("", None)` on
# no signal — the fail-closed signal that callers gate on.
# ============================================================================


def _fake_request(headers: dict[str, str]) -> SimpleNamespace:
    """Minimal Starlette/FastAPI-shaped request object for resolver tests."""
    return SimpleNamespace(headers=headers)


def test_resolve_ccr_workspace_explicit_project_id_wins() -> None:
    """x-headroom-project-id is the highest-priority signal."""
    request = _fake_request({"x-headroom-project-id": "my-cool-project"})
    body = {}
    key, label = AnthropicHandlerMixin()._resolve_ccr_workspace(request, body)
    assert key.startswith("my-cool-project-")
    assert len(key.split("-")[-1]) == 16
    assert label == "my-cool-project"


def test_resolve_ccr_workspace_cwd_header() -> None:
    """x-headroom-cwd produces a stable per-cwd key + basename label."""
    request = _fake_request({"x-headroom-cwd": "/home/user/code/daphni-rails"})
    body = {}
    key, label = AnthropicHandlerMixin()._resolve_ccr_workspace(request, body)
    # Key format: "{basename}-{sha256[:16]}" — stable per absolute cwd.
    assert key.startswith("daphni-rails-")
    assert len(key) >= len("daphni-rails-") + 16
    assert label == "daphni-rails"


def test_resolve_ccr_workspace_uses_configured_project_root_override() -> None:
    """The CLI project-root override reaches CCR workspace resolution."""
    handler = AnthropicHandlerMixin()
    handler.config = SimpleNamespace(memory_project_root_override="/home/user/code/project-c")

    key, label = handler._resolve_ccr_workspace(_fake_request({}), {})

    assert key.startswith("project-c-")
    assert label == "project-c"


def test_resolve_ccr_workspace_two_cwds_get_distinct_keys() -> None:
    """Two different cwds produce different workspace keys (cross-leak prevention)."""
    handler = AnthropicHandlerMixin()
    key_a, _ = handler._resolve_ccr_workspace(
        _fake_request({"x-headroom-cwd": "/home/user/code/daphni-rails"}), {}
    )
    key_b, _ = handler._resolve_ccr_workspace(
        _fake_request({"x-headroom-cwd": "/home/user/code/tamag0"}), {}
    )
    assert key_a != key_b, "different cwds must yield different workspace keys"


def test_resolve_ccr_workspace_project_label_alone_fails_closed() -> None:
    """The savings label must not become a memory/CCR identity."""
    key, label = AnthropicHandlerMixin()._resolve_ccr_workspace(
        _fake_request({"x-headroom-project": "api"}), {}
    )
    assert key == ""
    assert label is None


def test_resolve_ccr_workspace_project_label_does_not_collapse_cwds() -> None:
    """A user-supplied label cannot merge two distinct cwd identities."""
    key_a, _ = AnthropicHandlerMixin()._resolve_ccr_workspace(
        _fake_request(
            {
                "x-headroom-project": "api",
                "x-headroom-cwd": "/work/acme/api",
            }
        ),
        {},
    )
    key_b, _ = AnthropicHandlerMixin()._resolve_ccr_workspace(
        _fake_request(
            {
                "x-headroom-project": "api",
                "x-headroom-cwd": "/work/other/api",
            }
        ),
        {},
    )
    assert key_a != key_b


def test_resolve_ccr_workspace_no_signal_returns_empty() -> None:
    """No project-id, no cwd header, no system prompt → fail-closed signal."""
    request = _fake_request({})
    body = {}
    key, label = AnthropicHandlerMixin()._resolve_ccr_workspace(request, body)
    assert key == ""
    assert label is None


def test_resolve_ccr_workspace_system_prompt_cwd_fallback() -> None:
    """System prompt with `cwd:` line is the lowest-tier fallback."""
    request = _fake_request({})
    body = {
        "system": [{"type": "text", "text": "You are helpful.\ncwd: /home/u/code/my-project\nGo."}]
    }
    key, label = AnthropicHandlerMixin()._resolve_ccr_workspace(request, body)
    # The label is the basename of the cwd extracted from the prompt.
    assert label == "my-project"
    assert key.startswith("my-project-")


def test_resolve_ccr_workspace_malformed_request_returns_empty() -> None:
    """A request whose headers attribute can't be dict()-ed fails closed, not crashes."""

    class _BrokenHeaders:
        def __iter__(self):
            raise RuntimeError("boom")

    request = SimpleNamespace(headers=_BrokenHeaders())
    body = {}
    # The helper catches the exception, logs it, and returns the fail-
    # closed sentinel ("", None). Critically, it does NOT raise — the
    # proxy must continue serving the request even if CCR scoping fails.
    key, label = AnthropicHandlerMixin()._resolve_ccr_workspace(request, body)
    assert key == ""
    assert label is None


class TestHasNewCcrMarkers:
    """#1850: replayed (overlay) markers must not count as new-this-turn.

    ``overlay_cached_prefix`` replays the previously-forwarded compressed prefix
    byte-identical to keep the messages cache warm — which reintroduces its old
    ``hash=…`` markers. If those replayed markers counted as "new", the handler
    would re-inject the retrieve tool every frozen turn and bust the *tools*
    cache. ``has_new_ccr_markers`` filters them out.
    """

    @staticmethod
    def _hashes(*contents: str) -> list[str]:
        from headroom.ccr.tool_injection import CCRToolInjector

        inj = CCRToolInjector(
            provider="anthropic", inject_tool=False, inject_system_instructions=False
        )
        inj.scan_for_markers([{"role": "user", "content": c} for c in contents])
        return inj.detected_hashes

    def test_replayed_markers_are_not_new(self):
        from headroom.proxy.helpers import has_new_ccr_markers

        marker = "[100 items compressed to 10. Retrieve more: hash=abc123def456abc123def456]"
        current = self._hashes(marker)
        assert current, "sanity: the marker must be detected"
        # Every marker was already in what we forwarded last turn → nothing new.
        assert (
            has_new_ccr_markers(
                current_detected_hashes=current,
                previous_forwarded_messages=[{"role": "user", "content": marker}],
                provider="anthropic",
            )
            is False
        )

    def test_genuinely_new_marker_is_detected(self):
        from headroom.proxy.helpers import has_new_ccr_markers

        old = "[100 items compressed to 10. Retrieve more: hash=abc123def456abc123def456]"
        new = "[50 items compressed to 5. Retrieve more: hash=deadbeefdeadbeefdeadbeef]"
        current = self._hashes(old, new)
        # Only `old` was forwarded before; `new` is fresh → override must fire.
        assert (
            has_new_ccr_markers(
                current_detected_hashes=current,
                previous_forwarded_messages=[{"role": "user", "content": old}],
                provider="anthropic",
            )
            is True
        )

    def test_no_previous_forward_means_all_new(self):
        from headroom.proxy.helpers import has_new_ccr_markers

        marker = "[100 items compressed to 10. Retrieve more: hash=abc123def456abc123def456]"
        assert (
            has_new_ccr_markers(
                current_detected_hashes=self._hashes(marker),
                previous_forwarded_messages=None,
                provider="anthropic",
            )
            is True
        )

    def test_no_markers_means_nothing_new(self):
        from headroom.proxy.helpers import has_new_ccr_markers

        assert (
            has_new_ccr_markers(
                current_detected_hashes=[],
                previous_forwarded_messages=None,
                provider="anthropic",
            )
            is False
        )


def test_strict_frozen_count_tool_and_function_tail_are_mutable():
    # OpenAI function-calling harnesses (Kimi / fireworks) end each turn with a
    # role:"tool" (or legacy role:"function") observation — NOT role:"user".
    # Gating the mutable tail on role=="user" froze the whole conversation on
    # every such turn => zero compression. Tool/function observations must be
    # treated as the mutable delta (freeze all-but-last), like a user obs.
    from headroom.proxy.handlers.openai import OpenAIHandlerMixin as M

    # role:tool tail -> only the last message is mutable (frozen = final_idx)
    assert (
        M._strict_previous_turn_frozen_count(
            [{"role": "user"}, {"role": "assistant"}, {"role": "tool"}], 0
        )
        == 2
    )
    assert (
        M._strict_previous_turn_frozen_count(
            [{"role": "user"}, {"role": "assistant"}, {"role": "function"}], 0
        )
        == 2
    )
    # assistant/system tail is NOT an observation -> freeze everything
    assert (
        M._strict_previous_turn_frozen_count(
            [{"role": "user"}, {"role": "tool"}, {"role": "assistant"}], 0
        )
        == 3
    )


class _ClientDisconnectRequest:
    """Mock request whose body() raises ClientDisconnect to simulate mid-stream cancel."""

    method = "POST"
    headers = {"content-type": "application/json"}
    url = SimpleNamespace(path="/v1/chat/completions", query="")

    async def body(self) -> bytes:
        from starlette.requests import ClientDisconnect

        raise ClientDisconnect()


class _ClientDisconnectStreamRequest:
    """Mock request for streaming passthrough with ClientDisconnect."""

    method = "POST"
    headers = {"content-type": "application/json"}
    url = SimpleNamespace(
        path="/v1/projects/p/locations/us-central1/publishers/google/models/gemini-2.0-flash:streamGenerateContent",
        query="alt=sse",
    )

    async def body(self) -> bytes:
        from starlette.requests import ClientDisconnect

        raise ClientDisconnect()


def test_handle_passthrough_client_disconnect():
    """ClientDisconnect during body read returns 204 instead of crashing TaskGroup."""
    handler = object.__new__(OpenAIHandlerMixin)
    response = asyncio.run(
        handler.handle_passthrough(_ClientDisconnectRequest(), "https://api.openai.com")
    )
    assert response.status_code == 204


def test_handle_streaming_passthrough_client_disconnect():
    """ClientDisconnect during streaming body read returns 204."""
    handler = object.__new__(OpenAIHandlerMixin)
    response = asyncio.run(
        handler.handle_passthrough(
            _ClientDisconnectStreamRequest(),
            "https://us-central1-aiplatform.googleapis.com",
            endpoint_name="streamRawPredict",
            provider="vertex:google",
        )
    )
    assert response.status_code == 204