Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

166 KB
Raw Blame
from __future__ import annotations

import asyncio
import json
from pathlib import Path
from types import SimpleNamespace
from typing import Any

import httpx
import pytest

from deeptutor.agents.chat.agentic_pipeline import AgenticChatPipeline
from deeptutor.agents.loop import agent_loop as agent_loop_mod
from deeptutor.agents.loop.agent_loop import InlineThinkFilter
from deeptutor.capabilities.explore_context import explorer as explorer_mod
from deeptutor.capabilities.mastery import MASTERY_TOOL_NAMES
from deeptutor.capabilities.mastery.pipeline import MasteryLoopPipeline
from deeptutor.capabilities.mastery.tools import MasteryQuizTool
from deeptutor.capabilities.partner_group.tools import InvokeOtherTool
from deeptutor.core.context import Attachment, TurnRuntimeContext, UnifiedContext
from deeptutor.core.stream import StreamEvent, StreamEventType
from deeptutor.core.tool_protocol import ToolResult
from deeptutor.core.trace import ANSWER_BEARING_CALL_KINDS
from deeptutor.learning.models import KnowledgePoint, LearningModule, LearningProgress
from deeptutor.learning.storage import LearningStore
from deeptutor.runtime.stream_bus import StreamBus
from deeptutor.services.llm import LLMProviderTransportError, LLMReasoningBudgetExhausted
from deeptutor.services.llm.provider_core.openai_responses import convert_messages


async def _collect_bus_events(bus: StreamBus) -> tuple[list[StreamEvent], asyncio.Task[Any]]:
    events: list[StreamEvent] = []

    async def _consume() -> None:
        async for event in bus.subscribe():
            events.append(event)

    consumer = asyncio.create_task(_consume())
    await asyncio.sleep(0)
    return events, consumer  # type: ignore[return-value]


def _llm_chunk(
    *,
    content: str | None = None,
    tool_calls: list[dict[str, Any]] | None = None,
    usage: Any = None,
    finish_reason: str | None = None,
    reasoning_content: str | None = None,
    provider_specific_fields: dict[str, Any] | None = None,
) -> SimpleNamespace:
    delta_fields: dict[str, Any] = {"content": content}
    if reasoning_content is not None:
        delta_fields["reasoning_content"] = reasoning_content
    if tool_calls is not None:
        delta_fields["tool_calls"] = [
            SimpleNamespace(
                index=tc.get("index", i),
                id=tc.get("id"),
                extra_content=tc.get("extra_content"),
                function=SimpleNamespace(
                    name=tc.get("name"),
                    arguments=tc.get("arguments"),
                ),
            )
            for i, tc in enumerate(tool_calls)
        ]
    else:
        delta_fields["tool_calls"] = None
    return SimpleNamespace(
        choices=[
            SimpleNamespace(
                delta=SimpleNamespace(**delta_fields),
                finish_reason=finish_reason,
                provider_specific_fields=provider_specific_fields,
            )
        ],
        usage=usage,
    )


def _usage_only_chunk(*, prompt: int, completion: int, total: int) -> SimpleNamespace:
    return SimpleNamespace(
        choices=[],
        usage=SimpleNamespace(
            prompt_tokens=prompt,
            completion_tokens=completion,
            total_tokens=total,
        ),
    )


async def _async_llm_stream(chunks: list[SimpleNamespace]):
    for chunk in chunks:
        yield chunk


class _ScriptedChatClient:
    def __init__(self, scripted: list[list[SimpleNamespace]]) -> None:
        self._script = list(scripted)
        self.call_count = 0
        self.calls: list[dict[str, Any]] = []

        class _Completions:
            def __init__(self, parent: _ScriptedChatClient) -> None:
                self.parent = parent

            async def create(self, **kwargs):
                self.parent.call_count += 1
                self.parent.calls.append({**kwargs, "messages": list(kwargs.get("messages") or [])})
                if not self.parent._script:
                    raise RuntimeError("Scripted client exhausted")
                return _async_llm_stream(self.parent._script.pop(0))

        class _Chat:
            def __init__(self, parent: _ScriptedChatClient) -> None:
                self.completions = _Completions(parent)

        self.chat = _Chat(self)


class _Registry:
    def __init__(self) -> None:
        self.executed: list[dict[str, Any]] = []

    def deferred_tools(self):
        return []

    def build_prompt_text(self, _enabled, **_kwargs):
        return "- `web_search` - Search the web"

    def build_openai_schemas(self, _enabled):
        return [
            {
                "type": "function",
                "function": {
                    "name": "web_search",
                    "description": "Search",
                    "parameters": {
                        "type": "object",
                        "properties": {"query": {"type": "string"}},
                        "required": ["query"],
                    },
                },
            },
            {
                "type": "function",
                "function": {
                    "name": "ask_user",
                    "description": "Ask the user",
                    "parameters": {
                        "type": "object",
                        "properties": {"questions": {"type": "array"}},
                        "required": ["questions"],
                    },
                },
            },
        ]

    async def execute(self, name: str, **kwargs):
        self.executed.append({"name": name, "kwargs": kwargs})
        return ToolResult(
            content="tool answer",
            sources=[{"tool": name}],
            metadata={"tool": name},
            success=True,
        )


@pytest.fixture(autouse=True)
def _isolated_runtime(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
    from deeptutor.capabilities.setup.binding import mark_intro_shown
    from deeptutor.services.path_service import PathService

    # Exercise the loop in an initialized install, independent of developer
    # data or whether another test has already created the default workspace.
    monkeypatch.setenv("DEEPTUTOR_HOME", str(tmp_path))
    paths = PathService(workspace_root=tmp_path / "data")
    monkeypatch.setattr(PathService, "_instance", paths)
    paths.ensure_all_directories()
    # First-run onboarding legitimately changes the next turn's system prompt.
    # Replay tests require stable configuration; setup owns onboarding tests.
    mark_intro_shown()
    monkeypatch.setattr(
        "deeptutor.agents.loop.pipeline.get_llm_config",
        lambda: SimpleNamespace(
            binding="openai",
            model="gpt-test",
            api_key="k",
            base_url="u",
            api_version=None,
            extra_headers={},
            reasoning_effort=None,
        ),
    )


async def _run(pipeline: AgenticChatPipeline, context: UnifiedContext):
    bus = StreamBus()
    events, consumer = await _collect_bus_events(bus)
    await pipeline.run(context, bus)
    await asyncio.sleep(0)
    await bus.close()
    await consumer
    return events


@pytest.mark.asyncio
@pytest.mark.parametrize("evidence", ["available", "text_only", "missing", "inaccessible"])
async def test_active_mastery_retrieves_verified_pixels_without_persisting_them(
    monkeypatch, tmp_path, evidence
):
    """#1611: exercise the active Mastery loop, real RAG tool and verified store."""
    import base64

    from deeptutor.multi_user import knowledge_access
    from deeptutor.services.rag.visual_assets import VisualAssetStore, collect_visual_assets
    from deeptutor.tools import rag_tool
    from deeptutor.tools.builtin import RAGTool
    from tests.services.rag.test_visual_assets import _fixture

    kb_dir, source, image, parsed = _fixture(tmp_path)
    candidate = collect_visual_assets(parsed, source, kb_dir)[0]
    store = VisualAssetStore(kb_dir)
    store.publish([candidate])
    if evidence == "missing":
        (store.root / (candidate.record["asset_id"] + ".png")).unlink()
    monkeypatch.setattr(
        knowledge_access,
        "resolve_for_rag",
        lambda _name: (
            None if evidence == "inaccessible" else SimpleNamespace(name="kb", base_dir=tmp_path)
        ),
    )

    async def search(**_kwargs):
        return {
            "content": "The source contains a learning curve.",
            "sources": [{"visual_asset_id": candidate.record["asset_id"]}],
        }

    monkeypatch.setattr(rag_tool, "rag_search", search)

    class Registry(_Registry):
        def build_openai_schemas(self, _enabled):
            schemas = super().build_openai_schemas(_enabled)
            return [
                *schemas,
                {
                    "type": "function",
                    "function": {
                        "name": "rag",
                        "description": "Search selected sources",
                        "parameters": {
                            "type": "object",
                            "properties": {
                                "query": {"type": "string"},
                                "kb_name": {"type": "string"},
                            },
                            "required": ["query", "kb_name"],
                        },
                    },
                },
            ]

        async def execute(self, name, **kwargs):
            if name == "rag":
                return await RAGTool().execute(**kwargs)
            return await super().execute(name, **kwargs)

    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(
                    tool_calls=[
                        {
                            "id": "figure",
                            "name": "rag",
                            "arguments": '{"query":"curve","kb_name":"kb"}',
                        },
                        {"id": "other", "name": "web_search", "arguments": '{"query":"context"}'},
                    ],
                    finish_reason="tool_calls",
                )
            ],
            [_llm_chunk(content="Source-backed explanation.", finish_reason="stop")],
        ]
    )
    pipeline = MasteryLoopPipeline(language="en")
    pipeline.model = "gpt-3.5-turbo" if evidence == "text_only" else "gpt-4o"
    pipeline.registry = Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _: ["rag", "web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)
    monkeypatch.setattr(pipeline, "_capability_finish_instruction", lambda *_: None)
    context = UnifiedContext(session_id="s", user_message="Explain the original figure.")
    events = await _run(pipeline, context)

    request = client.calls[1]["messages"]
    images = [
        part
        for msg in request
        if isinstance(msg.get("content"), list)
        for part in msg["content"]
        if part.get("type") == "image_url"
    ]
    if evidence == "available":
        assert len(images) == 1
        assert context.extension("source_visual_evidence")["image_hashes"] == [
            candidate.record["image_sha256"]
        ]
        assert (
            base64.b64decode(images[0]["image_url"]["url"].split(",", 1)[1]) == image.read_bytes()
        )
        tool_positions = [i for i, msg in enumerate(request) if msg.get("role") == "tool"]
        image_position = next(
            i
            for i, msg in enumerate(request)
            if msg.get("content") and isinstance(msg["content"], list)
        )
        assert image_position > max(tool_positions)
        assert candidate.record["asset_id"] in str(request[image_position])
    else:
        assert images == []
        assert context.extension("source_visual_evidence")["image_hashes"] == []
        tool_text = next(msg["content"] for msg in request if msg.get("tool_call_id") == "figure")
        assert (
            "cannot inspect source image pixels"
            if evidence == "text_only"
            else "unavailable for pixel inspection"
        ) in tool_text
    assert "base64" not in json.dumps(context.runtime.model_turn)
    assert "data:image" not in str(events)


@pytest.mark.asyncio
async def test_active_loop_bounds_source_images_across_rounds_and_retains_fallback(monkeypatch):
    """Private source evidence is bounded and rejected pixels are not retried each round."""
    from copy import deepcopy

    from deeptutor.services.llm.multimodal import has_image_parts

    class Registry(_Registry):
        async def execute(self, name, **kwargs):
            result = await super().execute(name, **kwargs)
            count = len(self.executed)
            result.model_message = {
                "role": "user",
                "content": [
                    {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{count}{i}"}}
                    for i in range(2)
                ],
            }
            return result

    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(
                    tool_calls=[
                        {"id": "one", "name": "web_search", "arguments": '{"query":"one"}'}
                    ],
                    finish_reason="tool_calls",
                )
            ],
            [
                _llm_chunk(
                    tool_calls=[
                        {"id": "two", "name": "web_search", "arguments": '{"query":"two"}'}
                    ],
                    finish_reason="tool_calls",
                )
            ],
            [_llm_chunk(content="Continue.", finish_reason="length")],
            [_llm_chunk(content="Done.", finish_reason="stop")],
        ]
    )
    create = client.chat.completions.create
    attempts = []

    async def reject_latest_images(**kwargs):
        attempts.append(deepcopy(kwargs["messages"]))
        if client.call_count == 2 and has_image_parts(kwargs["messages"]):
            raise RuntimeError("image input is not supported")
        return await create(**kwargs)

    client.chat.completions.create = reject_latest_images
    pipeline = AgenticChatPipeline(language="en")
    pipeline.model = "gpt-3.5-turbo"
    pipeline.registry = Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)
    context = UnifiedContext(session_id="s", user_message="Explain source figures.")
    await _run(pipeline, context)
    images = [
        part["image_url"]["url"]
        for msg in attempts[2]
        if isinstance(msg.get("content"), list)
        for part in msg["content"]
        if part.get("type") == "image_url"
    ]
    assert images == ["data:image/png;base64,20", "data:image/png;base64,21"]
    assert not has_image_parts(attempts[3])
    assert not has_image_parts(attempts[4])
    assert "base64" not in json.dumps(context.runtime.model_turn)


@pytest.mark.asyncio
async def test_rejected_forced_choice_keeps_schemas_for_all_later_rounds(monkeypatch):
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(
                    tool_calls=[{"id": "a", "name": "web_search", "arguments": '{"query":"test"}'}],
                    finish_reason="tool_calls",
                )
            ],
            [_llm_chunk(content="Answer", finish_reason="stop")],
        ]
    )
    accepted_create = client.chat.completions.create
    attempts = []

    async def create(**kwargs):
        attempts.append(dict(kwargs))
        if isinstance(kwargs.get("tool_choice"), dict):
            raise RuntimeError("thinking mode does not support this tool_choice")
        return await accepted_create(**kwargs)

    client.chat.completions.create = create
    pipeline = AgenticChatPipeline(language="en", initial_tool_choice="web_search")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)
    context = UnifiedContext(session_id="s", user_message="Search")
    events = await _run(pipeline, context)
    assert _answer_text(events) == "Answer"
    assert len(attempts) == 3
    assert all(call["tools"] == attempts[0]["tools"] for call in attempts)
    assert attempts[1]["tool_choice"] == "auto"
    assert context.runtime.model_turn["tools"] == attempts[-1]["tools"]


@pytest.mark.asyncio
async def test_context_guard_is_told_which_tool_schemas_each_request_carries(monkeypatch):
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(
                    tool_calls=[{"id": "a", "name": "web_search", "arguments": '{"query":"test"}'}],
                    finish_reason="tool_calls",
                )
            ],
            [_llm_chunk(content="Answer", finish_reason="stop")],
        ]
    )
    accepted_create = client.chat.completions.create
    sent_tools = []

    async def create(**kwargs):
        sent_tools.append(kwargs.get("tools") or None)
        return await accepted_create(**kwargs)

    client.chat.completions.create = create
    pipeline = AgenticChatPipeline(language="en", initial_tool_choice="web_search")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)
    guard = pipeline._guard_context_window
    guarded_tools = []

    async def recording_guard(messages, stream, **kwargs):
        guarded_tools.append(kwargs.get("tool_schemas") or None)
        await guard(messages, stream, **kwargs)

    monkeypatch.setattr(pipeline, "_guard_context_window", recording_guard)
    context = UnifiedContext(session_id="s", user_message="Search")
    events = await _run(pipeline, context)
    assert _answer_text(events) == "Answer"
    assert sent_tools[0]
    assert guarded_tools == sent_tools


@pytest.mark.asyncio
async def test_persisted_tool_turn_extends_request_prefix_after_resume(monkeypatch, tmp_path):
    """A new pipeline/database read must preserve seed, reasoning and tools."""
    from deeptutor.core.context import WorkspaceRuntimeContext
    from deeptutor.services.session.context_builder import ContextBuilder
    from deeptutor.services.session.sqlite_store import SQLiteSessionStore

    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(
                    content="Checking. ",
                    reasoning_content="private plan",
                    tool_calls=[
                        {"id": "search-1", "name": "web_search", "arguments": '{"query":"cache"}'},
                    ],
                    finish_reason="tool_calls",
                )
            ],
            [
                _llm_chunk(
                    content="The answer.", reasoning_content="private finish", finish_reason="stop"
                )
            ],
            [_llm_chunk(content="The follow-up.", finish_reason="stop")],
        ]
    )

    def pipeline():
        result = AgenticChatPipeline(language="en")
        result.registry = _Registry()
        monkeypatch.setattr(result, "_compose_enabled_tools", lambda _: ["web_search"])
        monkeypatch.setattr(result, "_build_openai_client", lambda: client)
        return result

    first = UnifiedContext(
        session_id="cache-session",
        user_message="Question",
        runtime=TurnRuntimeContext(
            workspace=WorkspaceRuntimeContext(logical_output_dir="outputs/turn-1"),
        ),
    )
    await _run(pipeline(), first)
    record = first.runtime.model_turn
    assert record is not None
    assert [m["role"] for m in record["messages"][-3:]] == [
        "assistant",
        "tool",
        "assistant",
    ]
    assert record["messages"][-4] == {"role": "user", "content": "Question"}
    store = SQLiteSessionStore(db_path=tmp_path / "history.db")
    session = await store.create_session()
    sid = session["id"]
    await store.add_message(sid, "user", "Question")
    await store.add_message(
        sid, "assistant", "Display text may be repaired", metadata={"model_turn": record}
    )
    # Reopen the store: replay cannot depend on an in-memory loop instance.
    restored = SQLiteSessionStore(db_path=tmp_path / "history.db")
    built = await ContextBuilder(restored).build(
        session_id=sid,
        llm_config=SimpleNamespace(
            model="gpt-test",
            context_window=128000,
            max_tokens=4096,
        ),
    )
    second = UnifiedContext(
        session_id="cache-session",
        user_message="Follow-up",
        runtime=TurnRuntimeContext(
            workspace=WorkspaceRuntimeContext(logical_output_dir="outputs/turn-2"),
            model_history=built.model_history,
            previous_model_turn=built.previous_model_turn,
        ),
    )
    await _run(pipeline(), second)
    previous, resumed = client.calls[1], client.calls[2]
    assert previous["tools"] == resumed["tools"]
    # The fresh workspace slot replaces its obsolete runtime snapshot while
    # durable dialogue, reasoning, and tool protocol remain an exact prefix.
    retained = [
        message
        for message in previous["messages"]
        if not str(message.get("content", "")).startswith("[Runtime context: workspace]")
    ]
    assert resumed["messages"][: len(retained)] == retained
    assert "outputs/turn-1" not in resumed["messages"][0]["content"]
    assert "outputs/turn-2" in resumed["messages"][-2]["content"]
    assert resumed["messages"][-3]["reasoning_content"] == "private finish"
    assert all("_context_snapshot" not in m for m in resumed["messages"])
    updates = [
        m["_context_snapshot"]
        for m in second.runtime.model_turn["messages"]
        if "_context_snapshot" in m
    ]
    assert updates == ["workspace"]


def test_runtime_sections_are_updated_and_cleared_independently(monkeypatch):
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_build_notebook_manifest", lambda: "")
    first = UnifiedContext(user_message="Hello", memory_context="The learner prefers diagrams.")
    messages = pipeline._build_loop_messages(context=first, enabled_tools=[])
    second = UnifiedContext(
        user_message="Continue",
        memory_context="The learner prefers diagrams.",
        runtime=TurnRuntimeContext(
            model_history=messages[1:] + [{"role": "assistant", "content": "Hi"}]
        ),
    )
    same = pipeline._build_loop_messages(context=second, enabled_tools=[])
    assert same[-1] == {"role": "user", "content": "Continue"}
    assert len(same) == len(messages) + 2
    second.memory_context = ""
    cleared = pipeline._build_loop_messages(context=second, enabled_tools=[])
    assert cleared[0] == same[0]
    assert cleared[-2]["_context_snapshot"] == "memory"
    assert "empty" in cleared[-2]["content"]
    assert cleared[-3]["content"] == "Hi"


def _contents(events: list[StreamEvent]) -> list[str]:
    return [e.content for e in events if e.type == StreamEventType.CONTENT]


def _answer_text(events: list[StreamEvent]) -> str:
    """Published answer chunks remain visible regardless of completion markers."""
    return "".join(
        event.content
        for event in events
        if event.type == StreamEventType.CONTENT
        and (
            not event.metadata.get("call_id")
            or event.metadata.get("call_kind") in ANSWER_BEARING_CALL_KINDS
        )
    )


def _call_roles(events: list[StreamEvent]) -> list[str]:
    """Ordered list of per-round call_role markers ('narration' | 'finish')."""
    return [
        str(e.metadata.get("call_role"))
        for e in events
        if e.type == StreamEventType.PROGRESS
        and e.metadata.get("call_state") == "complete"
        and "call_role" in e.metadata
    ]


def _result(events: list[StreamEvent]) -> StreamEvent:
    return [e for e in events if e.type == StreamEventType.RESULT][-1]


class TestInlineThinkFilter:
    @staticmethod
    def _run(chunks: list[str]) -> list[tuple[str, str]]:
        f = InlineThinkFilter()
        out: list[tuple[str, str]] = []
        for c in chunks:
            out.extend(f.feed(c))
        out.extend(f.flush())
        return out

    @staticmethod
    def _join(segments: list[tuple[str, str]], kind: str) -> str:
        return "".join(text for k, text in segments if k == kind)

    def test_plain_content_passes_through(self) -> None:
        segs = self._run(["hello ", "world"])
        assert self._join(segs, "content") == "hello world"
        assert self._join(segs, "thinking") == ""

    def test_think_block_split_to_thinking(self) -> None:
        segs = self._run(["<think>plan</think>answer"])
        assert self._join(segs, "thinking") == "plan"
        assert self._join(segs, "content") == "answer"

    def test_tag_split_across_chunks(self) -> None:
        segs = self._run(["before<thi", "nk>inner</th", "ink>after"])
        assert self._join(segs, "content") == "beforeafter"
        assert self._join(segs, "thinking") == "inner"

    def test_unclosed_think_stays_thinking(self) -> None:
        # Interrupted stream: an opened think block never closes — its text
        # must never surface as content (mirrors clean_thinking_tags).
        segs = self._run(["<think>only reasoning, no answer"])
        assert self._join(segs, "content") == ""
        assert "only reasoning" in self._join(segs, "thinking")

    def test_thinking_variant_tag(self) -> None:
        segs = self._run(["<thinking>x</thinking>y"])
        assert self._join(segs, "thinking") == "x"
        assert self._join(segs, "content") == "y"

    def test_non_think_tags_untouched(self) -> None:
        segs = self._run(["a <b>bold</b> ", "and a < b comparison"])
        assert self._join(segs, "content") == "a <b>bold</b> and a < b comparison"

    def test_multiple_think_blocks(self) -> None:
        segs = self._run(["<think>1</think>mid<think>2</think>end"])
        assert self._join(segs, "content") == "midend"
        assert self._join(segs, "thinking") == "12"


@pytest.mark.asyncio
async def test_inline_think_streams_to_trace_not_bubble(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """Providers that inline <think> in the content channel: think text must
    stream as thinking events; only the post-think text is user content."""
    registry = _Registry()
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(content="<think>let me "),
                _llm_chunk(content="reason</think>"),
                _llm_chunk(content="The answer."),
            ]
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(pipeline, UnifiedContext(session_id="s1", user_message="Hi"))

    assert _contents(events) == ["The answer."]
    thinking = "".join(e.content for e in events if e.type == StreamEventType.THINKING)
    assert "let me reason" in thinking
    result = _result(events)
    assert result.metadata["response"] == "The answer."
    assert result.metadata["completed"] is True


@pytest.mark.asyncio
async def test_multi_chunk_usage_counts_as_one_call(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """Gemini OpenAI-compat (and similar) may attach usage to several stream
    chunks. Each completion must still count as one call with the final
    token totals — not N× inflated ``total_calls`` / tokens."""
    usage_partial = SimpleNamespace(prompt_tokens=100, completion_tokens=2, total_tokens=102)
    usage_final = SimpleNamespace(prompt_tokens=100, completion_tokens=5, total_tokens=105)
    registry = _Registry()
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(content="Hello", usage=usage_partial),
                _llm_chunk(content=" world", usage=usage_partial),
                _llm_chunk(content=".", finish_reason="stop", usage=usage_partial),
                _usage_only_chunk(prompt=100, completion=5, total=105),
            ]
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(pipeline, UnifiedContext(session_id="s1", user_message="Hi"))

    assert "".join(_contents(events)) == "Hello world."
    assert client.call_count == 1
    summary = pipeline.usage.summary()
    assert summary is not None
    assert summary["total_calls"] == 1
    assert summary["prompt_tokens"] == 100
    assert summary["completion_tokens"] == 5
    assert summary["total_tokens"] == 105
    # Final usage frame wins over earlier partials.
    assert usage_final.total_tokens == summary["total_tokens"]
    result = _result(events)
    cost = (result.metadata.get("metadata") or {}).get("cost_summary") or result.metadata.get(
        "cost_summary"
    )
    if cost is not None:
        assert cost["total_calls"] == 1
        assert cost["total_tokens"] == 105


@pytest.mark.asyncio
async def test_capability_can_intentionally_finish_with_empty_text(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """Structured-artifact capabilities suppress prose after committing it."""

    registry = _Registry()
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(
                    tool_calls=[
                        {
                            "id": "commit-1",
                            "name": "web_search",
                            "arguments": json.dumps({"query": "commit artifact"}),
                        }
                    ]
                )
            ]
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)
    monkeypatch.setattr(pipeline, "_has_capability_finish_guard", lambda _context: True)
    monkeypatch.setattr(
        pipeline,
        "_capability_final_text_override",
        lambda _context, _text: "",
    )

    events = await _run(
        pipeline,
        UnifiedContext(session_id="structured", user_message="Build the artifact"),
    )

    assert _contents(events) == []
    result = _result(events)
    assert result.metadata["completed"] is True
    assert result.metadata["response"] == ""


@pytest.mark.asyncio
async def test_empty_finish_gets_one_nudge_then_recovers(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A tool-less round that is ALL internal reasoning must not finalize as
    an empty answer: the loop nudges once and the model recovers."""
    registry = _Registry()
    client = _ScriptedChatClient(
        [
            # Round 1: the model "finishes" with nothing but think text.
            [_llm_chunk(content="<think>I wrote a whole script here</think>")],
            # Round 2 (after the nudge): a real answer.
            [_llm_chunk(content="Here is the real answer.")],
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(pipeline, UnifiedContext(session_id="s1", user_message="Make a PDF"))

    assert client.call_count == 2
    # The nudge round keeps the raw think text in-conversation and appends
    # the nudge instruction as the trailing user message.
    second_round = client.calls[1]["messages"]
    assert second_round[-1]["role"] == "user"
    assert "internal reasoning" in second_round[-1]["content"]
    assert any(
        m.get("role") == "assistant" and "whole script" in str(m.get("content"))
        for m in second_round
    )
    result = _result(events)
    assert result.metadata["response"] == "Here is the real answer."
    assert result.metadata["completed"] is True


@pytest.mark.asyncio
async def test_empty_round_nudge_keeps_multimodal_user_parts(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A nudge must extend a multimodal user message, never stringify it.

    A chat PDF's embedded images ride in the trailing user message's content
    parts. A round that finishes with nothing to replay leaves that message
    trailing, so the recovery directive is appended to it; rebuilding the
    message as a string folds every ``data:...;base64,`` payload into prompt
    text and the next round bills image bytes as language tokens.
    """
    image = {"type": "image_url", "image_url": {"url": "data:image/png;base64,YWJj"}}
    messages = [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "[Attached Documents]\nQuestion sheet"},
                image,
            ],
        }
    ]
    client = _ScriptedChatClient(
        [
            # Round 1: an empty finish — no text, no reasoning, no tool call.
            [_llm_chunk(finish_reason="stop")],
            # Round 2 (after the nudge): a real answer.
            [_llm_chunk(content="Here is the real answer.")],
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    pipeline._model_turn_start = 0
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)
    monkeypatch.setattr(pipeline, "_build_loop_messages", lambda *_args, **_kwargs: messages)

    events = await _run(pipeline, UnifiedContext(session_id="s1", user_message="Solve it"))

    assert client.call_count == 2
    durable = messages[0]["content"]
    assert isinstance(durable, list)
    assert [part["type"] for part in durable] == ["text", "image_url"]
    assert durable[0]["text"].startswith("[Attached Documents]\nQuestion sheet")
    assert "internal reasoning" in durable[0]["text"]
    assert durable[1] == image
    # The round the provider receives still carries the image as an image.
    wire = client.calls[1]["messages"][-1]["content"]
    assert any(part.get("type") == "image_url" for part in wire)
    result = _result(events)
    assert result.metadata["response"] == "Here is the real answer."
    assert result.metadata["completed"] is True


@pytest.mark.asyncio
async def test_pure_image_message_gets_its_own_directive_part(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A message holding only images has no text part to extend."""
    image = {"type": "image_url", "image_url": {"url": "data:image/png;base64,YWJj"}}
    messages = [{"role": "user", "content": [image]}]
    client = _ScriptedChatClient(
        [
            [_llm_chunk(finish_reason="stop")],
            [_llm_chunk(content="Answered from the image.")],
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    pipeline._model_turn_start = 0
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)
    monkeypatch.setattr(pipeline, "_build_loop_messages", lambda *_args, **_kwargs: messages)

    await _run(pipeline, UnifiedContext(session_id="s1", user_message="What is this?"))

    durable = messages[0]["content"]
    assert [part["type"] for part in durable] == ["image_url", "text"]
    assert "internal reasoning" in durable[1]["text"]
    assert durable[0] == image


@pytest.mark.asyncio
async def test_explore_context_pre_pass_seeds_loop_without_polluting_answer(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """When the user attaches fresh context, the explore_context pre-pass runs
    before the answer loop and folds an objective briefing into the loop's
    user-message seed — while its own output never appears as the answer."""

    def _fake_explore_stream(*_args, **_kwargs):
        async def _gen():
            yield "The user and the external agent updated the navigation."

        return _gen()

    monkeypatch.setattr(explorer_mod, "llm_stream", _fake_explore_stream)
    monkeypatch.setattr(
        explorer_mod,
        "get_llm_config",
        lambda: SimpleNamespace(
            model="gpt-test", api_key="k", base_url="u", api_version=None, binding="openai"
        ),
    )

    registry = _Registry()
    client = _ScriptedChatClient([[_llm_chunk(content="Here is what that chat did.")]])
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    context = UnifiedContext(
        session_id="s1",
        user_message="what did this chat do?",
        source_manifest="[Attached Sources]\n- id=hs-imported_claude_code_x type=history",
        metadata={
            "source_index": {"hs-imported_claude_code_x": "## Claude Code\nI updated the nav."},
            "history_references": ["imported_claude_code_x"],
        },
    )
    events = await _run(pipeline, context)

    # The briefing rode into the answer loop's trailing user message (the seed).
    first_call_messages = client.calls[0]["messages"]
    seed_user_msg = first_call_messages[-1]["content"]
    assert "external agent updated the navigation" in seed_user_msg

    # The pre-pass streamed THINKING (reasoning trace), never CONTENT — the
    # answer is only the chat loop's finish text.
    assert _contents(events) == ["Here is what that chat did."]
    explore_thinking = "".join(
        e.content
        for e in events
        if e.type == StreamEventType.THINKING
        and str((e.metadata or {}).get("call_kind")) == "context_exploration"
    )
    assert "external agent updated the navigation" in explore_thinking


@pytest.mark.asyncio
async def test_finish_first_round_no_tools(monkeypatch: pytest.MonkeyPatch) -> None:
    """A request that needs no exploration: the first round emits no tool
    calls, so it IS the finish — one LLM call, streamed straight to the user."""
    registry = _Registry()
    client = _ScriptedChatClient([[_llm_chunk(content="A direct answer.")]])
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(pipeline, UnifiedContext(session_id="s1", user_message="Hello"))

    assert client.call_count == 1
    # The finish round's text streams to the user, not the trace.
    assert _contents(events) == ["A direct answer."]
    assert _call_roles(events) == ["finish"]
    result = _result(events)
    assert result.metadata["engine"] == "agent_loop"
    assert result.metadata["completed"] is True
    assert result.metadata["response"] == "A direct answer."
    assert result.metadata["rounds"] == 1
    assert result.metadata["tool_steps"] == 0


@pytest.mark.asyncio
async def test_anthropic_gateway_request_carries_cache_control_breakpoints(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """The loop must apply the provider's prompt-caching treatment (#2078).

    The loop builds its own request kwargs, so an ``anthropic/`` model on a
    prompt-caching gateway used to send no ``cache_control`` breakpoint at all.
    It now marks system, the last message, and the end of the durable history.
    """
    monkeypatch.setattr(
        "deeptutor.agents.loop.pipeline.get_llm_config",
        lambda: SimpleNamespace(
            binding="openrouter",
            model="anthropic/claude-haiku-5.5",
            api_key="k",
            base_url="https://openrouter.ai/api/v1",
            api_version=None,
            extra_headers={},
            reasoning_effort=None,
        ),
    )
    client = _ScriptedChatClient([[_llm_chunk(content="Answer", finish_reason="stop")]])
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    durable = [
        {"role": "user", "content": "Question one"},
        {"role": "assistant", "content": "Answer one"},
    ]
    await _run(
        pipeline,
        UnifiedContext(
            session_id="s1",
            user_message="Question two",
            runtime=TurnRuntimeContext(model_history=list(durable)),
        ),
    )

    sent = client.calls[0]["messages"]
    marked = [
        index
        for index, message in enumerate(sent)
        if isinstance(message.get("content"), list)
        and any(
            isinstance(block, dict) and "cache_control" in block for block in message["content"]
        )
    ]
    # system + end-of-stable-history (the durable assistant turn) + last message.
    assert len(marked) == 3
    assert sent[0]["role"] == "system"
    # The middle breakpoint sits on the last durable assistant turn, before the
    # trailing (possibly multi-message) user block of this turn.
    assert sent[marked[1]]["role"] == "assistant"
    assert sent[marked[1]]["content"][-1]["text"] == "Answer one"
    assert marked[-1] == len(sent) - 1
    assert sent[-1]["role"] == "user"
    assert all(
        block.get("cache_control") == {"type": "ephemeral"}
        for index in marked
        for block in sent[index]["content"]
        if isinstance(block, dict) and "cache_control" in block
    )


@pytest.mark.asyncio
async def test_non_anthropic_gateway_request_gets_no_cache_control(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A non-Anthropic model on the same gateway must not receive markers."""
    monkeypatch.setattr(
        "deeptutor.agents.loop.pipeline.get_llm_config",
        lambda: SimpleNamespace(
            binding="openrouter",
            model="google/gemini-2.0-flash",
            api_key="k",
            base_url="https://openrouter.ai/api/v1",
            api_version=None,
            extra_headers={},
            reasoning_effort=None,
        ),
    )
    client = _ScriptedChatClient([[_llm_chunk(content="Answer", finish_reason="stop")]])
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    await _run(pipeline, UnifiedContext(session_id="s1", user_message="Hi"))

    assert all(
        not isinstance(message.get("content"), list) for message in client.calls[0]["messages"]
    )


@pytest.mark.asyncio
async def test_native_anthropic_binding_leaves_markers_to_the_provider(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """The native Anthropic adapter applies its own cache_control.

    The loop must not pre-mark that path, or the adapter's own breakpoints
    would be added on top of the loop's.
    """
    monkeypatch.setattr(
        "deeptutor.agents.loop.pipeline.get_llm_config",
        lambda: SimpleNamespace(
            binding="anthropic",
            model="claude-sonnet-4-5",
            api_key="k",
            base_url="https://api.anthropic.com",
            api_version=None,
            extra_headers={},
            reasoning_effort=None,
        ),
    )
    client = _ScriptedChatClient([[_llm_chunk(content="Answer", finish_reason="stop")]])
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    await _run(pipeline, UnifiedContext(session_id="s1", user_message="Hi"))

    assert all(
        not isinstance(message.get("content"), list) for message in client.calls[0]["messages"]
    )


@pytest.mark.asyncio
async def test_finish_round_persists_provider_response_state(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    registry = _Registry()
    native_items = [{"type": "reasoning", "id": "rs_1", "summary": []}]
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(
                    content="A direct answer.",
                    reasoning_content="private reasoning",
                    provider_specific_fields={"native_output_items": native_items},
                )
            ]
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)
    context = UnifiedContext(session_id="s1", user_message="Hello")

    await _run(pipeline, context)

    assert context.runtime.provider_response_state == {
        "responses_output_items": native_items,
        "reasoning_content": "private reasoning",
    }


@pytest.mark.asyncio
@pytest.mark.parametrize("call_count", [8, 15, 16, 18])
@pytest.mark.parametrize("forced_finish", [False, True])
@pytest.mark.parametrize("pipeline_type", [AgenticChatPipeline, MasteryLoopPipeline])
async def test_tool_batch_limit_preserves_all_call_results(
    monkeypatch: pytest.MonkeyPatch, call_count: int, forced_finish: bool, pipeline_type: type
) -> None:
    """Overflow calls must be answered before either continuation or hard finish."""
    registry = _Registry()
    calls = [
        {"id": f"call-{i}", "name": "web_search", "arguments": json.dumps({"query": f"q{i}"})}
        for i in range(call_count)
    ]
    native_items = [
        {
            "type": "function_call",
            "call_id": call["id"],
            "name": call["name"],
            "arguments": call["arguments"],
        }
        for call in calls
    ]
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(
                    tool_calls=calls, provider_specific_fields={"native_output_items": native_items}
                )
            ],
            [_llm_chunk(content="Answer after tools.")],
        ]
    )
    pipeline = pipeline_type(language="en")
    pipeline.registry = registry
    if forced_finish:
        pipeline._max_rounds = 1
        monkeypatch.setattr(agent_loop_mod, "MAX_SETTLEMENT_ROUNDS", 0)
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(
        pipeline,
        UnifiedContext(session_id="s1", user_message="Research", enabled_tools=["web_search"]),
    )

    assert client.call_count == 2
    assert ("tools" not in client.calls[1]) is forced_finish
    assert [entry["kwargs"]["query"] for entry in registry.executed] == [
        f"q{i}" for i in range(min(call_count, 15))
    ]
    messages = client.calls[1]["messages"]
    assistant_index = next(i for i, message in enumerate(messages) if message.get("tool_calls"))
    tool_messages = messages[assistant_index + 1 : assistant_index + 1 + call_count]
    assert [message.get("role") for message in tool_messages] == ["tool"] * call_count
    assert [message["tool_call_id"] for message in tool_messages] == [call["id"] for call in calls]
    for message in tool_messages[15:]:
        assert "not executed" in message["content"]
        assert "15" in message["content"]
    # Responses replay uses the native calls, so it needs the same complete pairing.
    _instructions, input_items = convert_messages(messages)
    assert [item["call_id"] for item in input_items if item.get("type") == "function_call"] == [
        item["call_id"] for item in input_items if item.get("type") == "function_call_output"
    ]
    assert _result(events).metadata["response"] == "Answer after tools."


@pytest.mark.asyncio
async def test_tool_round_then_finish(monkeypatch: pytest.MonkeyPatch) -> None:
    """A tool round (narration text + a tool call) is followed by a tool-less
    finish round whose text is the answer — two LLM calls, no respond pass."""
    registry = _Registry()
    client = _ScriptedChatClient(
        [
            # Round 1: preamble (narration) text + a tool call.
            [
                _llm_chunk(content="Searching.", reasoning_content="round one private reasoning"),
                _llm_chunk(
                    tool_calls=[
                        {
                            "id": "call-1",
                            "name": "web_search",
                            "arguments": json.dumps({"query": "Fourier transform"}),
                        }
                    ]
                ),
            ],
            # Round 2: the model sees the tool result in-protocol and finishes
            # by replying without tool calls.
            [_llm_chunk(content="Found what was needed.", reasoning_content="final reasoning")],
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(
        pipeline,
        UnifiedContext(
            session_id="s1", user_message="Look up Fourier", enabled_tools=["web_search"]
        ),
    )

    assert client.call_count == 2
    assert registry.executed[0]["name"] == "web_search"
    assert registry.executed[0]["kwargs"]["query"] == "Fourier transform"
    # Both rounds' text streams to the user; the round roles distinguish them.
    assert _contents(events) == ["Searching.", "Found what was needed."]
    assert _call_roles(events) == ["narration", "finish"]
    # Round 2 sees the tool exchange in-protocol: the assistant tool_calls
    # message (with its preamble text) followed by the role=tool result.
    second_round = client.calls[1]["messages"]
    assistant_tc = [m for m in second_round if m.get("role") == "assistant" and m.get("tool_calls")]
    assert assistant_tc and assistant_tc[0]["tool_calls"][0]["function"]["name"] == "web_search"
    assert assistant_tc[0]["content"] == "Searching."
    assert assistant_tc[0]["_provider_response_state"] == {
        "reasoning_content": "round one private reasoning"
    }
    tool_msgs = [m for m in second_round if m.get("role") == "tool"]
    assert tool_msgs and "tool answer" in tool_msgs[0]["content"]
    result = _result(events)
    assert result.metadata["tool_steps"] == 1
    assert result.metadata["rounds"] == 2
    # The reader keeps BOTH: the commentary that introduced the search and the
    # closing answer, in the order they were written.
    assert _answer_text(events) == "Searching.Found what was needed."
    # RESULT still reports the closing answer alone — it is what an SDK caller
    # or a title generator asked for, not the running commentary.
    assert result.metadata["response"] == "Found what was needed."


@pytest.mark.asyncio
async def test_gemini_tool_round_replays_thought_signature(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """The second request must echo Gemini's signature on the assistant
    function call, otherwise the compatibility endpoint returns HTTP 400."""
    registry = _Registry()
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(
                    tool_calls=[
                        {
                            "id": "function-call-1",
                            "name": "web_search",
                            "arguments": json.dumps({"query": "Fourier transform"}),
                            "extra_content": {
                                "google": {"thought_signature": "signature-from-gemini"}
                            },
                        }
                    ]
                )
            ],
            [_llm_chunk(content="Found it.")],
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    await _run(
        pipeline,
        UnifiedContext(
            session_id="s1",
            user_message="Look up Fourier",
            enabled_tools=["web_search"],
        ),
    )

    second_round = client.calls[1]["messages"]
    assistant_message = next(message for message in second_round if message.get("tool_calls"))
    assistant_call = assistant_message["tool_calls"][0]
    assert assistant_call["extra_content"] == {
        "google": {"thought_signature": "signature-from-gemini"}
    }


@pytest.mark.asyncio
async def test_partner_group_answer_plus_invoke_finishes_in_one_round(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A model may combine its formal answer and proposal despite the prompt.

    The answer is accepted before dispatch and the proposal terminates the
    private protocol, so the model never gets a chance to rewrite the answer.
    """

    class _InvokeRegistry(_Registry):
        def build_openai_schemas(self, _enabled):
            return [InvokeOtherTool().get_definition().to_openai_schema()]

        async def execute(self, name: str, **kwargs):
            kwargs.pop("event_sink", None)
            self.executed.append({"name": name, "kwargs": kwargs})
            return await InvokeOtherTool().execute(**kwargs)

    registry = _InvokeRegistry()
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(content="The formal answer."),
                _llm_chunk(
                    tool_calls=[
                        {
                            "id": "invoke-1",
                            "name": "invoke_other",
                            "arguments": json.dumps(
                                {
                                    "target_partner_id": "bob",
                                    "question": "Which premise should we test?",
                                }
                            ),
                        }
                    ]
                ),
            ]
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["invoke_other"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)
    context = UnifiedContext(
        session_id="group:ada:test",
        user_message="Discuss this",
        metadata={
            "source": "partner",
            "partner_group": {
                "group_id": "panel",
                "name": "Panel",
                "self_id": "ada",
                "allow_invoke_other": True,
                "members": [
                    {"partner_id": "ada", "name": "Ada"},
                    {"partner_id": "bob", "name": "Bob"},
                ],
            },
        },
    )

    events = await _run(pipeline, context)

    assert client.call_count == 1
    assert _contents(events) == ["The formal answer."]
    assert _result(events).metadata["response"] == "The formal answer."
    assert context.extension("partner_group")["invocation_proposal"] == {
        "target_partner_id": "bob",
        "target_partner_name": "Bob",
        "question": "Which premise should we test?",
    }


@pytest.mark.asyncio
async def test_invoked_group_reply_strips_dangling_peer_question_in_one_round(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    dangling = (
        "The complete invoked answer.\n\n---\n\n**想请教一下 @ada:**\n你还会建议用户做什么?"
    )
    client = _ScriptedChatClient([[_llm_chunk(content=dangling)]])
    pipeline = AgenticChatPipeline(language="zh")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)
    context = UnifiedContext(
        session_id="group:bob:invoked",
        user_message="Ada asks you directly in the Group: answer this",
        metadata={
            "source": "partner",
            "partner_group": {
                "group_id": "panel",
                "name": "Panel",
                "self_id": "bob",
                "allow_invoke_other": False,
                "members": [
                    {"partner_id": "ada", "name": "Ada"},
                    {"partner_id": "bob", "name": "Bob"},
                ],
            },
        },
    )

    events = await _run(pipeline, context)

    assert client.call_count == 1
    assert _contents(events) == ["The complete invoked answer."]
    assert _result(events).metadata["response"] == "The complete invoked answer."
    assert "invocation_proposal" not in context.extension("partner_group")


@pytest.mark.asyncio
async def test_mastery_tool_round_keeps_teaching_markdown_visible(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """Mastery teaching may share a native tool round with quiz setup.

    The prose must stay in the answer surface after the round resolves instead
    of being demoted into the compact reasoning trace (issue #855).
    """

    class _MasteryRegistry(_Registry):
        def build_openai_schemas(self, enabled):
            schemas = super().build_openai_schemas(enabled)
            schemas.append(
                {
                    "type": "function",
                    "function": {
                        "name": "mastery_quiz",
                        "description": "Register a mastery quiz",
                        "parameters": {"type": "object", "properties": {}},
                    },
                }
            )
            return schemas

        async def execute(self, name: str, **kwargs):
            if name == "mastery_quiz":
                # One call registers the question AND poses it on its own
                # answer card — then ends the turn, the way the real tool
                # signals it through the injected callback.
                self.executed.append({"name": name, "kwargs": kwargs})
                kwargs["_end_turn_on_card"]()
                return ToolResult(
                    content="The question is on the learner's answer card.",
                    success=True,
                    metadata={"ask_user": {"questions": [{"id": "q1", "prompt": "Which sum?"}]}},
                )
            return await super().execute(name, **kwargs)

    explanation = (
        "### Binary addition\n\n"
        "| Carry | Sum |\n"
        "| --- | --- |\n"
        "| 1 | 0 |\n\n"
        "Use the carry column to work through the next question."
    )
    registry = _MasteryRegistry()
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(content=explanation),
                _llm_chunk(
                    tool_calls=[
                        {
                            "id": "quiz-1",
                            "name": "mastery_quiz",
                            "arguments": "{}",
                        }
                    ]
                ),
            ],
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    monkeypatch.setattr(
        pipeline,
        "_compose_enabled_tools",
        lambda _context: ["mastery_quiz"],
    )
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(
        pipeline,
        UnifiedContext(
            session_id="s1",
            user_message="Teach me binary addition",
            enabled_tools=["mastery_quiz"],
            metadata={"mastery_mode": True, "mastery_path_id": ""},
        ),
    )

    markers = [
        event.metadata
        for event in events
        if event.type == StreamEventType.PROGRESS
        and event.metadata.get("call_state") == "complete"
        and "call_role" in event.metadata
    ]
    assert markers[0]["call_role"] == "narration"
    assert markers[0]["answer_visible"] is True
    joined_content = "".join(_contents(events))
    assert joined_content.startswith(explanation)
    # Posing the card ends the turn: no second LLM round, no parked turn, and
    # the teaching prose is the answer this turn leaves behind.
    assert client.call_count == 1
    assert [row["name"] for row in registry.executed] == ["mastery_quiz"]
    result = _result(events)
    assert result.metadata["completed"] is True


@pytest.mark.asyncio
@pytest.mark.parametrize(
    "plain_quiz",
    [
        (
            "Which expression builds a dictionary?\n\n"
            "- A. `{w: words.count(w) for w in words}`\n"
            "- B. `[w: words.count(w) for w in words]`\n"
            "- C. `{w for w in words}`\n"
            "- D. `(w: words.count(w) for w in words)`"
        ),
        (
            "请选择正确的字典推导式:\n\n"
            "- A. `{w: words.count(w) for w in words}`\n"
            "- B. `[w: words.count(w) for w in words]`\n"
            "- C. `{w for w in words}`\n"
            "- D. `(w: words.count(w) for w in words)`"
        ),
    ],
)
async def test_mastery_choice_explanation_is_not_redirected(
    plain_quiz: str,
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """Choice-shaped prose remains visible without forcing a registered card."""

    class _MasteryCardRegistry(_Registry):
        def build_openai_schemas(self, enabled):
            schemas = super().build_openai_schemas(enabled)
            schemas.append(
                {
                    "type": "function",
                    "function": {
                        "name": "mastery_quiz",
                        "description": "Register a mastery quiz",
                        "parameters": {"type": "object", "properties": {}},
                    },
                }
            )
            return schemas

        async def execute(self, name: str, **kwargs):
            if name == "mastery_quiz":
                self.executed.append({"name": name, "kwargs": kwargs})
                return ToolResult(
                    content="[awaiting the learner's answer]",
                    success=True,
                    pause_for_user={"questions": [{"id": "q1", "prompt": "Which expression?"}]},
                )
            return await super().execute(name, **kwargs)

    registry = _MasteryCardRegistry()
    client = _ScriptedChatClient(
        [
            [_llm_chunk(content=plain_quiz)],
            [
                _llm_chunk(
                    tool_calls=[
                        {
                            "id": "quiz-1",
                            "name": "mastery_quiz",
                            "arguments": "{}",
                        }
                    ]
                )
            ],
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["mastery_quiz"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(
        pipeline,
        UnifiedContext(
            session_id="s1",
            user_message="Continue",
            enabled_tools=["mastery_quiz"],
            metadata={"mastery_mode": True, "mastery_path_id": ""},
        ),
    )

    assert client.call_count == 1
    assert not registry.executed
    assert _result(events).metadata["completed"] is True
    assert _result(events).metadata["response"] == plain_quiz
    assert _answer_text(events) == plain_quiz


@pytest.mark.asyncio
async def test_graded_review_reaches_the_learner(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """Feedback on a graded answer must not read as a plain-text quiz.

    Walking the options after grading ("you picked C; A fails because…") is
    the whole point of the round, and it matches the plain-text-quiz shape
    exactly. Guarding it there discarded the explanation twice and ended the
    turn silent behind a card that only said "correct".
    """

    class _MasteryGradeRegistry(_Registry):
        def build_openai_schemas(self, enabled):
            schemas = super().build_openai_schemas(enabled)
            schemas.append(
                {
                    "type": "function",
                    "function": {
                        "name": "mastery_grade",
                        "description": "Grade the open question",
                        "parameters": {"type": "object", "properties": {}},
                    },
                }
            )
            return schemas

    review = (
        "回答正确!你选择的 C 正是 Agentic RAG 的核心做法。\n\n"
        "其他选项为什么不对:\n"
        "- A. 直接返回“没找到”就结束,等于放弃了自愈能力。\n"
        "- B. 无脑降低相似度阈值,会把噪声一起召回。\n"
        "- D. goto 与 Agentic 架构无关,是干扰项。"
    )
    registry = _MasteryGradeRegistry()
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(
                    tool_calls=[{"id": "grade-1", "name": "mastery_grade", "arguments": "{}"}]
                )
            ],
            [_llm_chunk(content=review)],
        ]
    )
    pipeline = AgenticChatPipeline(language="zh")
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["mastery_grade"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(
        pipeline,
        UnifiedContext(
            session_id="s1",
            user_message="C",
            enabled_tools=["mastery_grade"],
            metadata={"mastery_mode": True, "mastery_path_id": ""},
        ),
    )

    assert client.call_count == 2
    assert review in "".join(_contents(events))
    assert _result(events).metadata["completed"] is True


@pytest.mark.asyncio
async def test_choice_prose_does_not_trigger_repeated_model_calls(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A choice-shaped reply must not be sent through an automatic retry."""
    plain_quiz = "Which value is correct?\n\nA. one\nB. two\nC. three\nD. four"
    client = _ScriptedChatClient(
        [[_llm_chunk(content=plain_quiz)], [_llm_chunk(content=plain_quiz)]]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["ask_user"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(
        pipeline,
        UnifiedContext(
            session_id="s1",
            user_message="Continue",
            enabled_tools=["ask_user"],
            metadata={"mastery_mode": True, "mastery_path_id": ""},
        ),
    )

    assert client.call_count == 1
    assert _answer_text(events) == plain_quiz
    assert not any(event.metadata.get("answer_visible") is False for event in events)
    assert _result(events).metadata["completed"] is True


@pytest.mark.asyncio
@pytest.mark.parametrize(
    "repair",
    [
        "new",
        "existing",
        "tool_failure",
        "repeat",
        "selected_retry",
        "selected_failure",
        "selected_budget",
    ],
)
async def test_mastery_card_promise_repair_uses_real_question_tool(
    repair: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    """Only a selected tool operation needs repair; prose remains visible."""
    monkeypatch.setenv("DEEPTUTOR_WORKSPACE_ROOT", str(tmp_path))

    def init_store(self: LearningStore, root: Path | None = None) -> None:
        self._root = tmp_path / "learning"
        self._root.mkdir(parents=True, exist_ok=True)

    monkeypatch.setattr(LearningStore, "__init__", init_store)
    LearningStore().save(
        LearningProgress(
            book_id="p1",
            modules=[
                LearningModule(
                    id="m1",
                    name="Sorting",
                    order=0,
                    knowledge_points=[
                        KnowledgePoint(
                            id="kp1", name="Bubble sort", type="procedure", module_id="m1"
                        )
                    ],
                )
            ],
        )
    )
    quiz_args = {
        "knowledge_point_id": "kp1",
        "question": "After one left-to-right ascending bubble-sort pass on [3, 1, 2]?",
        "expected_answer": "A",
        "options": [{"label": "A", "body": "1, 2, 3"}, {"label": "B", "body": "1, 3, 2"}],
        "explanation": "The largest value 3 moves to the end in this pass.",
    }
    old_id = None
    if repair == "existing":
        old = await MasteryQuizTool().execute(
            **quiz_args, _mastery_path_id="p1", _session_id="s1", _turn_id="previous"
        )
        assert old.success
        old_id = old.metadata["mastery_question"]["question_id"]

    class RealQuizRegistry(_Registry):
        def get(self, name: str):
            return MasteryQuizTool() if name == "mastery_quiz" else None

        def build_openai_schemas(self, _enabled: list[str]) -> list[dict[str, Any]]:
            return [MasteryQuizTool().get_definition().to_openai_schema()]

        async def execute(self, name: str, **kwargs: Any) -> ToolResult:
            self.executed.append({"name": name, "kwargs": kwargs})
            assert name == "mastery_quiz"
            return await MasteryQuizTool().execute(**kwargs)

    promise = "卡片这次重开一遍,题面我直接写在题干里了。"
    script = [[_llm_chunk(content=promise, finish_reason="stop")]]
    if repair == "repeat":
        script.append([_llm_chunk(content=promise, finish_reason="stop")])
    else:
        script.append(
            [
                _llm_chunk(
                    tool_calls=[
                        {
                            "id": "quiz-1",
                            "name": "mastery_quiz",
                            "arguments": json.dumps({} if repair == "tool_failure" else quiz_args),
                        }
                    ],
                    finish_reason="tool_calls",
                )
            ]
        )
        if repair == "tool_failure":
            script.append([_llm_chunk(content=promise, finish_reason="stop")])
    selected_quiz = repair.startswith("selected_")
    if selected_quiz:
        # No delivery keywords: a failed native tool call alone establishes
        # the obligation, and unrelated final prose must not erase it.
        promise = "Done."
        script = [
            [
                _llm_chunk(
                    tool_calls=[{"id": "bad-quiz", "name": "mastery_quiz", "arguments": "{}"}],
                    finish_reason="tool_calls",
                )
            ],
            [_llm_chunk(content=promise, finish_reason="stop")],
            [
                _llm_chunk(
                    tool_calls=[
                        {
                            "id": "retry-quiz",
                            "name": "mastery_quiz",
                            "arguments": json.dumps(quiz_args),
                        }
                    ],
                    finish_reason="tool_calls",
                )
            ]
            if repair == "selected_retry"
            else [_llm_chunk(content=promise, finish_reason="stop")],
        ]
    if repair == "selected_budget":
        script = [
            [
                _llm_chunk(
                    tool_calls=[{"id": f"bad-{index}", "name": "mastery_quiz", "arguments": "{}"}],
                    finish_reason="tool_calls",
                )
            ]
            for index in range(4)
        ] + [[_llm_chunk(content="Done.", finish_reason="stop")]]
    client = _ScriptedChatClient(script)
    registry = RealQuizRegistry()
    pipeline = MasteryLoopPipeline(language="zh")
    if repair == "selected_budget":
        pipeline._max_rounds = 1
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["mastery_quiz"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)
    context = UnifiedContext(
        session_id="s1",
        user_message="没有卡片",
        enabled_tools=["mastery_quiz"],
        metadata={
            "mastery_mode": True,
            "mastery_path_id": "p1",
            "mastery_session_mode": "study",
            "turn_id": "repair-turn",
        },
    )
    events = await _run(pipeline, context)
    cards = [
        e.metadata["tool_metadata"]["mastery_question"]
        for e in events
        if e.type == StreamEventType.TOOL_RESULT
        and "mastery_question" in e.metadata.get("tool_metadata", {})
    ]
    if not selected_quiz:
        assert client.call_count == 1
        assert promise == _answer_text(events)
        assert not cards
        assert _result(events).metadata["completed"] is True
        pending = LearningStore().load("p1").pending_question
        assert (pending.question_id if pending else None) == old_id
        return
    if repair != "selected_budget":
        assert promise in _answer_text(events)
    if repair == "selected_budget":
        # One exploration round plus three settlement rounds; no tool-less
        # salvage call can discharge an unfulfilled quiz obligation.
        assert client.call_count == 4
        assert all("tools" in call for call in client.calls)
    else:
        correction = client.calls[2 if selected_quiz else 1]
        assert "mastery_quiz" in correction["messages"][-1]["content"]
        assert any(s["function"]["name"] == "mastery_quiz" for s in correction["tools"])
        assert client.call_count == (3 if repair == "tool_failure" or selected_quiz else 2)
    succeeded = repair in {"new", "existing", "selected_retry"}
    assert _result(events).metadata["completed"] is succeeded
    if succeeded:
        assert len(cards) == 1
        persisted = LearningStore().load("p1").pending_question
        assert persisted is not None
        assert cards[0]["question_id"] == persisted.question_id
        assert cards[0]["prompt"] == quiz_args["question"]
        if old_id:
            assert cards[0]["question_id"] == old_id
    else:
        assert cards == []
        assert LearningStore().load("p1").pending_question is None
        if repair != "selected_budget":
            assert promise in _result(events).metadata["response"]


@pytest.mark.asyncio
@pytest.mark.parametrize("recovery", ["success", "unsupported", "rogue", "failed_prepare", "stale"])
async def test_mastery_preparation_at_settlement_boundary_gets_one_delivery_round(
    recovery: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    """A successful source repair gets one restricted chance to deliver its card."""
    from deeptutor.capabilities.mastery.tools import MasteryPrepareLessonTool
    from deeptutor.learning import semantic_assessment

    monkeypatch.setenv("DEEPTUTOR_WORKSPACE_ROOT", str(tmp_path))

    def init_store(self, root=None):
        self._root = tmp_path / "learning"
        self._root.mkdir(parents=True, exist_ok=True)

    monkeypatch.setattr(LearningStore, "__init__", init_store)
    LearningStore().save(
        LearningProgress(
            book_id="p1",
            modules=[
                LearningModule(
                    id="m1",
                    name="Synthetic",
                    order=0,
                    knowledge_points=[
                        KnowledgePoint(
                            id="kp1", name="Synthetic objective", type="memory", module_id="m1"
                        )
                    ],
                )
            ],
        )
    )
    prepared = False

    async def verify(_store, _progress, _questions, config=None):
        if not prepared or recovery == "unsupported":
            raise semantic_assessment.AssessmentUnavailable(
                "Synthetic unsupported source contract."
            )

    monkeypatch.setattr(semantic_assessment, "bind_questions", verify)
    quiz_args = {
        "questions": [
            {"knowledge_point_id": "kp1", "question": "Synthetic first?", "expected_answer": "one"},
            {
                "knowledge_point_id": "kp1",
                "question": "Synthetic second?",
                "expected_answer": "two",
            },
        ]
    }

    class Registry(_Registry):
        def build_openai_schemas(self, _enabled):
            return [
                tool.get_definition().to_openai_schema()
                for tool in (MasteryQuizTool(), MasteryPrepareLessonTool())
            ]

        async def execute(self, name, **kwargs):
            nonlocal prepared
            self.executed.append({"name": name, "kwargs": kwargs})
            if name == "mastery_quiz":
                return await MasteryQuizTool().execute(**kwargs)
            assert name == "mastery_prepare_lesson"
            if recovery == "failed_prepare":
                return ToolResult(content="Synthetic preparation unavailable.", success=False)
            prepared = True
            kwargs["_bind_lesson_objective"]("kp1")
            if recovery == "stale":
                progress = LearningStore().load("p1")
                LearningStore().save(progress)
            return ToolResult(content="Synthetic source preparation succeeded.", success=True)

    def tool(name, args, call_id):
        return [
            _llm_chunk(
                tool_calls=[{"id": call_id, "name": name, "arguments": json.dumps(args)}],
                finish_reason="tool_calls",
            )
        ]

    script = [
        tool("mastery_quiz", quiz_args, "quiz-1"),
        tool("mastery_quiz", quiz_args, "quiz-2"),
        [_llm_chunk(content="Done.", finish_reason="stop")],
        tool("mastery_prepare_lesson", {"knowledge_point_id": "kp1"}, "repair"),
    ]
    if recovery not in {"failed_prepare", "stale"}:
        script.append(
            tool("mastery_prepare_lesson", {"knowledge_point_id": "kp1"}, "rogue")
            if recovery == "rogue"
            else tool("mastery_quiz", quiz_args, "delivery")
        )
    client, registry = _ScriptedChatClient(script), Registry()
    pipeline = MasteryLoopPipeline(language="en")
    pipeline._max_rounds = 1
    pipeline.registry = registry
    monkeypatch.setattr(
        pipeline, "_compose_enabled_tools", lambda _ctx: ["mastery_quiz", "mastery_prepare_lesson"]
    )
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)
    context = UnifiedContext(
        session_id="s1",
        user_message="Give me two practice questions.",
        allowed_builtin_tools=["mastery_quiz", "mastery_prepare_lesson"],
        metadata={
            "mastery_mode": True,
            "mastery_path_id": "p1",
            "mastery_session_mode": "study",
            "turn_id": "repair-turn",
        },
    )
    events = await _run(pipeline, context)
    assert client.call_count == (4 if recovery in {"failed_prepare", "stale"} else 5)
    if client.call_count == 5:
        assert [schema["function"]["name"] for schema in client.calls[-1]["tools"]] == [
            "mastery_quiz"
        ]
    assert [row["name"] for row in registry.executed].count("mastery_prepare_lesson") == 1
    assert _result(events).metadata["completed"] is (recovery == "success")
    pending = LearningStore().load("p1").pending_question
    if recovery == "success":
        assert pending is not None and len(pending.questions) == 2
        cards = [
            event
            for event in events
            if event.type == StreamEventType.TOOL_RESULT
            and "mastery_question" in event.metadata.get("tool_metadata", {})
        ]
        assert len(cards) == 1
    else:
        assert pending is None


@pytest.mark.asyncio
async def test_truncated_pure_reasoning_round_is_told_to_act_not_continue(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A round that reasoned itself out of budget has nothing to continue from.

    "Continue from where it ended" assumes visible output to resume. A reasoning
    model that spends its whole budget revising a plan it had already settled
    produces none, so that instruction sends it back into the same loop: rounds
    burn, nothing reaches the reader, and the turn looks stuck.
    """
    client = _ScriptedChatClient(
        [
            [_llm_chunk(content="<think>让我再想一遍这道题</think>", finish_reason="length")],
            [_llm_chunk(content="答案是 42。")],
        ]
    )
    pipeline = AgenticChatPipeline(language="zh")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(pipeline, UnifiedContext(session_id="s1", user_message="出题"))

    assert client.call_count == 2
    instruction = str(client.calls[1]["messages"][-1]["content"])
    assert "没有「中断处」可以续" in instruction
    assert "从中断处继续" not in instruction
    assert _answer_text(events) == "答案是 42。"


@pytest.mark.asyncio
async def test_truncated_reasoning_round_replays_state_and_keeps_tools(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """The one reasoning-budget recovery keeps provider state and tools."""
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(
                    reasoning_content="I have enough context to act.",
                    finish_reason="length",
                )
            ],
            [_llm_chunk(content="Implemented the requested change.")],
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(
        pipeline,
        UnifiedContext(session_id="s1", user_message="Implement it", enabled_tools=["web_search"]),
    )

    assert client.call_count == 2
    second_round = client.calls[1]["messages"]
    assert "tools" in client.calls[1]
    assert any(
        message.get("role") == "assistant"
        and message.get("reasoning_content") == "I have enough context to act."
        for message in second_round
    )
    assert "Act now" in str(second_round[-1]["content"])
    first_complete = next(
        event
        for event in events
        if event.type == StreamEventType.PROGRESS
        and event.metadata.get("trace_kind") == "call_status"
        and event.metadata.get("call_state") == "complete"
        and event.metadata.get("finish_reason") == "length"
    )
    # The budget the round asked for, not a literal: `chat.responding.max_tokens`
    # is an agents.yaml knob, so pinning the shipped default here made the test
    # read whatever budget the developer running it happens to have configured.
    assert first_complete.metadata["requested_max_tokens"] == pipeline.loop_max_tokens
    assert first_complete.metadata["usage_reported"] is False
    assert first_complete.metadata["completion_tokens"] == "unavailable"
    assert first_complete.metadata["reasoning_chars"] > 0
    assert first_complete.metadata["content_chars"] == 0
    assert first_complete.metadata["tool_call_count"] == 0
    assert _answer_text(events) == "Implemented the requested change."


@pytest.mark.asyncio
async def test_repeated_reasoning_budget_exhaustion_is_retryable_error(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A second pure-reasoning truncation stops after the single recovery."""
    client = _ScriptedChatClient(
        [
            [_llm_chunk(reasoning_content="first pass", finish_reason="length")],
            [_llm_chunk(reasoning_content="second pass", finish_reason="length")],
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    with pytest.raises(LLMReasoningBudgetExhausted) as raised:
        await pipeline.run(
            UnifiedContext(
                session_id="s1", user_message="Implement it", enabled_tools=["web_search"]
            ),
            StreamBus(),
        )

    assert client.call_count == 2
    assert raised.value.error_code == "reasoning_budget_exhausted"
    assert raised.value.retryable is True
    assert "useful response" not in str(raised.value).lower()


@pytest.mark.asyncio
async def test_reasoning_progress_is_throttled_and_contains_no_reasoning_text(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """Reasoning-only streams emit opaque 15-second progress markers."""
    clock = iter([0.0, 16.0, 20.0, 31.0, 40.0])
    monkeypatch.setattr(agent_loop_mod, "monotonic", lambda: next(clock, 40.0))
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(reasoning_content="private one"),
                _llm_chunk(reasoning_content="private two"),
                _llm_chunk(reasoning_content="private three"),
            ],
            [_llm_chunk(content="Now acting.")],
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(pipeline, UnifiedContext(session_id="s1", user_message="Do it"))

    progress = [
        event
        for event in events
        if event.type == StreamEventType.PROGRESS
        and event.metadata.get("trace_kind") == "reasoning_progress"
    ]
    assert len(progress) == 2
    assert [event.metadata["reasoning_chars"] for event in progress] == [11, 35]
    assert [event.metadata["elapsed_s"] for event in progress] == [16.0, 31.0]
    assert all(event.metadata.get("call_id") for event in progress)
    assert all("private" not in event.content for event in progress)
    assert _answer_text(events) == "Now acting."


@pytest.mark.asyncio
async def test_reasoning_progress_stops_after_visible_action(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    clock = iter([0.0, 16.0, 20.0, 31.0])
    monkeypatch.setattr(agent_loop_mod, "monotonic", lambda: next(clock, 31.0))
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(reasoning_content="private"),
                _llm_chunk(content="Started acting."),
                _llm_chunk(reasoning_content="late private"),
            ]
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(pipeline, UnifiedContext(session_id="s1", user_message="Do it"))

    progress = [
        event
        for event in events
        if event.type == StreamEventType.PROGRESS
        and event.metadata.get("trace_kind") == "reasoning_progress"
    ]
    assert len(progress) == 1
    assert _answer_text(events) == "Started acting."


@pytest.mark.asyncio
async def test_forced_finish_reasoning_budget_exhaustion_is_not_empty_success(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """The tool-less hard finish has the same dedicated failure boundary."""
    registry = _Registry()
    tool_rounds = [
        [
            _llm_chunk(
                tool_calls=[
                    {
                        "id": f"call-{index}",
                        "name": "web_search",
                        "arguments": json.dumps({"query": f"step {index}"}),
                    }
                ]
            )
        ]
        for index in range(4)
    ]
    client = _ScriptedChatClient(
        [
            *tool_rounds,
            [_llm_chunk(reasoning_content="still thinking", finish_reason="length")],
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    pipeline._max_rounds = 1
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    with pytest.raises(LLMReasoningBudgetExhausted) as raised:
        await pipeline.run(
            UnifiedContext(session_id="s1", user_message="Research", enabled_tools=["web_search"]),
            StreamBus(),
        )

    assert client.call_count == 5
    assert raised.value.error_code == "reasoning_budget_exhausted"
    assert raised.value.retryable is True


@pytest.mark.asyncio
async def test_truncated_round_with_visible_text_still_continues(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A partially written answer is resumed, as before."""
    client = _ScriptedChatClient(
        [
            [_llm_chunk(content="答案的前半段", finish_reason="length")],
            [_llm_chunk(content="和后半段。")],
        ]
    )
    pipeline = AgenticChatPipeline(language="zh")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(pipeline, UnifiedContext(session_id="s1", user_message="讲一下"))

    instruction = str(client.calls[1]["messages"][-1]["content"])
    assert "从中断处继续" in instruction
    assert _answer_text(events) == "答案的前半段和后半段。"


@pytest.mark.asyncio
async def test_forced_tool_round_keeps_inline_reasoning_in_the_trace(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """Forced tool rounds preserve prose while routing reasoning to the trace."""
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(content="<think>先想清楚要问什么</think>先确认你的目标。"),
                _llm_chunk(
                    tool_calls=[
                        {
                            "id": "ask-1",
                            "name": "ask_user",
                            "arguments": json.dumps({"questions": [{"id": "q1", "prompt": "?"}]}),
                        }
                    ]
                ),
            ]
        ]
    )
    pipeline = AgenticChatPipeline(language="zh")
    pipeline.registry = _Registry()
    pipeline.initial_tool_choice = "ask_user"
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["ask_user"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(
        pipeline,
        UnifiedContext(session_id="s1", user_message="帮我问", enabled_tools=["ask_user"]),
    )

    thinking = "".join(e.content for e in events if e.type == StreamEventType.THINKING)
    assert "先想清楚要问什么" in thinking
    # The reasoning is trace-only: it must not become the answer.
    assert "先想清楚要问什么" not in _answer_text(events)
    assert "先确认你的目标。" in _answer_text(events)


@pytest.mark.asyncio
async def test_inline_think_is_never_answer_content(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """An ordinary round splits inline reasoning off the reply."""
    client = _ScriptedChatClient([[_llm_chunk(content="<think>推导过程</think>结论是 A。")]])
    pipeline = AgenticChatPipeline(language="zh")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(pipeline, UnifiedContext(session_id="s1", user_message="算"))

    thinking = "".join(e.content for e in events if e.type == StreamEventType.THINKING)
    assert thinking == "推导过程"
    assert _answer_text(events) == "结论是 A。"


@pytest.mark.asyncio
async def test_partner_wording_request_keeps_its_answer(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A Partner keyword in another task cannot redirect or discard a turn."""
    client = _ScriptedChatClient([[_llm_chunk(content="Use a warmer tone.")]])
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(
        pipeline,
        UnifiedContext(
            session_id="s1",
            user_message="Please add a companion-style tone to my summary",
        ),
    )

    assert _answer_text(events) == "Use a warmer tone."


@pytest.mark.asyncio
async def test_mastery_teaching_prose_streams_chunk_by_chunk(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A guarded surface still streams; it does not withhold the whole round.

    Buffering used to be switched on by the mere presence of a capability
    ``finish_instruction``, which is how mastery — whose guard fires only on an
    uncommon turn shape — lost streaming altogether: every round was withheld
    until it closed, so the learner watched a spinner and then received the
    answer in one piece. Buffering is now declared per capability, and mastery
    does not declare it.
    """
    pieces = ["先", "看", "这", "一", "步", ":", "分", "母", "不", "能", "为", "零"]
    client = _ScriptedChatClient([[_llm_chunk(content=piece) for piece in pieces]])
    pipeline = AgenticChatPipeline(language="zh")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(
        pipeline,
        UnifiedContext(
            session_id="s1",
            user_message="讲一下",
            metadata={"mastery_mode": True, "mastery_path_id": ""},
        ),
    )

    assert _contents(events) == pieces
    assert _answer_text(events) == "".join(pieces)


@pytest.mark.asyncio
async def test_protocol_capabilities_still_withhold_their_rounds(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A capability that declares buffering keeps it.

    Visualization's deliverable is the committed payload and its prose is
    discarded, so streaming that prose would show the reader scaffolding that
    is about to be thrown away.
    """
    pieces = ["draw", "ing ", "it"]
    client = _ScriptedChatClient([[_llm_chunk(content=piece) for piece in pieces]])
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)
    monkeypatch.setattr(pipeline, "_capability_buffers_visible_output", lambda _context: True)

    events = await _run(pipeline, UnifiedContext(session_id="s1", user_message="Draw it"))

    assert _contents(events) == ["".join(pieces)]


@pytest.mark.asyncio
async def test_non_streaming_endpoint_is_served_through_one_chunk(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A provider declared non-streaming answers instead of failing the turn.

    ``supports_streaming`` was declared for every binding and read by nobody:
    the loop asked for SSE regardless, so an endpoint without it lost the turn.
    """
    requested: list[Any] = []

    class _NonStreamingClient:
        def __init__(self) -> None:
            parent = self

            class _Completions:
                async def create(self, **kwargs):
                    requested.append(kwargs.get("stream"))
                    if kwargs.get("stream"):
                        raise AssertionError("this endpoint cannot stream")
                    return SimpleNamespace(
                        choices=[
                            SimpleNamespace(
                                message=SimpleNamespace(
                                    content="one whole answer",
                                    tool_calls=None,
                                ),
                                finish_reason="stop",
                            )
                        ],
                        usage=None,
                    )

            self.chat = SimpleNamespace(completions=_Completions())
            _ = parent

    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", _NonStreamingClient)
    monkeypatch.setattr(agent_loop_mod, "supports_streaming", lambda _binding, _model: False)

    events = await _run(pipeline, UnifiedContext(session_id="s1", user_message="Answer"))

    assert requested == [False]
    assert _answer_text(events) == "one whole answer"
    assert _result(events).metadata["response"] == "one whole answer"


@pytest.mark.asyncio
async def test_mastery_labelled_teaching_examples_stay_direct(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A labelled teaching list is not itself an assessment prompt."""
    registry = _Registry()
    teaching = (
        "Here are container spellings to remember:\n\n"
        "- A. lists use brackets.\n"
        "- B. dictionaries answer key lookups with braces and a colon.\n"
        "- C. sets use braces without a colon."
    )
    client = _ScriptedChatClient([[_llm_chunk(content=teaching)]])
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(
        pipeline,
        UnifiedContext(
            session_id="s1",
            user_message="Teach me Python containers",
            metadata={"mastery_mode": True, "mastery_path_id": ""},
        ),
    )

    assert client.call_count == 1
    assert "".join(_contents(events)) == teaching
    assert _result(events).metadata["completed"] is True


@pytest.mark.asyncio
async def test_dsml_round_keeps_clean_prose_visible_and_decodes_container_args(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A DSML call may share a content stream with tutor feedback.

    Only the call markup is hidden; prose on both sides stays in ``content``.
    The completion marker narrowly opts that cleaned prose out of the normal
    narration demotion, and schema-declared arrays reach the tool as arrays.
    """

    class _PausingRegistry(_Registry):
        async def execute(self, name: str, **kwargs):
            self.executed.append({"name": name, "kwargs": kwargs})
            return ToolResult(
                content="Asked the user.",
                success=True,
                pause_for_user={"questions": kwargs["questions"]},
            )

    registry = _PausingRegistry()
    dsml = (
        "Feedback before. "
        '<||DSML||tool_calls><||DSML||invoke name="ask_user">'
        '<||DSML||parameter name="questions" string="true">'
        '[{"id":"q1","prompt":"Continue?"}]'
        "</||DSML||parameter></||DSML||invoke>"
        "</||DSML||tool_calls> Feedback after."
    )
    # Split inside special tokens, tag names, and the JSON parameter value.
    dsml_chunks = [dsml[index : index + 5] for index in range(0, len(dsml), 5)]
    client = _ScriptedChatClient([[_llm_chunk(content=piece) for piece in dsml_chunks]])
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["ask_user"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(
        pipeline,
        UnifiedContext(session_id="s1", user_message="Teach me", enabled_tools=["ask_user"]),
    )

    assert registry.executed[0]["name"] == "ask_user"
    assert registry.executed[0]["kwargs"]["questions"] == [{"id": "q1", "prompt": "Continue?"}]
    round_content = "".join(
        event.content
        for event in events
        if event.type == StreamEventType.CONTENT
        and event.metadata.get("call_kind") == "agent_loop_round"
    )
    assert round_content == "Feedback before.  Feedback after."
    assert "DSML" not in round_content
    thinking = "".join(event.content for event in events if event.type == StreamEventType.THINKING)
    assert "DSML" not in thinking

    markers = [
        event.metadata
        for event in events
        if event.type == StreamEventType.PROGRESS
        and event.metadata.get("call_state") == "complete"
        and "call_role" in event.metadata
    ]
    assert markers[0]["call_role"] == "narration"
    assert markers[0]["answer_visible"] is True
    result = _result(events)
    assert client.call_count == 1
    assert result.metadata["completed"] is False
    assert result.metadata["response"] == ""


@pytest.mark.asyncio
async def test_dsml_container_schema_survives_native_tool_fallback(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    class _FallbackClient:
        def __init__(self, scripted: list[list[SimpleNamespace]]) -> None:
            self.scripted = list(scripted)
            self.calls: list[dict[str, Any]] = []

            class _Completions:
                def __init__(self, parent: _FallbackClient) -> None:
                    self.parent = parent

                async def create(self, **kwargs):
                    self.parent.calls.append(kwargs)
                    if kwargs.get("tools"):
                        raise RuntimeError("tool_choice is invalid")
                    return _async_llm_stream(self.parent.scripted.pop(0))

            self.chat = SimpleNamespace(completions=_Completions(self))

    class _PausingRegistry(_Registry):
        async def execute(self, name: str, **kwargs):
            self.executed.append({"name": name, "kwargs": kwargs})
            if name == "ask_user":
                return ToolResult(
                    content="Asked the user.",
                    success=True,
                    pause_for_user={"questions": kwargs["questions"]},
                )
            return ToolResult(content="search result", success=True)

    first = (
        '<|DSML|invoke name="web_search">'
        '<|DSML|parameter name="query" string="true">topic'
        "</|DSML|parameter></|DSML|invoke>"
    )
    second = (
        '<|DSML|invoke name="ask_user">'
        '<|DSML|parameter name="questions" string="true">'
        '[{"id":"q1","prompt":"Continue?"}]'
        "</|DSML|parameter></|DSML|invoke>"
    )
    client = _FallbackClient([[_llm_chunk(content=first)], [_llm_chunk(content=second)]])
    registry = _PausingRegistry()
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    monkeypatch.setattr(
        pipeline, "_compose_enabled_tools", lambda _context: ["web_search", "ask_user"]
    )
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    await _run(
        pipeline,
        UnifiedContext(
            session_id="s1",
            user_message="Teach me",
            enabled_tools=["web_search", "ask_user"],
        ),
    )

    assert [item["name"] for item in registry.executed] == ["web_search", "ask_user"]
    assert registry.executed[-1]["kwargs"]["questions"] == [{"id": "q1", "prompt": "Continue?"}]
    assert "tools" in client.calls[0]
    assert all("tools" not in call for call in client.calls[1:])


@pytest.mark.asyncio
async def test_midloop_transport_failure_retries_current_round(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A transport failure before the next round emits output retries that
    round without discarding the useful tool work already in context."""

    class _FailingThenFinishClient:
        def __init__(self) -> None:
            self.call_count = 0
            self.calls: list[dict[str, Any]] = []
            parent = self

            class _Completions:
                async def create(self, **kwargs):
                    parent.call_count += 1
                    parent.calls.append({**kwargs, "messages": list(kwargs.get("messages") or [])})
                    if parent.call_count == 1:
                        return _async_llm_stream(
                            [
                                _llm_chunk(content="Searching."),
                                _llm_chunk(
                                    tool_calls=[
                                        {
                                            "id": "call-1",
                                            "name": "web_search",
                                            "arguments": json.dumps({"query": "q"}),
                                        }
                                    ]
                                ),
                            ]
                        )
                    if parent.call_count == 2:
                        raise TimeoutError("Request timed out.")
                    return _async_llm_stream([_llm_chunk(content="Best-effort answer.")])

            class _Chat:
                def __init__(self) -> None:
                    self.completions = _Completions()

            self.chat = _Chat()

    registry = _Registry()
    client = _FailingThenFinishClient()
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(
        pipeline,
        UnifiedContext(session_id="s1", user_message="Look up", enabled_tools=["web_search"]),
    )

    # 1 tool round + 1 failed attempt + 1 retry = 3 create() calls.
    assert client.call_count == 3
    # The turn produced an answer instead of failing.
    result = _result(events)
    assert result.metadata["response"] == "Best-effort answer."
    # The retry is explicit in the trace, and no forced-finish path was needed.
    progress = [
        e.content
        for e in events
        if e.type == StreamEventType.PROGRESS
        and e.metadata.get("error_code") == "provider_transport"
    ]
    assert progress == ["The model provider connection was interrupted; retrying."]


@pytest.mark.asyncio
@pytest.mark.parametrize("phase", ["connect", "stream", "partial_stream"])
async def test_cold_start_stalled_provider_settles_with_bounded_retries(monkeypatch, phase):
    """#1421: a provider that never raises its own timeout cannot hold discovery forever."""
    attempts = []
    stopped = []

    async def stalled_stream():
        try:
            if phase == "partial_stream":
                yield _llm_chunk(content="Partial answer.")
            await asyncio.Event().wait()
            yield _llm_chunk(content="unreachable")
        finally:
            stopped.append(True)

    async def create(**_kwargs):
        attempts.append(True)
        if phase == "connect":
            await asyncio.Event().wait()
        return stalled_stream()

    client = SimpleNamespace(chat=SimpleNamespace(completions=SimpleNamespace(create=create)))
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(agent_loop_mod, "_PROVIDER_RETRY_DELAYS", (0, 0))
    monkeypatch.setattr(agent_loop_mod, "_STREAM_IDLE_TIMEOUT_SECONDS", 0.01)
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)
    bus = StreamBus()
    events, consumer = await _collect_bus_events(bus)
    try:
        with pytest.raises(LLMProviderTransportError) as failure:
            await asyncio.wait_for(
                pipeline.run(UnifiedContext(session_id="cold", user_message="Hello"), bus), 1
            )
        assert failure.value.retryable
        assert len(attempts) == (1 if phase == "partial_stream" else 3)
        assert failure.value.partial_response is (phase == "partial_stream")
        if phase != "connect":
            assert len(stopped) == len(attempts)
    finally:
        await bus.close()
        await consumer
    assert sum(event.metadata.get("error_code") == "provider_transport" for event in events) >= 1


@pytest.mark.asyncio
async def test_first_round_transport_failure_retries_then_becomes_structured_error(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """An unavailable provider gets bounded retries and a safe UI error."""

    class _AlwaysFailClient:
        def __init__(self) -> None:
            self.call_count = 0
            parent = self

            class _Completions:
                async def create(self, **kwargs):
                    parent.call_count += 1
                    raise TimeoutError("Request timed out.")

            class _Chat:
                def __init__(self) -> None:
                    self.completions = _Completions()

            self.chat = _Chat()

    client = _AlwaysFailClient()
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(agent_loop_mod, "_PROVIDER_RETRY_DELAYS", (0, 0))
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    bus = StreamBus()
    _events, consumer = await _collect_bus_events(bus)
    with pytest.raises(LLMProviderTransportError) as raised:
        await pipeline.run(
            UnifiedContext(session_id="s1", user_message="x", enabled_tools=["web_search"]),
            bus,
        )
    await bus.close()
    await consumer

    assert client.call_count == 3
    assert raised.value.error_code == "provider_transport"
    assert raised.value.retryable is True
    assert raised.value.partial_response is False
    assert str(raised.value) == "Unable to reach the model provider. Please retry."


@pytest.mark.asyncio
async def test_transport_failure_before_output_recovers_without_duplicate_content(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    class _RecoveringClient:
        def __init__(self) -> None:
            self.call_count = 0
            parent = self

            class _Completions:
                async def create(self, **kwargs):
                    parent.call_count += 1
                    if parent.call_count == 1:
                        raise httpx.ConnectTimeout("provider handshake timed out")
                    return _async_llm_stream([_llm_chunk(content="Recovered.")])

            self.chat = SimpleNamespace(completions=_Completions())

    client = _RecoveringClient()
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(agent_loop_mod, "_PROVIDER_RETRY_DELAYS", (0, 0))
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(pipeline, UnifiedContext(session_id="s1", user_message="Hi"))

    assert client.call_count == 2
    assert _contents(events) == ["Recovered."]
    retry_events = [
        event
        for event in events
        if event.type == StreamEventType.PROGRESS
        and event.metadata.get("error_code") == "provider_transport"
    ]
    assert len(retry_events) == 1
    assert retry_events[0].metadata["retry_attempt"] == 1


@pytest.mark.asyncio
async def test_midstream_transport_failure_is_not_replayed(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    async def _interrupted_stream():
        yield _llm_chunk(content="Partial answer.")
        raise httpx.ReadError("peer closed the SSE stream")

    class _InterruptedClient:
        def __init__(self) -> None:
            self.call_count = 0
            parent = self

            class _Completions:
                async def create(self, **kwargs):
                    parent.call_count += 1
                    return _interrupted_stream()

            self.chat = SimpleNamespace(completions=_Completions())

    client = _InterruptedClient()
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(agent_loop_mod, "_PROVIDER_RETRY_DELAYS", (0, 0))
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    bus = StreamBus()
    events, consumer = await _collect_bus_events(bus)
    context = UnifiedContext(session_id="s1", user_message="Hi")
    with pytest.raises(LLMProviderTransportError) as raised:
        await pipeline.run(context, bus)
    await bus.close()
    await consumer

    assert client.call_count == 1
    assert _contents(events) == ["Partial answer."]
    assert context.runtime.model_turn["messages"][-1] == {
        "role": "assistant",
        "content": "Partial answer.",
    }
    assert raised.value.partial_response is True
    failed_call = next(
        event
        for event in events
        if event.type == StreamEventType.PROGRESS and event.metadata.get("call_state") == "failed"
    )
    assert failed_call.metadata["error_code"] == "provider_transport"
    assert failed_call.metadata["partial_response"] is True


@pytest.mark.asyncio
async def test_later_round_midstream_transport_failure_is_not_forced_finished(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """Visible output after a tool round must not be mixed with a replay."""

    async def _interrupted_stream():
        yield _llm_chunk(content="Partial final answer.")
        raise httpx.ReadError("peer closed the SSE stream")

    class _ToolThenInterruptedClient:
        def __init__(self) -> None:
            self.call_count = 0
            parent = self

            class _Completions:
                async def create(self, **kwargs):
                    parent.call_count += 1
                    if parent.call_count == 1:
                        return _async_llm_stream(
                            [
                                _llm_chunk(
                                    tool_calls=[
                                        {
                                            "id": "call-1",
                                            "name": "web_search",
                                            "arguments": json.dumps({"query": "q"}),
                                        }
                                    ]
                                )
                            ]
                        )
                    return _interrupted_stream()

            self.chat = SimpleNamespace(completions=_Completions())

    client = _ToolThenInterruptedClient()
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(agent_loop_mod, "_PROVIDER_RETRY_DELAYS", (0, 0))
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    bus = StreamBus()
    events, consumer = await _collect_bus_events(bus)
    with pytest.raises(LLMProviderTransportError) as raised:
        await pipeline.run(
            UnifiedContext(session_id="s1", user_message="Look up", enabled_tools=["web_search"]),
            bus,
        )
    await bus.close()
    await consumer

    assert client.call_count == 2
    assert _contents(events).count("Partial final answer.") == 1
    assert raised.value.partial_response is True


@pytest.mark.asyncio
async def test_forced_finish_transport_failure_remains_structured(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A failed salvage request must stay retryable instead of completing."""

    class _ToolThenFailingClient:
        def __init__(self) -> None:
            self.call_count = 0
            parent = self

            class _Completions:
                async def create(self, **kwargs):
                    parent.call_count += 1
                    if parent.call_count == 1:
                        return _async_llm_stream(
                            [
                                _llm_chunk(
                                    tool_calls=[
                                        {
                                            "id": "call-1",
                                            "name": "web_search",
                                            "arguments": json.dumps({"query": "q"}),
                                        }
                                    ]
                                )
                            ]
                        )
                    if parent.call_count == 2:
                        raise RuntimeError("mid-loop application failure")
                    raise TimeoutError("provider unavailable during forced finish")

            self.chat = SimpleNamespace(completions=_Completions())

    client = _ToolThenFailingClient()
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(agent_loop_mod, "_PROVIDER_RETRY_DELAYS", (0, 0))
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    bus = StreamBus()
    _events, consumer = await _collect_bus_events(bus)
    with pytest.raises(LLMProviderTransportError) as raised:
        await pipeline.run(
            UnifiedContext(session_id="s1", user_message="Look up", enabled_tools=["web_search"]),
            bus,
        )
    await bus.close()
    await consumer

    # Tool round + failed ordinary round + three bounded finish attempts.
    assert client.call_count == 5
    assert raised.value.error_code == "provider_transport"
    assert raised.value.retryable is True
    assert raised.value.partial_response is False


@pytest.mark.asyncio
async def test_context_checkpoint_folds_completed_tool_rounds(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    class _CheckpointRegistry(_Registry):
        async def execute(self, name: str, **kwargs):
            self.executed.append({"name": name, "kwargs": kwargs})
            query = str(kwargs.get("query") or "")
            return ToolResult(
                content=f"noisy tool result for {query}",
                success=True,
                metadata={"_context_checkpoint": {"summary": f"checkpoint: {query}"}},
            )

    registry = _CheckpointRegistry()
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(content="Searching step one."),
                _llm_chunk(
                    tool_calls=[
                        {
                            "id": "call-1",
                            "name": "web_search",
                            "arguments": json.dumps({"query": "step one"}),
                        }
                    ]
                ),
            ],
            [
                _llm_chunk(content="Searching step two."),
                _llm_chunk(
                    tool_calls=[
                        {
                            "id": "call-2",
                            "name": "web_search",
                            "arguments": json.dumps({"query": "step two"}),
                        }
                    ]
                ),
            ],
            [_llm_chunk(content="Final from checkpoints.")],
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(
        pipeline,
        UnifiedContext(
            session_id="s1",
            user_message="Research this",
            enabled_tools=["web_search"],
        ),
    )

    assert client.call_count == 3
    second_round = client.calls[1]["messages"]
    assert any(
        m.get("role") == "system" and "checkpoint: step one" in str(m.get("content"))
        for m in second_round
    )
    assert not any(m.get("role") == "tool" for m in second_round)
    assert not any("Searching step one." in str(m.get("content")) for m in second_round)
    third_round = client.calls[2]["messages"]
    checkpoint_text = "\n".join(
        str(m.get("content") or "") for m in third_round if m.get("role") == "system"
    )
    assert "checkpoint: step one" in checkpoint_text
    assert "checkpoint: step two" in checkpoint_text
    assert not any(m.get("role") == "tool" for m in third_round)
    assert not any("noisy tool result" in str(m.get("content")) for m in third_round)
    result = _result(events)
    assert result.metadata["response"] == "Final from checkpoints."


@pytest.mark.asyncio
async def test_context_checkpoint_state_replaces_instead_of_stacking(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    class _StatefulCheckpointRegistry(_Registry):
        async def execute(self, name: str, **kwargs):
            query = str(kwargs.get("query") or "")
            return ToolResult(
                content=f"noisy tool result for {query}",
                success=True,
                metadata={
                    "_context_checkpoint": {
                        "summary": f"checkpoint: {query}",
                        "state": f"state after {query}",
                    }
                },
            )

    def _search(call_id: str, query: str) -> SimpleNamespace:
        return _llm_chunk(
            tool_calls=[
                {"id": call_id, "name": "web_search", "arguments": json.dumps({"query": query})}
            ]
        )

    client = _ScriptedChatClient(
        [
            [_search("call-1", "step one")],
            [_search("call-2", "step two")],
            [_llm_chunk(content="Final.")],
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _StatefulCheckpointRegistry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    await _run(
        pipeline,
        UnifiedContext(session_id="s1", user_message="Research this", enabled_tools=["web_search"]),
    )

    second_round = [m.get("content") for m in client.calls[1]["messages"]]
    assert second_round[-2:] == [
        "[Context checkpoint]\ncheckpoint: step one",
        "state after step one",
    ]
    third_round = client.calls[2]["messages"]
    contents = [str(m.get("content") or "") for m in third_round]
    # Summaries accumulate as history; only the latest state is kept, last.
    assert contents[-3:] == [
        "[Context checkpoint]\ncheckpoint: step one",
        "[Context checkpoint]\ncheckpoint: step two",
        "state after step two",
    ]
    assert "state after step one" not in contents
    assert not any(m.get("role") == "tool" for m in third_round)


@pytest.mark.asyncio
async def test_solve_checkpoint_fold_keeps_remaining_plan(monkeypatch: pytest.MonkeyPatch) -> None:
    from deeptutor.capabilities.solve.tools import SolveFinishStepTool, SolvePlanTool

    tools = {"solve_plan": SolvePlanTool(), "solve_finish_step": SolveFinishStepTool()}

    class _SolveRegistry(_Registry):
        def build_openai_schemas(self, _enabled):
            return [tool.get_definition().to_openai_schema() for tool in tools.values()]

        async def execute(self, name: str, **kwargs):
            return await tools[name].execute(**kwargs)

    def _call(call_id: str, name: str, args: dict[str, Any]) -> SimpleNamespace:
        return _llm_chunk(tool_calls=[{"id": call_id, "name": name, "arguments": json.dumps(args)}])

    goals = ["Factor x^2-5x+6", "Find both roots", "Verify by substitution"]
    client = _ScriptedChatClient(
        [
            [
                _call(
                    "c1",
                    "solve_plan",
                    {"analysis": "factor", "steps": [{"goal": g} for g in goals]},
                )
            ],
            [_call("c2", "solve_finish_step", {"step_id": "S1", "summary": "(x-2)(x-3)"})],
            [_llm_chunk(content="x = 2 or x = 3")],
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _SolveRegistry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: list(tools))
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)
    context = UnifiedContext(
        session_id="s1",
        user_message="Solve x^2 - 5x + 6 = 0",
        metadata={"solve_mode": True, "solve_session_id": "fold-keeps-plan"},
    )

    await _run(pipeline, context)

    # The step's tool chatter is folded away; the remaining plan must stay in view.
    after_fold = client.calls[2]["messages"]
    assert not any(m.get("role") == "tool" for m in after_fold)
    assert after_fold[-2]["content"].startswith("[Context checkpoint]\n[S1] Factor x^2-5x+6")
    plan = after_fold[-1]["content"]
    assert "- S1 [done] Factor x^2-5x+6" in plan
    assert "- S2 [next] Find both roots" in plan
    assert "- S3 [todo] Verify by substitution" in plan
    # A follow-up turn replays the persisted model turn, so it carries the plan too.
    model_turn = json.dumps(context.runtime.model_turn, ensure_ascii=False)
    assert "Find both roots" in model_turn and "Verify by substitution" in model_turn


@pytest.mark.asyncio
async def test_ask_user_available_every_round(monkeypatch: pytest.MonkeyPatch) -> None:
    """The single loop offers the full tool belt — including ask_user — on
    every round; there is no respond stage that narrows tools to ask_user."""
    registry = _Registry()
    client = _ScriptedChatClient([[_llm_chunk(content="Final answer.")]])
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    monkeypatch.setattr(
        pipeline, "_compose_enabled_tools", lambda _context: ["web_search", "ask_user"]
    )
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    await _run(
        pipeline,
        UnifiedContext(
            session_id="s1",
            user_message="Quick question",
            enabled_tools=["web_search", "ask_user"],
        ),
    )

    loop_tools = {t["function"]["name"] for t in client.calls[0]["tools"]}
    assert loop_tools == {"web_search", "ask_user"}


@pytest.mark.asyncio
async def test_initial_tool_choice_preserves_preamble_and_only_forces_first_round(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    class _PausingRegistry(_Registry):
        async def execute(self, name: str, **kwargs):
            self.executed.append({"name": name, "kwargs": kwargs})
            return ToolResult(
                content="Asked the user.",
                success=True,
                pause_for_user={"questions": [{"id": "q1", "prompt": "What matters most?"}]},
            )

    registry = _PausingRegistry()
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(content="Let me ask one thing first."),
                _llm_chunk(
                    tool_calls=[
                        {
                            "id": "call-1",
                            "name": "ask_user",
                            "arguments": json.dumps(
                                {"questions": [{"id": "q1", "prompt": "What matters most?"}]}
                            ),
                        }
                    ]
                ),
            ],
            [_llm_chunk(content="Completed with the added context.")],
        ]
    )
    pipeline = AgenticChatPipeline(language="en", initial_tool_choice="ask_user")
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["ask_user"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    async def _waiter():
        return {"text": "Accuracy"}

    events = await _run(
        pipeline,
        UnifiedContext(
            session_id="s1",
            user_message="Help with this task",
            runtime=TurnRuntimeContext(wait_for_user_reply=_waiter),
        ),
    )

    assert client.calls[0]["tool_choice"] == {
        "type": "function",
        "function": {"name": "ask_user"},
    }
    assert client.calls[1]["tool_choice"] == "auto"
    assert _contents(events) == ["Let me ask one thing first.", "Completed with the added context."]


@pytest.mark.asyncio
async def test_ask_questions_uses_a_card_when_provider_rejects_tool_schemas(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    class _PausingRegistry(_Registry):
        async def execute(self, name: str, **kwargs):
            self.executed.append({"name": name, "kwargs": kwargs})
            return ToolResult(
                content="Asked the user.",
                success=True,
                pause_for_user={"questions": kwargs["questions"]},
            )

    class _SchemaRejectingClient:
        def __init__(self) -> None:
            self.calls: list[dict[str, Any]] = []

            class _Completions:
                def __init__(self, parent: _SchemaRejectingClient) -> None:
                    self.parent = parent

                async def create(self, **kwargs):
                    self.parent.calls.append(kwargs)
                    if len(self.parent.calls) == 1:
                        raise ValueError("unsupported parameter: tools")
                    content = (
                        "Which outcome matters most?"
                        if len(self.parent.calls) == 2
                        else "Completed after clarification."
                    )
                    return _async_llm_stream([_llm_chunk(content=content)])

            self.chat = SimpleNamespace(completions=_Completions(self))

    registry = _PausingRegistry()
    client = _SchemaRejectingClient()
    pipeline = AgenticChatPipeline(language="en", initial_tool_choice="ask_user")
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["ask_user"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    async def _waiter():
        return {"text": "Accuracy"}

    events = await _run(
        pipeline,
        UnifiedContext(
            session_id="s1",
            user_message="Help with this task",
            runtime=TurnRuntimeContext(wait_for_user_reply=_waiter),
        ),
    )

    assert "tools" in client.calls[0]
    assert "tools" not in client.calls[1]
    assert [item["name"] for item in registry.executed] == ["ask_user"]
    assert registry.executed[0]["kwargs"]["questions"] == [
        {
            "id": "clarification",
            "prompt": "Which outcome matters most?",
            "allow_free_text": True,
        }
    ]
    assert _contents(events) == ["Which outcome matters most?", "Completed after clarification."]
    assert any(event.metadata.get("tool_schema_fallback") for event in events)


@pytest.mark.asyncio
async def test_ask_user_pause_resumes_and_streams_interleaved(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    class _PausingRegistry(_Registry):
        async def execute(self, name: str, **kwargs):
            self.executed.append({"name": name, "kwargs": kwargs})
            if name == "ask_user":
                return ToolResult(
                    content="Asked the user.",
                    success=True,
                    pause_for_user={"questions": [{"id": "q1", "prompt": "Which topic?"}]},
                )
            return await super().execute(name, **kwargs)

    registry = _PausingRegistry()
    client = _ScriptedChatClient(
        [
            # Round 1: a clarification (narration text + ask_user tool call).
            [
                _llm_chunk(content="Let me check one thing."),
                _llm_chunk(
                    tool_calls=[
                        {
                            "id": "call-1",
                            "name": "ask_user",
                            "arguments": json.dumps(
                                {"questions": [{"id": "q1", "prompt": "Which topic?"}]}
                            ),
                        }
                    ]
                ),
            ],
            # Round 2 finishes after the user's reply resumes the loop.
            [_llm_chunk(content="The answer.")],
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["ask_user"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    async def _waiter():
        return {"text": "Topic A"}

    events = await _run(
        pipeline,
        UnifiedContext(
            session_id="s1",
            user_message="Quick question",
            enabled_tools=["ask_user"],
            runtime=TurnRuntimeContext(wait_for_user_reply=_waiter),
        ),
    )

    assert client.call_count == 2
    assert _contents(events) == ["Let me check one thing.", "The answer."]
    assert _call_roles(events) == ["narration", "finish"]
    # The reply was substituted into the role=tool message in-protocol.
    final_round = client.calls[-1]["messages"]
    tool_msgs = [m for m in final_round if m.get("role") == "tool"]
    assert tool_msgs and "Topic A" in tool_msgs[-1]["content"]
    result = _result(events)
    # The persisted answer is the finish round's text.
    assert result.metadata["response"] == "The answer."
    assert result.metadata["completed"] is True


@pytest.mark.asyncio
async def test_ask_user_resume_end_loop_skips_further_llm(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """Neutral ``metadata['end_loop']`` after resume stops without another LLM round."""

    class _EndLoopOnResume:
        name = "end_loop_probe"
        owned_tools: tuple[str, ...] = ()

        def is_active(self, context: UnifiedContext) -> bool:
            return True

        def system_block(self, context, *, language, prompts):  # noqa: ANN001
            return None

        def augment_kwargs(self, tool_name, kwargs, context):  # noqa: ANN001
            return kwargs

        def pre_loop_seed(self, context: UnifiedContext) -> str:
            return ""

        async def on_user_resume(self, context, ask_user, *, reply_text, answers):  # noqa: ANN001
            _ = ask_user, reply_text, answers
            context.interaction.end_loop = True

    class _PausingRegistry(_Registry):
        async def execute(self, name: str, **kwargs):
            self.executed.append({"name": name, "kwargs": kwargs})
            if name == "ask_user":
                return ToolResult(
                    content="Asked the user.",
                    success=True,
                    pause_for_user={"questions": [{"id": "q1", "prompt": "Which topic?"}]},
                )
            return await super().execute(name, **kwargs)

    registry = _PausingRegistry()
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(content="One question."),
                _llm_chunk(
                    tool_calls=[
                        {
                            "id": "call-1",
                            "name": "ask_user",
                            "arguments": json.dumps(
                                {"questions": [{"id": "q1", "prompt": "Which topic?"}]}
                            ),
                        }
                    ]
                ),
            ],
            # Must not be reached when end_loop is set on resume.
            [_llm_chunk(content="Should not stream.")],
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["ask_user"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)
    monkeypatch.setattr(
        pipeline,
        "_active_loop_capabilities",
        lambda _context: (_EndLoopOnResume(),),
    )

    async def _waiter():
        return {"text": "abort please"}

    events = await _run(
        pipeline,
        UnifiedContext(
            session_id="s-end-loop",
            user_message="Quick question",
            enabled_tools=["ask_user"],
            runtime=TurnRuntimeContext(wait_for_user_reply=_waiter),
        ),
    )

    assert client.call_count == 1
    assert "Should not stream." not in _contents(events)
    result = _result(events)
    assert result.metadata["completed"] is False
    # The user did answer, so the reply must still reach the transcript — only
    # the further LLM rounds are skipped.
    replies = [
        event
        for event in events
        if (event.metadata or {}).get("trace_kind") == "user_reply"
        and (event.metadata or {}).get("reply_preview") == "abort please"
    ]
    assert len(replies) == 1


@pytest.mark.asyncio
async def test_unresolved_ask_user_halts_turn(monkeypatch: pytest.MonkeyPatch) -> None:
    class _PausingRegistry(_Registry):
        async def execute(self, name: str, **kwargs):
            self.executed.append({"name": name, "kwargs": kwargs})
            return ToolResult(
                content="Asked the user.",
                success=True,
                pause_for_user={"questions": [{"id": "q1", "prompt": "Which topic?"}]},
            )

    registry = _PausingRegistry()
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(
                    tool_calls=[
                        {
                            "id": "call-1",
                            "name": "ask_user",
                            "arguments": json.dumps({"questions": []}),
                        }
                    ]
                ),
            ],
            # No further scripted responses: with no wait_for_user_reply waiter
            # the loop must halt here instead of producing another answer.
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["ask_user"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(
        pipeline,
        UnifiedContext(session_id="s1", user_message="Help me study", enabled_tools=["ask_user"]),
    )

    assert client.call_count == 1
    assert _contents(events) == ["Which topic?"]
    result = _result(events)
    assert result.metadata["completed"] is False


@pytest.mark.asyncio
async def test_round_budget_enters_tool_enabled_settlement_then_finishes(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    registry = _Registry()
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(
                    tool_calls=[
                        {
                            "id": "call-1",
                            "name": "web_search",
                            "arguments": json.dumps({"query": "step one"}),
                        }
                    ]
                ),
            ],
            [_llm_chunk(content="Best effort answer.")],
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    pipeline._max_rounds = 1
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(
        pipeline,
        UnifiedContext(session_id="s1", user_message="Research this", enabled_tools=["web_search"]),
    )

    assert client.call_count == 2
    # The exploration budget is separate from bounded protocol settlement:
    # one follow-up round retains tools so already-started work can settle.
    assert "tools" in client.calls[-1]
    settlement_instruction = client.calls[-1]["messages"][-1]["content"]
    assert "exploration round budget" in settlement_instruction.lower()
    result = _result(events)
    assert result.metadata["response"] == "Best effort answer."
    assert result.metadata["completed"] is True
    assert result.metadata["settlement_rounds"] == 1


@pytest.mark.asyncio
async def test_budget_settlement_completes_quiz_ask_grade_and_feedback(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A quiz registered on the final exploration round still gets shown,
    answered, graded, and followed by deterministic learner feedback."""

    class _MasteryRegistry(_Registry):
        def build_openai_schemas(self, _enabled):
            schemas = super().build_openai_schemas(_enabled)
            schemas.extend(
                [
                    {
                        "type": "function",
                        "function": {
                            "name": name,
                            "description": name,
                            "parameters": {
                                "type": "object",
                                "properties": {},
                                "additionalProperties": True,
                            },
                        },
                    }
                    for name in ("mastery_quiz", "mastery_grade")
                ]
            )
            return schemas

        async def execute(self, name: str, **kwargs):
            self.executed.append({"name": name, "kwargs": kwargs})
            if name == "ask_user":
                return ToolResult(
                    content="Asked the learner.",
                    success=True,
                    pause_for_user={"questions": kwargs["questions"]},
                )
            if name == "mastery_quiz":
                return ToolResult(content="Quiz q1 registered.", success=True)
            if name == "mastery_grade":
                return ToolResult(content="Correct; objective mastered.", success=True)
            raise AssertionError(f"unexpected tool: {name}")

    registry = _MasteryRegistry()
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(
                    tool_calls=[
                        {
                            "id": "quiz-1",
                            "name": "mastery_quiz",
                            "arguments": "{}",
                        }
                    ]
                )
            ],
            [
                _llm_chunk(
                    tool_calls=[
                        {
                            "id": "ask-1",
                            "name": "ask_user",
                            "arguments": json.dumps(
                                {"questions": [{"id": "q1", "prompt": "Which answer?"}]}
                            ),
                        }
                    ]
                )
            ],
            [
                _llm_chunk(
                    tool_calls=[
                        {
                            "id": "grade-1",
                            "name": "mastery_grade",
                            "arguments": json.dumps({"question_id": "q1", "answer": "B"}),
                        }
                    ]
                )
            ],
            [_llm_chunk(content="Correct — here is why B is the right answer.")],
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    pipeline._max_rounds = 1
    monkeypatch.setattr(
        pipeline,
        "_compose_enabled_tools",
        lambda _context: ["mastery_quiz", "ask_user", "mastery_grade"],
    )
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    async def _waiter():
        return {"text": "B"}

    events = await _run(
        pipeline,
        UnifiedContext(
            session_id="s1",
            user_message="Quiz me",
            enabled_tools=["mastery_quiz", "ask_user", "mastery_grade"],
            runtime=TurnRuntimeContext(wait_for_user_reply=_waiter),
        ),
    )

    assert [entry["name"] for entry in registry.executed] == [
        "mastery_quiz",
        "ask_user",
        "mastery_grade",
    ]
    assert client.call_count == 4
    # All three settlement rounds retain the tool contract; the final one
    # chooses to finish without calling another tool.
    assert all("tools" in call for call in client.calls)
    grade_round = client.calls[2]["messages"]
    assert any(
        message.get("role") == "tool" and "User answered" in str(message.get("content"))
        for message in grade_round
    )
    result = _result(events)
    assert result.metadata["response"] == "Correct — here is why B is the right answer."
    assert result.metadata["completed"] is True
    assert result.metadata["rounds"] == 4
    assert result.metadata["settlement_rounds"] == 3


@pytest.mark.asyncio
async def test_settlement_hard_limit_forces_one_tool_less_finish(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A model that ignores settlement instructions cannot loop forever."""
    registry = _Registry()
    repeated_tool_rounds = [
        [
            _llm_chunk(
                tool_calls=[
                    {
                        "id": f"call-{index}",
                        "name": "web_search",
                        "arguments": json.dumps({"query": f"step {index}"}),
                    }
                ]
            )
        ]
        for index in range(4)
    ]
    client = _ScriptedChatClient([*repeated_tool_rounds, [_llm_chunk(content="Hard-stop answer.")]])
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    pipeline._max_rounds = 1
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(
        pipeline,
        UnifiedContext(session_id="s1", user_message="Research", enabled_tools=["web_search"]),
    )

    # N exploration calls + 3 tool-enabled settlement calls + 1 hard finish.
    assert client.call_count == 5
    assert all("tools" in call for call in client.calls[:4])
    assert "tools" not in client.calls[4]
    assert len(registry.executed) == 4
    result = _result(events)
    assert result.metadata["response"] == "Hard-stop answer."
    assert result.metadata["completed"] is True
    assert result.metadata["rounds"] == 5
    assert result.metadata["settlement_rounds"] == 3


@pytest.mark.asyncio
async def test_length_finish_reason_continues_within_bounded_settlement(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A token-truncated, tool-less round is incomplete, not a finish."""
    registry = _Registry()
    client = _ScriptedChatClient(
        [
            [_llm_chunk(content="Part one is incomplete. ", finish_reason="length")],
            [_llm_chunk(content="Part two completes the answer.", finish_reason="stop")],
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    pipeline._max_rounds = 1
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(
        pipeline,
        UnifiedContext(session_id="s1", user_message="Explain fully", enabled_tools=["web_search"]),
    )

    assert client.call_count == 2
    continuation_messages = client.calls[1]["messages"]
    assert continuation_messages[-2] == {
        "role": "assistant",
        "content": "Part one is incomplete. ",
    }
    assert "token limit" in continuation_messages[-1]["content"].lower()
    markers = [
        event.metadata
        for event in events
        if event.type == StreamEventType.PROGRESS
        and event.metadata.get("call_state") == "complete"
        and "call_role" in event.metadata
    ]
    assert markers[0]["call_role"] == "narration"
    assert markers[0]["answer_visible"] is True
    assert markers[1]["call_role"] == "finish"
    result = _result(events)
    expected = "Part one is incomplete. Part two completes the answer."
    assert result.metadata["response"] == expected
    # RESULT/SDK and event-replay consumers use the exact same visible bytes.
    assert "".join(_contents(events)) == expected
    assert result.metadata["completed"] is True
    assert result.metadata["settlement_rounds"] == 1


@pytest.mark.asyncio
async def test_repeated_reasoning_only_finishes_are_bounded(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A second reasoning-only miss gets a stronger directive and a hard finish."""
    registry = _Registry()
    client = _ScriptedChatClient(
        [
            [_llm_chunk(content="<think>first empty</think>")],
            [_llm_chunk(content="<think>still empty</think>")],
            [_llm_chunk(content="Recovered after the hard finish.")],
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    pipeline._max_rounds = 1
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(pipeline, UnifiedContext(session_id="s1", user_message="Answer"))

    assert client.call_count == 3
    forced_request = client.calls[2]["messages"]
    forced_instruction = str(forced_request[-1]["content"])
    assert "Do not reason further" in forced_instruction
    assert "Stop calling tools" in forced_instruction
    result = _result(events)
    assert result.metadata["response"] == "Recovered after the hard finish."
    assert result.metadata["completed"] is True
    assert result.metadata["settlement_rounds"] == 1


@pytest.mark.asyncio
async def test_reasoning_only_hard_finish_has_distinct_fallback(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """Reasoning without an answer is not reported as an opaque model failure."""
    registry = _Registry()
    client = _ScriptedChatClient(
        [
            [_llm_chunk(content="<think>first empty</think>")],
            [_llm_chunk(content="<think>still empty</think>")],
            [_llm_chunk(content="<think>reasoned away the hard finish</think>")],
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = registry
    pipeline._max_rounds = 1
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(pipeline, UnifiedContext(session_id="s1", user_message="Answer"))

    assert client.call_count == 3
    result = _result(events)
    assert result.metadata["response"] == (
        "The model produced internal reasoning but no usable answer. "
        "Please try again or narrow the request."
    )
    assert result.metadata["completed"] is True
    assert result.metadata["settlement_rounds"] == 1


def test_compose_enabled_tools_injects_rag_when_kb_selected(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    monkeypatch.setattr(
        "deeptutor.services.memory.get_memory_store",
        lambda: SimpleNamespace(read_raw=lambda *_args, **_kwargs: ""),
    )
    monkeypatch.setattr(
        "deeptutor.services.notebook.get_notebook_manager",
        lambda: SimpleNamespace(list_notebooks=lambda: []),
    )
    pipeline = AgenticChatPipeline.__new__(AgenticChatPipeline)
    pipeline._deferred_loader = None
    pipeline._exec_enabled = False
    pipeline.registry = SimpleNamespace(
        get_enabled=lambda selected: [SimpleNamespace(name=n) for n in selected]
    )
    context = UnifiedContext(
        user_message="hi",
        enabled_tools=["web_search"],
        knowledge_bases=["kb-a"],
    )
    assert "rag" in pipeline._compose_enabled_tools(context)
    assert "web_search" in pipeline._compose_enabled_tools(context)


def test_compose_enabled_tools_mounts_mastery_plugin_only_in_mastery_mode(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    monkeypatch.setattr(
        "deeptutor.services.memory.get_memory_store",
        lambda: SimpleNamespace(read_raw=lambda *_args, **_kwargs: ""),
    )
    monkeypatch.setattr(
        "deeptutor.services.notebook.get_notebook_manager",
        lambda: SimpleNamespace(list_notebooks=lambda: []),
    )
    pipeline = AgenticChatPipeline.__new__(AgenticChatPipeline)
    pipeline._deferred_loader = None
    pipeline._exec_enabled = False
    pipeline.registry = SimpleNamespace(
        get_enabled=lambda selected: [SimpleNamespace(name=n) for n in selected]
    )

    ordinary = UnifiedContext(user_message="hi")
    mastery = UnifiedContext(
        user_message="teach me",
        metadata={"mastery_mode": True, "mastery_path_id": "path-a"},
    )

    ordinary_tools = pipeline._compose_enabled_tools(ordinary)
    mastery_tools = pipeline._compose_enabled_tools(mastery)
    assert not set(MASTERY_TOOL_NAMES).intersection(ordinary_tools)
    assert set(MASTERY_TOOL_NAMES).issubset(mastery_tools)
    # Additive plugin surface: a mastery turn reuses chat's full built-in
    # surface (always-on defaults included) and just adds its owned tools.
    assert {"web_fetch", "github", "cron"}.issubset(mastery_tools)
    assert {"web_fetch", "github", "cron"}.issubset(ordinary_tools)


def test_augment_tool_kwargs_injects_mastery_path_id() -> None:
    pipeline = AgenticChatPipeline.__new__(AgenticChatPipeline)
    context = UnifiedContext(
        user_message="teach",
        metadata={"mastery_mode": True, "mastery_path_id": "book-1"},
    )

    augmented = pipeline._augment_tool_kwargs("mastery_status", {}, context)

    assert augmented["_mastery_path_id"] == "book-1"


def test_augment_tool_kwargs_injects_geogebra_image() -> None:
    pipeline = AgenticChatPipeline.__new__(AgenticChatPipeline)
    pipeline.language = "zh"
    context = UnifiedContext(
        user_message="solve this triangle",
        attachments=[
            Attachment(
                type="image",
                base64="REAL_IMG_BYTES",
                filename="problem.png",
                mime_type="image/png",
            ),
        ],
        language="zh",
    )

    augmented = pipeline._augment_tool_kwargs(
        "geogebra_analysis",
        {"image_base64": "HALLUCINATED"},
        context,
    )

    assert augmented["image_base64"] == "data:image/png;base64,REAL_IMG_BYTES"
    assert augmented["language"] == "zh"


def test_build_llm_tool_schemas_kb_name_enum_matches_attached() -> None:
    pipeline = AgenticChatPipeline.__new__(AgenticChatPipeline)
    pipeline.registry = _Registry()

    schemas = pipeline._build_llm_tool_schemas(
        ["web_search"],
        UnifiedContext(knowledge_bases=["kb-a", "kb-b"]),
    )

    assert schemas[0]["function"]["parameters"]["additionalProperties"] is False


def _draft_payloads(events: list[StreamEvent]) -> list[dict[str, Any]]:
    """Card previews the round published while ``ask_user`` was streaming."""
    return [
        event.metadata["ask_user_draft"]
        for event in events
        if event.type == StreamEventType.PROGRESS
        and isinstance(event.metadata.get("ask_user_draft"), dict)
    ]


def _ask_user_argument_chunks() -> list[str]:
    """The card's arguments split the way a provider streams them."""
    arguments = json.dumps(
        {
            "intro": "Which path?",
            "questions": [
                {
                    "id": "which",
                    "prompt": "Where should we pick up?",
                    "options": [
                        {"label": "Advanced route", "description": "15 goals in all"},
                        {"label": "Core design", "description": "4 goals, focused"},
                    ],
                }
            ],
        },
        ensure_ascii=False,
    )
    size = 30
    return [arguments[start : start + size] for start in range(0, len(arguments), size)]


@pytest.mark.asyncio
async def test_ask_user_card_is_previewed_while_its_arguments_stream(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A card is drawn as it is written, not dropped in whole at the end.

    ``ask_user``'s arguments *are* what the reader is waiting on, and writing
    a card with explained options takes seconds. The round used to go silent
    for all of it. Now each fragment grows a preview, and the last preview
    matches the payload the dispatched call carries.
    """
    chunks = _ask_user_argument_chunks()
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(content="Let me check which one you mean."),
                _llm_chunk(tool_calls=[{"id": "ask-1", "name": "ask_user", "arguments": ""}]),
                *(
                    _llm_chunk(tool_calls=[{"id": "ask-1", "name": "ask_user", "arguments": chunk}])
                    for chunk in chunks
                ),
            ]
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["ask_user"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(
        pipeline,
        UnifiedContext(session_id="s1", user_message="take me back", enabled_tools=["ask_user"]),
    )

    drafts = _draft_payloads(events)
    assert drafts, "the card was never previewed"
    shapes = [(len(d["questions"]), sum(len(q["options"]) for q in d["questions"])) for d in drafts]
    assert shapes == sorted(shapes), f"the previewed card shrank: {shapes}"
    assert drafts[-1]["intro"] == "Which path?"
    assert [
        option["label"] for question in drafts[-1]["questions"] for option in question["options"]
    ] == ["Advanced route", "Core design"]
    # Every preview arrives before the call that replaces it.
    types = [
        event.type
        for event in events
        if event.type == StreamEventType.TOOL_CALL
        or (
            event.type == StreamEventType.PROGRESS
            and isinstance(event.metadata.get("ask_user_draft"), dict)
        )
    ]
    assert types.index(StreamEventType.TOOL_CALL) == len(drafts)


@pytest.mark.asyncio
async def test_native_adapter_tool_argument_previews_reach_the_card(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A native-provider adapter reports arguments on the chunk, not the delta.

    Responses-API providers hand the loop one finished tool call, so their
    in-flight arguments ride on ``provider_specific_fields`` instead. Both
    shapes must end at the same preview.
    """
    chunks = _ask_user_argument_chunks()
    accumulated: list[str] = []
    for chunk in chunks:
        accumulated.append((accumulated[-1] if accumulated else "") + chunk)
    client = _ScriptedChatClient(
        [
            [
                *(
                    _llm_chunk(
                        provider_specific_fields={
                            "tool_args_preview": {
                                "id": "ask-1",
                                "name": "ask_user",
                                "arguments": text,
                            }
                        }
                    )
                    for text in accumulated
                ),
                _llm_chunk(
                    tool_calls=[
                        {"id": "ask-1|item-9", "name": "ask_user", "arguments": accumulated[-1]}
                    ]
                ),
            ]
        ]
    )
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["ask_user"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(
        pipeline,
        UnifiedContext(session_id="s1", user_message="take me back", enabled_tools=["ask_user"]),
    )

    drafts = _draft_payloads(events)
    assert drafts, "the card was never previewed"
    assert drafts[-1]["intro"] == "Which path?"
    # The composite dispatch id and the preview id name the same card.
    call_ids = {
        event.metadata.get("draft_call_id")
        for event in events
        if isinstance(event.metadata.get("ask_user_draft"), dict)
    }
    assert call_ids == {"ask-1"}


@pytest.mark.asyncio
async def test_truncated_tool_call_says_the_output_hit_the_limit(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """The reader must learn the round was cut off, not just that an arg is missing.

    Visualize's canvas came back empty with nothing on screen explaining why: a
    reasoning model spent the round's budget on ``<think>`` and the tool call's
    JSON stopped mid-argument, so the only trace row was the arg guard's
    "missing query" — which reads as a model that forgot a field (#1546).
    """
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(
                    content="<think>先想清楚画什么</think>",
                    tool_calls=[{"id": "a", "name": "web_search", "arguments": '{"que'}],
                    finish_reason="length",
                )
            ],
            [_llm_chunk(content="答案", finish_reason="stop")],
        ]
    )
    pipeline = AgenticChatPipeline(language="zh")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)

    events = await _run(pipeline, UnifiedContext(session_id="s1", user_message="画一张图"))

    warnings = [
        str(event.content)
        for event in events
        if (event.metadata or {}).get("trace_kind") == "warning"
    ]
    assert any("输出 token 上限" in text for text in warnings)
    # The notice is a report, not a control-flow change: the round is handled
    # exactly as before and the turn still finishes.
    assert _answer_text(events) == "答案"


@pytest.mark.asyncio
async def test_wire_deduplicates_user_images_without_mutating_model_history(monkeypatch):
    from copy import deepcopy

    image = {"type": "image_url", "image_url": {"url": "data:image/png;base64,YWJj"}}
    messages = [
        {"role": "user", "content": [image]},
        {"role": "assistant", "content": "answer"},
        {"role": "user", "content": [deepcopy(image)]},
    ]
    original = deepcopy(messages)
    client = _ScriptedChatClient([[_llm_chunk(content="answer")]])
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)
    pipeline._model_turn_start = 0
    monkeypatch.setattr(pipeline, "_build_loop_messages", lambda *_args, **_kwargs: messages)
    await _run(pipeline, UnifiedContext(session_id="s", user_message="again"))
    wire = client.calls[0]["messages"]
    assert wire[0]["content"][-1] == original[0]["content"][0]
    assert "Repeated image" in wire[2]["content"][0]["text"]
    assert [message["content"] for message in messages[:3]] == [
        message["content"] for message in original
    ]


@pytest.mark.asyncio
@pytest.mark.parametrize("distinct", [False, True])
async def test_request_guard_budgets_projected_images_and_preserves_tool_history(
    monkeypatch, distinct
):
    from copy import deepcopy

    messages = []
    for turn in range(4):
        images = [
            {
                "type": "image_url",
                "image_url": {
                    "url": f"data:image/png;base64,image-{4 * turn + i if distinct else i}"
                },
            }
            for i in range(4)
        ]
        messages.extend(
            [
                {"role": "user", "content": images},
                {
                    "role": "assistant",
                    "content": None,
                    "tool_calls": [
                        {
                            "id": f"call-{turn}",
                            "type": "function",
                            "function": {"name": "web_search", "arguments": '{"query":"source"}'},
                        }
                    ],
                },
                {"role": "tool", "tool_call_id": f"call-{turn}", "content": f"evidence {turn}"},
                {"role": "assistant", "content": "answer"},
            ]
        )
    original = deepcopy(messages)
    client = _ScriptedChatClient([[_llm_chunk(content="answer")]])
    pipeline = AgenticChatPipeline(language="en")
    pipeline.llm_config = SimpleNamespace(context_window=60000, max_tokens=4096)
    pipeline.registry = _Registry()
    pipeline._model_turn_start = 0
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: [])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)
    monkeypatch.setattr(pipeline, "_build_loop_messages", lambda *_args, **_kwargs: messages)

    await _run(pipeline, UnifiedContext(session_id="s", user_message="again"))

    wire_tools = [
        message["content"] for message in client.calls[0]["messages"] if message["role"] == "tool"
    ]
    expected = (
        [pipeline._tool_result_snip_marker()] * 4
        if distinct
        else [f"evidence {turn}" for turn in range(4)]
    )
    assert wire_tools == expected
    assert messages[: len(original)] == original


@pytest.mark.asyncio
async def test_image_fallback_strips_all_canonical_copies_after_wire_deduplication(monkeypatch):
    from copy import deepcopy

    from deeptutor.services.llm.multimodal import has_image_parts

    image = {"type": "image_url", "image_url": {"url": "data:image/png;base64,YWJj"}}
    messages = [
        {"role": "user", "content": [image]},
        {"role": "user", "content": [deepcopy(image)]},
    ]
    client = _ScriptedChatClient(
        [
            [
                _llm_chunk(
                    tool_calls=[
                        {"id": "search-1", "name": "web_search", "arguments": '{"query":"text"}'}
                    ],
                    finish_reason="tool_calls",
                )
            ],
            [_llm_chunk(content="Text answer.")],
        ]
    )
    create = client.chat.completions.create
    attempted = []

    async def reject_images(**kwargs):
        attempted.append(deepcopy(kwargs["messages"]))
        if has_image_parts(kwargs["messages"]):
            raise RuntimeError("image input is not supported")
        return await create(**kwargs)

    client.chat.completions.create = reject_images
    pipeline = AgenticChatPipeline(language="en")
    pipeline.model = "gpt-3.5-turbo"
    pipeline.registry = _Registry()
    pipeline._model_turn_start = 0
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["web_search"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)
    monkeypatch.setattr(pipeline, "_build_loop_messages", lambda *_args, **_kwargs: messages)
    context = UnifiedContext(session_id="s", user_message="again")
    await _run(pipeline, context)
    assert len(attempted) == 3
    assert not has_image_parts(attempted[1])
    assert not has_image_parts(attempted[2])
    assert not has_image_parts(messages)
    assert context.extension("source_visual_evidence")["image_hashes"] == []
    assert "Repeated image" not in str(messages)


@pytest.mark.asyncio
async def test_mastery_objection_preserves_option_by_option_explanation(monkeypatch):
    explanation = (
        "你的异议有道理,这道题的答案需要补充前提。\n"
        "A. 在原来的前提下成立。\nB. 在你提出的前提下也成立。\n"
        "C. 缺少条件,不能唯一确定。\nD. 不能直接排除。"
    )
    client = _ScriptedChatClient([[_llm_chunk(content=explanation)]])
    pipeline = AgenticChatPipeline(language="zh")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _context: ["ask_user"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)
    context = UnifiedContext(
        session_id="objection",
        user_message="我认为 B 也对,为什么答案只有 A?请先解释,不要继续出题。",
        metadata={"mastery_mode": True, "mastery_path_id": ""},
    )
    context.extension("mastery")["quiz_awaiting_grade"] = True
    events = await _run(pipeline, context)
    assert client.call_count == 1
    assert _answer_text(events) == explanation
    assert _result(events).metadata["response"] == explanation
    assert _result(events).metadata["completed"] is True
    assert not any(e.metadata.get("answer_visible") is False for e in events)


@pytest.mark.asyncio
async def test_public_answer_with_capability_notice_is_preserved_once(monkeypatch):
    explanation = "Your objection is valid because B also satisfies the condition."
    notice = "The profile change could not be saved."
    client = _ScriptedChatClient([[_llm_chunk(content=explanation)]])
    pipeline = AgenticChatPipeline(language="en")
    pipeline.registry = _Registry()
    monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _: ["ask_user"])
    monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)
    monkeypatch.setattr(
        pipeline, "_capability_final_text_override", lambda _, text: notice + "\n\n" + text
    )
    events = await _run(pipeline, UnifiedContext(user_message="Why not B?"))
    answer = _answer_text(events)
    assert answer.count(explanation) == 1
    assert answer.count(notice) == 1
    assert answer.startswith(explanation)
    assert _result(events).metadata["response"] == answer