Skip to content

Enterprise agent platform for building, deploying, and operating AI teammates.

81.9 KB
Raw Blame
from __future__ import annotations

import asyncio
import json
import re
from datetime import datetime, timezone
from types import SimpleNamespace
from typing import Any, cast
from zoneinfo import ZoneInfo

import pytest

from xagent.core.agent import (
    AgentExecutionAdapter,
    AgentExecutionConfig,
    ExecutionContext,
    PatternRuntime,
    ReActPattern,
)
from xagent.core.agent import execution_adapter as execution_adapter_module
from xagent.core.agent.context.execution import TURN_CONTEXT_HEADER
from xagent.core.agent.context.memory_retrieval import (
    MEMORY_RETRIEVAL_SCOPE_FINGERPRINT_METADATA_KEY,
)
from xagent.core.agent.execution_adapter import INTERRUPTED_USER_MESSAGE
from xagent.core.agent.result import COMPLETION_OUTCOMES, NO_OUTPUT_PLACEHOLDER
from xagent.core.agent.runner import UserMessageInjectionOutcome
from xagent.core.agent.service import AgentService
from xagent.core.memory.in_memory import InMemoryMemoryStore
from xagent.core.task_runtime import PREFERRED_INPUT_MODALITIES_METADATA_KEY


def _without_turn_context(content: object) -> str:
    """The message text without the per-turn context appended to the request."""
    return str(content).split(f"\n\n{TURN_CONTEXT_HEADER}", 1)[0]


def _all_text(messages: list[dict[str, Any]]) -> str:
    return "\n\n".join(str(message.get("content") or "") for message in messages)


class FakeLLM:
    def __init__(self, responses: list[Any]) -> None:
        self.responses = responses
        self.calls: list[dict[str, Any]] = []
        self.model_name = "fake-llm"

    async def chat(self, **kwargs: Any) -> Any:
        self.calls.append(kwargs)
        return self.responses.pop(0)


class BlockingLLM:
    def __init__(self, response: Any = "released") -> None:
        self.response = response
        self.started = asyncio.Event()
        self.release = asyncio.Event()
        self.calls: list[dict[str, Any]] = []

    async def chat(self, **kwargs: Any) -> Any:
        self.calls.append(kwargs)
        self.started.set()
        await self.release.wait()
        return self.response


class TracerCheckpointStore:
    def __init__(self) -> None:
        self.by_execution_id: dict[str, dict[str, Any]] = {}

    async def checkpoint(self, **payload: Any) -> None:
        self.by_execution_id[str(payload["execution_id"])] = dict(payload)

    async def load_latest_checkpoint(self, execution_id: str) -> dict[str, Any] | None:
        payload = self.by_execution_id.get(execution_id)
        return dict(payload) if payload is not None else None

    async def trace_event(self, event_type: Any, **kwargs: Any) -> str:
        return f"{event_type}-{kwargs.get('execution_id', 'execution')}"


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

    async def trace_event(self, event_type: Any, **kwargs: Any) -> str:
        self.events.append({"event_type": event_type, **kwargs})
        return f"event-{len(self.events)}"


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

        class Metadata:
            name = "noop"
            description = "No-op test tool."

        self.metadata = Metadata()
        self.name = "noop"

    def args_type(self) -> type:
        class Args:
            @staticmethod
            def model_json_schema() -> dict[str, Any]:
                return {"type": "object", "properties": {}}

        return Args

    async def run_json_async(self, args: dict[str, Any]) -> dict[str, Any]:
        self.calls.append(args)
        return {"args": args}

    async def setup(self, task_id: str | None = None) -> None:
        self.setup_calls.append(task_id)

    async def teardown(self, task_id: str | None = None) -> None:
        self.teardown_calls.append(task_id)


class StartHandle:
    task = None

    def to_dict(self) -> dict[str, Any]:
        return {"status": "running"}


class RecordingRegistry:
    def __init__(self) -> None:
        self.start_kwargs: dict[str, Any] | None = None

    def start(self, *args: Any, **kwargs: Any) -> StartHandle:
        self.start_kwargs = dict(kwargs)
        return StartHandle()


class BindingSnapshotRegistry:
    def __init__(self) -> None:
        self.handles: dict[str, SimpleNamespace] = {}
        self.started_runners: list[Any] = []
        self.resumed_binding: tuple[Any, Any] | None = None
        self.resume_kwargs: dict[str, Any] | None = None

    def start(
        self,
        runner: Any,
        *,
        execution_id: str,
        metadata: dict[str, Any],
        **_kwargs: Any,
    ) -> StartHandle:
        self.started_runners.append(runner)
        self.handles[execution_id] = SimpleNamespace(
            runner=runner,
            metadata=dict(metadata),
        )
        return StartHandle()

    def get(self, execution_id: str) -> SimpleNamespace | None:
        return self.handles.get(execution_id)

    async def resume(self, execution_id: str, **kwargs: Any) -> dict[str, Any]:
        self.resume_kwargs = dict(kwargs)
        runner = self.handles[execution_id].runner
        self.resumed_binding = (
            runner.agent.memory_store,
            runner.agent.memory_tools_factory,
        )
        return {"success": True, "output": "resumed"}


class NoSkillManager:
    async def list_skills(self) -> list[dict[str, Any]]:
        return []

    async def get_skill(self, name: str) -> None:
        return None


class ReusedExecutionAdapter:
    def __init__(self, config: SimpleNamespace) -> None:
        self.config = config
        self.execute_kwargs: dict[str, Any] | None = None

    async def execute(self, **kwargs: Any) -> dict[str, Any]:
        self.execute_kwargs = dict(kwargs)
        return {"success": True}


def test_runner_pattern_kwargs_include_custom_memory_tool_factory() -> None:
    def factory(**_kwargs: Any) -> list[Any]:
        return []

    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="memory-factory-kwargs",
            pattern="auto",
            llm=FakeLLM([]),
            memory_store=InMemoryMemoryStore(),
            memory_tools_factory=factory,
        )
    )
    runner, _ = adapter._build_runner()
    pattern = runner.agent.patterns[0]

    kwargs = runner._build_pattern_kwargs(
        pattern=pattern,
        task="remember",
        context=ExecutionContext(execution_id="memory-factory-kwargs"),
        tools=[],
        runtime=PatternRuntime(execution_id="memory-factory-kwargs"),
        streaming_handler=None,
    )

    assert kwargs["memory_tools_factory"] is factory


def test_execution_adapter_can_disable_skills_and_preserve_internal_metadata() -> None:
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="builtin:internal_worker",
            pattern="single_call",
            llm=FakeLLM([]),
            allowed_skills=["must-not-load"],
            skills_enabled=False,
            user_interaction_enabled=False,
            execution_metadata={
                "agent_type": "builtin",
                "builtin_agent_name": "internal_worker",
            },
        )
    )

    runner, execution_type = adapter._build_runner()
    metadata = adapter._execution_metadata(execution_type=execution_type)
    normalized = adapter._normalize_result(
        result={"success": True, "output": "ok"},
        execution_type=execution_type,
        execution_id="run-1",
    )

    assert runner.agent.skill_manager is None
    assert runner.agent.allowed_skills is None
    assert [
        schema["function"]["name"]
        for schema in runner.agent.patterns[0]._builtin_tool_schemas()
    ] == ["final_answer"]
    assert runner.agent.metadata == {
        "agent_type": "builtin",
        "builtin_agent_name": "internal_worker",
        "pattern": "single_call",
    }
    assert metadata["agent_type"] == "builtin"
    assert metadata["builtin_agent_name"] == "internal_worker"
    assert normalized["metadata"]["agent_type"] == "builtin"
    assert normalized["metadata"]["builtin_agent_name"] == "internal_worker"


@pytest.mark.asyncio
@pytest.mark.parametrize("pattern_name", ["react", "dag_plan_execute", "auto"])
async def test_execution_binding_is_snapshotted_until_next_start_or_resume(
    pattern_name: str,
) -> None:
    old_store = InMemoryMemoryStore()
    new_store = InMemoryMemoryStore()

    def old_factory(_request: object) -> list[str]:
        return ["old"]

    def new_factory(_request: object) -> list[str]:
        return ["new"]

    registry = BindingSnapshotRegistry()
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="memory-binding-snapshot",
            pattern=pattern_name,
            llm=FakeLLM([]),
            registry=cast(Any, registry),
            memory_store=old_store,
            memory_tools_factory=old_factory,
            execution_metadata={
                MEMORY_RETRIEVAL_SCOPE_FINGERPRINT_METADATA_KEY: "old-fingerprint"
            },
        )
    )

    adapter.start(task="active turn", task_id="active")
    active_runner = registry.started_runners[-1]

    adapter.config.memory_store = new_store
    adapter.config.memory_tools_factory = new_factory
    adapter.config.execution_metadata = {
        MEMORY_RETRIEVAL_SCOPE_FINGERPRINT_METADATA_KEY: "new-fingerprint"
    }

    assert active_runner.agent.memory_store is old_store
    assert active_runner.agent.memory_tools_factory is old_factory
    assert (
        active_runner.agent.metadata[MEMORY_RETRIEVAL_SCOPE_FINGERPRINT_METADATA_KEY]
        == "old-fingerprint"
    )

    adapter.start(task="next turn", task_id="next")
    next_runner = registry.started_runners[-1]
    assert next_runner.agent.memory_store is new_store
    assert next_runner.agent.memory_tools_factory is new_factory
    assert (
        next_runner.agent.metadata[MEMORY_RETRIEVAL_SCOPE_FINGERPRINT_METADATA_KEY]
        == "new-fingerprint"
    )

    await adapter.resume("active")
    assert registry.resumed_binding == (new_store, new_factory)
    assert registry.resume_kwargs is not None
    assert (
        registry.resume_kwargs["metadata"][
            MEMORY_RETRIEVAL_SCOPE_FINGERPRINT_METADATA_KEY
        ]
        == "new-fingerprint"
    )


@pytest.mark.asyncio
async def test_fresh_execution_uses_server_memory_fingerprint_over_request_context() -> (
    None
):
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="memory-policy",
            pattern="react",
            llm=FakeLLM(["done"]),
            tools=[],
            execution_metadata={
                MEMORY_RETRIEVAL_SCOPE_FINGERPRINT_METADATA_KEY: "trusted"
            },
            skill_manager=NoSkillManager(),
        )
    )

    result = await adapter.execute(
        task="answer",
        task_id="memory-policy",
        context={MEMORY_RETRIEVAL_SCOPE_FINGERPRINT_METADATA_KEY: "spoofed"},
    )

    assert (
        result["agent_result"]["context"].metadata[
            MEMORY_RETRIEVAL_SCOPE_FINGERPRINT_METADATA_KEY
        ]
        == "trusted"
    )


@pytest.mark.parametrize("pattern_name", ["dag_plan_execute", "auto"])
def test_execution_adapter_propagates_interaction_policy_to_nested_patterns(
    pattern_name: str,
) -> None:
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="builtin:nested_worker",
            pattern=pattern_name,
            llm=FakeLLM([]),
            skills_enabled=False,
            user_interaction_enabled=False,
        )
    )

    runner, _ = adapter._build_runner()
    pattern = runner.agent.patterns[0]

    assert runner.agent.skill_manager is None
    if pattern_name == "dag_plan_execute":
        assert pattern.user_interaction_enabled is False
    else:
        assert pattern.react_pattern.user_interaction_enabled is False
        assert pattern.dag_pattern.user_interaction_enabled is False


def test_execution_metadata_carries_runtime_modality_preferences() -> None:
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="test",
            pattern="react",
            llm=FakeLLM([]),
            preferred_input_modalities=("IMAGE", "image"),
        )
    )

    metadata = adapter._execution_metadata(execution_type="react")

    assert metadata[PREFERRED_INPUT_MODALITIES_METADATA_KEY] == ["image"]


def test_execution_metadata_omits_empty_runtime_modality_preferences() -> None:
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="test",
            pattern="react",
            llm=FakeLLM([]),
        )
    )

    metadata = adapter._execution_metadata(execution_type="react")

    assert PREFERRED_INPUT_MODALITIES_METADATA_KEY not in metadata


def auto_decision(
    action: str, *, answer: str = "", reason: str = "test"
) -> dict[str, Any]:
    return {
        "tool_calls": [
            {
                "id": "call-select",
                "function": {
                    "name": "select_execution_pattern",
                    "arguments": {
                        "action": action,
                        "reason": reason,
                        "answer": answer,
                        "requires_current_or_external_facts": False,
                        "existing_context_sufficient": True,
                        "evidence_basis": "test context",
                        "missing_verification": "",
                    },
                },
            }
        ]
    }


def dag_plan(steps: list[dict[str, Any]]) -> dict[str, Any]:
    return {
        "tool_calls": [
            {
                "id": "call-plan",
                "function": {
                    "name": "generate_execution_plan",
                    "arguments": {"steps": steps, "response_language": "English"},
                },
            }
        ]
    }


def dag_completion(answer: str = "dag done") -> dict[str, Any]:
    return {
        "tool_calls": [
            {
                "id": "call-assess",
                "function": {
                    "name": "assess_dag_completion",
                    "arguments": json.dumps(
                        {
                            "status": "completed",
                            "reason": "Done.",
                            "answer": answer,
                            "missing_work": "",
                            "replan_instruction": "",
                        }
                    ),
                },
            }
        ]
    }


def test_execution_adapter_uses_service_id_as_runner_workspace_id() -> None:
    registry = RecordingRegistry()
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="web-task",
            pattern="react",
            llm=FakeLLM(["unused"]),
            service_id="web_task_458",
            registry=cast(Any, registry),
            skill_manager=NoSkillManager(),
        )
    )

    adapter.start(task="Generate a file", task_id="458")

    assert registry.start_kwargs is not None
    assert registry.start_kwargs["execution_id"] == "458"
    assert registry.start_kwargs["workspace_id"] == "web_task_458"


def test_execution_adapter_projects_request_images_to_task_context_refs() -> None:
    registry = RecordingRegistry()
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="vision-task",
            pattern="react",
            llm=FakeLLM(["unused"]),
            service_id="vision-service",
            registry=cast(Any, registry),
            skill_manager=NoSkillManager(),
        )
    )

    adapter.start(
        task="Inspect the upload",
        task_id="vision-exec",
        context={
            "file_info": [
                {
                    "file_id": "image-id",
                    "name": "screen.png",
                    "type": "image/png",
                    "path": "/private/runtime/screen.png",
                }
            ],
            # The display-safe projection can be present at the same time and
            # must not duplicate the provider image.
            "files": [
                {
                    "file_id": "image-id",
                    "name": "display-screen.png",
                    "type": "image/png",
                }
            ],
        },
    )

    assert registry.start_kwargs is not None
    references = registry.start_kwargs["task_context_refs"]
    assert len(references) == 1
    assert references[0].file_id == "image-id"
    assert "path" not in references[0].durable_dict()["file_ref"]


@pytest.mark.asyncio
async def test_execution_adapter_routes_single_call_to_one_tool_then_final_answer() -> (
    None
):
    llm = FakeLLM(
        [
            {
                "tool_calls": [
                    {
                        "id": "call-noop",
                        "function": {
                            "name": "noop",
                            "arguments": '{"value":"from tool"}',
                        },
                    }
                ]
            },
            {
                "tool_calls": [
                    {
                        "id": "call-final",
                        "function": {
                            "name": "final_answer",
                            "arguments": json.dumps(
                                {
                                    "response_language": "English",
                                    "answer": "done",
                                }
                            ),
                        },
                    }
                ]
            },
        ]
    )
    tool = FakeTool()
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="single",
            pattern="single_call",
            llm=llm,
            tools=[tool],
            service_id="single-service",
            skill_manager=NoSkillManager(),
        )
    )

    result = await adapter.execute(task="Say done", task_id="single-exec")

    assert result["success"] is True
    assert result["status"] == "completed"
    assert result["output"] == "done"
    assert result["metadata"]["execution_type"] == "agent_single_call"
    assert tool.calls == [{"value": "from tool"}]
    assert llm.calls[0]["tools"][0]["function"]["name"] == "noop"
    assert llm.calls[0]["tool_choice"] == "required"
    assert [schema["function"]["name"] for schema in llm.calls[1]["tools"]] == [
        "final_answer"
    ]
    assert llm.calls[1]["tool_choice"] == "required"


@pytest.mark.asyncio
async def test_execution_adapter_routes_react_to_react() -> None:
    llm = FakeLLM(["react done"])
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="react",
            pattern="react",
            llm=llm,
            tools=[FakeTool()],
            service_id="react-service",
            skill_manager=NoSkillManager(),
        )
    )

    result = await adapter.execute(task="Say done", task_id="react-exec")

    assert result["success"] is True
    assert result["output"] == "react done"
    assert result["metadata"]["execution_type"] == "agent_react"
    assert result["agent_result"]["pattern"] == "ReActPattern"
    assert llm.calls[0]["tools"] is not None


@pytest.mark.asyncio
async def test_request_context_timezone_reaches_both_prompt_clocks() -> None:
    """Covers the transport the renderer depends on: request context ->
    metadata["request_context"] -> _apply_request_context -> metadata. The
    renderer's own formatting is unit-tested in tests/core/agent/test_context.py.
    """
    llm = FakeLLM(["tz done"])
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="tz",
            pattern="react",
            llm=llm,
            tools=[FakeTool()],
            service_id="tz-service",
            skill_manager=NoSkillManager(),
        )
    )

    result = await adapter.execute(
        task="how many shifts do we have on tomorrow?",
        task_id="tz-exec",
        context={"timezone": "Australia/Melbourne"},
    )

    assert result["success"] is True
    # The turn clock is in the turn context and the turn-start date in the
    # system message; read the prompt as a whole.
    system_prompt = _all_text(llm.calls[0]["messages"])

    # created_at is a dataclass default_factory, so it cannot be monkeypatched
    # from here. Reading the UTC stamp back out of the prompt pins the pair
    # without a wall-clock race.
    stamped_utc = re.search(
        r"which is (\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) UTC\.", system_prompt
    )
    assert stamped_utc is not None, system_prompt
    expected_local = (
        datetime.strptime(stamped_utc.group(1), "%Y-%m-%d %H:%M:%S")
        .replace(tzinfo=timezone.utc)
        .astimezone(ZoneInfo("Australia/Melbourne"))
    )

    assert (
        f"Turn started at: {expected_local.strftime('%Y-%m-%d %H:%M:%S')} "
        f"(Australia/Melbourne, UTC+" in system_prompt
    )
    assert (
        f"Turn-start date (Australia/Melbourne): {expected_local.date().isoformat()}."
        in system_prompt
    )


@pytest.mark.asyncio
async def test_request_context_without_timezone_keeps_utc_clocks() -> None:
    llm = FakeLLM(["utc done"])
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="utc",
            pattern="react",
            llm=llm,
            tools=[FakeTool()],
            service_id="utc-service",
            skill_manager=NoSkillManager(),
        )
    )

    result = await adapter.execute(task="Say done", task_id="utc-exec", context={})

    assert result["success"] is True
    system_prompt = _all_text(llm.calls[0]["messages"])
    assert "Turn-start date (UTC): " in system_prompt
    assert " UTC. Real time keeps advancing" in system_prompt
    assert "which is" not in system_prompt


@pytest.mark.asyncio
async def test_execution_adapter_propagates_request_context_to_llm() -> None:
    llm = FakeLLM(["context done"])
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="context",
            pattern="react",
            llm=llm,
            tools=[FakeTool()],
            system_prompt="Base system.",
            service_id="context-service",
            skill_manager=NoSkillManager(),
        )
    )

    result = await adapter.execute(
        task="Say done",
        task_id="context-exec",
        context={
            "system_prompt": "Follow request-specific rules.",
            "process_description": "Use the provided process.",
            "examples": [{"input": "hello", "output": "world"}],
        },
    )

    assert result["success"] is True
    system_messages = [
        message["content"]
        for message in llm.calls[0]["messages"]
        if message["role"] == "system"
    ]
    assert len(system_messages) == 1
    system_prompt = system_messages[0]
    assert "Base system." in system_prompt
    assert "Follow request-specific rules." in system_prompt
    assert "Use the provided process." in system_prompt
    assert "Input: hello" in system_prompt
    assert "Output: world" in system_prompt


@pytest.mark.asyncio
async def test_execution_adapter_runs_tool_lifecycle() -> None:
    llm = FakeLLM(["done"])
    tool = FakeTool()
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="lifecycle",
            pattern="react",
            llm=llm,
            tools=[tool],
            service_id="lifecycle-service",
            skill_manager=NoSkillManager(),
        )
    )

    result = await adapter.execute(task="Say done", task_id="lifecycle-exec")

    assert result["success"] is True
    assert tool.setup_calls == ["lifecycle-exec"]
    assert tool.teardown_calls == ["lifecycle-exec"]


@pytest.mark.asyncio
async def test_execution_adapter_preserves_waiting_for_user_payload() -> None:
    interactions = [
        {
            "type": "action_cards",
            "field": "kb_source",
            "label": "Choose source",
            "options": [
                {
                    "label": "Upload",
                    "value": "upload",
                    "action_type": "upload",
                }
            ],
        }
    ]
    llm = FakeLLM(
        [
            {
                "tool_calls": [
                    {
                        "id": "call-ask",
                        "function": {
                            "name": "ask_user_question",
                            "arguments": json.dumps(
                                {
                                    "message": "Need FAQ content",
                                    "interactions": interactions,
                                }
                            ),
                        },
                    }
                ]
            }
        ]
    )
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="react",
            pattern="react",
            llm=llm,
            tools=[],
            service_id="react-service",
            skill_manager=NoSkillManager(),
        )
    )

    result = await adapter.execute(task="Create an FAQ agent", task_id="react-exec")

    assert result["success"] is False
    assert result["status"] == "waiting_for_user"
    assert result["message"] == "Need FAQ content"
    assert result["interactions"] == interactions
    assert result["chat_response"] == {
        "message": "Need FAQ content",
        "interactions": interactions,
    }


@pytest.mark.asyncio
async def test_execution_adapter_surfaces_clarification_draft_at_top_level() -> None:
    llm = FakeLLM(
        [
            {
                "tool_calls": [
                    {
                        "id": "call-ask",
                        "function": {
                            "name": "ask_user_question",
                            "arguments": (
                                '{"message":"Pick one","interactions":'
                                '[{"type":"select_one","field":"choice","label":"Choice"}]}'
                            ),
                        },
                    }
                ]
            }
        ]
    )
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="react",
            pattern="react",
            llm=llm,
            tools=[],
            service_id="react-service",
            skill_manager=NoSkillManager(),
        )
    )

    result = await adapter.execute(task="Ask something", task_id="react-exec")

    assert result["status"] == "waiting_for_user"
    assert result["clarification_draft"] is not None
    assert (
        result["clarification_draft"] is result["agent_result"]["clarification_draft"]
    )


@pytest.mark.asyncio
async def test_execution_adapter_omits_clarification_draft_key_when_not_waiting() -> (
    None
):
    llm = FakeLLM(["done"])
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="lifecycle",
            pattern="react",
            llm=llm,
            tools=[],
            service_id="lifecycle-service",
            skill_manager=NoSkillManager(),
        )
    )

    result = await adapter.execute(task="Say done", task_id="lifecycle-exec")

    assert result["status"] != "waiting_for_user"
    assert "clarification_draft" not in result


def test_execution_adapter_surfaces_superseded_step_ids_at_top_level() -> None:
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="dag",
            pattern="react",
            llm=FakeLLM([]),
            skill_manager=NoSkillManager(),
        )
    )

    with_losers = adapter._normalize_result(
        result={
            "status": "waiting_for_user",
            "success": False,
            "message": "Pick one",
            "clarification_superseded_step_ids": ["ask_b"],
        },
        execution_type="agent_dag",
        execution_id="dag-superseded-exec",
    )
    assert with_losers["clarification_superseded_step_ids"] == ["ask_b"]

    without_losers = adapter._normalize_result(
        result={
            "status": "waiting_for_user",
            "success": False,
            "message": "Pick one",
        },
        execution_type="agent_dag",
        execution_id="dag-no-superseded-exec",
    )
    assert without_losers["clarification_superseded_step_ids"] == []

    not_waiting = adapter._normalize_result(
        result={
            "status": "completed",
            "success": True,
            "output": "done",
        },
        execution_type="agent_dag",
        execution_id="dag-completed-exec",
    )
    assert "clarification_superseded_step_ids" not in not_waiting


def test_execution_adapter_surfaces_superseded_step_ids_for_an_interrupted_winner() -> (
    None
):
    """A batch's winner can be an interrupt rather than a question -- the
    DAG ranks an interrupt ahead of a waiting result within the same
    wakeup -- and a losing waiting step is still superseded in that case.
    The interrupted branch must promote the same top-level key, with the
    same empty-list default, as the waiting branch already does; otherwise
    a reader cannot tell "no sibling was superseded" apart from "this
    status never carries the key"."""

    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="dag",
            pattern="react",
            llm=FakeLLM([]),
            skill_manager=NoSkillManager(),
        )
    )

    with_losers = adapter._normalize_result(
        result={
            "status": "interrupted",
            "success": False,
            "clarification_superseded_step_ids": ["ask_b"],
        },
        execution_type="agent_dag",
        execution_id="dag-interrupted-superseded-exec",
    )
    assert with_losers["clarification_superseded_step_ids"] == ["ask_b"]

    without_losers = adapter._normalize_result(
        result={
            "status": "interrupted",
            "success": False,
        },
        execution_type="agent_dag",
        execution_id="dag-interrupted-no-superseded-exec",
    )
    assert without_losers["clarification_superseded_step_ids"] == []


@pytest.mark.asyncio
async def test_execution_adapter_includes_persisted_conversation_history() -> None:
    llm = FakeLLM(["generated"])
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="history",
            pattern="react",
            llm=llm,
            tools=[FakeTool()],
            service_id="history-service",
            skill_manager=NoSkillManager(),
            conversation_history=[
                {"role": "user", "content": "用 Python 生成随机整数"},
                {"role": "assistant", "content": "可以用 random.randint。"},
            ],
        )
    )

    result = await adapter.execute(task="生成一个返回给我", task_id="history-exec")

    assert result["success"] is True
    messages = llm.calls[0]["messages"]
    assert [
        _without_turn_context(message["content"])
        for message in messages
        if message["role"] == "user"
    ] == [
        "用 Python 生成随机整数",
        "生成一个返回给我",
    ]
    assert any(
        message["role"] == "assistant"
        and message["content"] == "可以用 random.randint。"
        for message in messages
    )


@pytest.mark.asyncio
async def test_execution_adapter_includes_persisted_execution_context_before_history() -> (
    None
):
    llm = FakeLLM(["updated"])
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="execution-context",
            pattern="react",
            llm=llm,
            tools=[FakeTool()],
            service_id="execution-context-service",
            skill_manager=NoSkillManager(),
            execution_context_messages=[
                {
                    "role": "system",
                    "content": "Previous tool result: output/index_en.html exists.",
                }
            ],
            conversation_history=[
                {"role": "user", "content": "写到文件"},
                {"role": "assistant", "content": "已写入文件。"},
            ],
        )
    )

    result = await adapter.execute(task="继续修改文件", task_id="execution-context")

    assert result["success"] is True
    messages = llm.calls[0]["messages"]
    system_messages = [
        message["content"] for message in messages if message["role"] == "system"
    ]
    assert len(system_messages) == 1
    assert any(
        message["role"] == "user"
        and "Previous tool result: output/index_en.html exists." in message["content"]
        for message in messages
    )
    assert [
        _without_turn_context(message["content"])
        for message in messages
        if message["role"] == "user"
    ][-2:] == ["写到文件", "继续修改文件"]


@pytest.mark.asyncio
async def test_agent_service_passes_conversation_history_to_execution_adapter() -> None:
    llm = FakeLLM(["generated"])
    service = AgentService(
        name="history-service",
        id="history-service",
        pattern="react",
        llm=cast(Any, llm),
        tools=cast(Any, [FakeTool()]),
        tool_config=None,
    )
    service.allowed_skills = []
    service.set_conversation_history(
        [
            {"role": "user", "content": "用 Python 生成随机整数"},
            {"role": "assistant", "content": "可以用 random.randint。"},
        ]
    )

    result = await service.execute_task(
        "生成一个返回给我", task_id="history-service-task"
    )

    assert result["success"] is True
    messages = llm.calls[0]["messages"]
    assert [
        _without_turn_context(message["content"])
        for message in messages
        if message["role"] == "user"
    ] == [
        "用 Python 生成随机整数",
        "生成一个返回给我",
    ]


@pytest.mark.asyncio
async def test_agent_service_passes_execution_context_to_execution_adapter() -> None:
    llm = FakeLLM(["updated"])
    service = AgentService(
        name="execution-context-service",
        id="execution-context-service",
        pattern="react",
        llm=cast(Any, llm),
        tools=cast(Any, [FakeTool()]),
        tool_config=None,
    )
    service.allowed_skills = []
    service.set_execution_context_messages(
        [
            {
                "role": "system",
                "content": "Previous tool result: output/index_zh.html exists.",
            }
        ]
    )

    result = await service.execute_task("继续修改文件", task_id="service-context-task")

    assert result["success"] is True
    system_messages = [
        message["content"]
        for message in llm.calls[0]["messages"]
        if message["role"] == "system"
    ]
    assert len(system_messages) == 1
    messages = llm.calls[0]["messages"]
    assert any(
        message["role"] == "user"
        and "Previous tool result: output/index_zh.html exists." in message["content"]
        for message in messages
    )


@pytest.mark.asyncio
async def test_agent_service_refreshes_compact_llm_on_reused_execution_adapter() -> (
    None
):
    initial_llm = FakeLLM(["initial"])
    updated_llm = FakeLLM(["updated"])
    initial_compact_llm = FakeLLM(["initial compact"])
    updated_compact_llm = FakeLLM(["updated compact"])
    adapter = ReusedExecutionAdapter(
        SimpleNamespace(
            current_task_id=None,
            tools=[],
            llm=initial_llm,
            compact_llm=initial_compact_llm,
            pattern="react",
            outbound_message_handler=None,
            conversation_history=[],
            execution_context_messages=[],
            recovered_skill_context=None,
            memory_store=None,
            allowed_skills=None,
            skills_enabled=True,
            workspace_enabled=True,
            user_interaction_enabled=True,
            execution_metadata={"old": True},
        )
    )
    service = AgentService(
        name="compact-refresh-service",
        id="compact-refresh-service",
        pattern="react",
        llm=cast(Any, initial_llm),
        compact_llm=cast(Any, initial_compact_llm),
        tools=[],
        tool_config=None,
        enable_workspace=False,
        skills_enabled=False,
        user_interaction_enabled=False,
        execution_metadata={"agent_type": "builtin"},
    )
    service._execution_adapter = cast(Any, adapter)

    service.llm = cast(Any, updated_llm)
    service.compact_llm = cast(Any, updated_compact_llm)

    result = await service._execute_agent_task(
        "continue", task_id="task-compact-refresh"
    )

    assert result["success"] is True
    assert adapter.config.current_task_id == "task-compact-refresh"
    assert adapter.config.llm is updated_llm
    assert adapter.config.compact_llm is updated_compact_llm
    assert adapter.config.skills_enabled is False
    assert adapter.config.workspace_enabled is False
    assert adapter.config.user_interaction_enabled is False
    assert adapter.config.execution_metadata == {"agent_type": "builtin"}


@pytest.mark.asyncio
async def test_execution_adapter_emits_visible_trace_events() -> None:
    tracer = RecordingTracer()
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="trace",
            pattern="react",
            llm=FakeLLM(["hello"]),
            tracer=tracer,
            skill_manager=NoSkillManager(),
        )
    )

    result = await adapter.execute(task="hi", task_id="trace-exec")

    assert result["success"] is True
    event_values = [event["event_type"].value for event in tracer.events]
    assert "task_start_message" in event_values
    assert "task_end_message" in event_values
    user_event = next(
        event
        for event in tracer.events
        if event["event_type"].value == "task_start_message"
    )
    ai_event = next(
        event
        for event in tracer.events
        if event["event_type"].value == "task_end_message"
    )
    assert user_event["data"]["message"] == "hi"
    assert ai_event["data"]["content"] == "hello"


@pytest.mark.asyncio
async def test_execution_adapter_routes_dag_to_dag() -> None:
    llm = FakeLLM(
        [
            dag_plan([{"id": "answer", "task": "Answer directly"}]),
            "dag done",
            dag_completion("dag done"),
        ]
    )
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="dag",
            pattern="dag_plan_execute",
            llm=llm,
            tools=[],
            service_id="dag-service",
            skill_manager=NoSkillManager(),
        )
    )

    result = await adapter.execute(task="Plan then answer", task_id="dag-exec")

    assert result["success"] is True
    assert result["output"] == "dag done"
    assert result["metadata"]["execution_type"] == "agent_dag"
    assert result["agent_result"]["pattern"] == "DAGPattern"


@pytest.mark.asyncio
async def test_execution_adapter_preserves_dag_failure_delivery_reason() -> None:
    class FailingStepLLM(FakeLLM):
        async def chat(self, **kwargs: Any) -> Any:
            if len(self.calls) == 2:
                self.calls.append(kwargs)
                raise RuntimeError("Step provider failed after the tool result")
            return await super().chat(**kwargs)

    llm = FailingStepLLM(
        [
            dag_plan([{"id": "work", "task": "Run a tool and verify it"}]),
            {"tool_calls": [{"id": "work", "name": "noop", "args": {}}]},
            {
                "tool_calls": [
                    {
                        "id": "delivery",
                        "function": {
                            "name": "final_answer",
                            "arguments": {
                                "answer": "Tool ran; verification unfinished.",
                                "outcome": "partial",
                            },
                        },
                    }
                ]
            },
        ]
    )
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="dag-partial",
            pattern="dag_plan_execute",
            llm=llm,
            tools=[FakeTool()],
            workspace_enabled=False,
            skills_enabled=False,
        )
    )

    result = await adapter.execute(
        task="Run a tool and verify it", task_id="dag-partial"
    )

    assert result["completion_outcome"] == "partial"
    assert result["termination_reason"] == "step_failed"
    assert result["metadata"]["termination_reason"] == "step_failed"
    assert "not a completed task" in result["output"]
    assert len(llm.calls) == 4


def test_execution_adapter_passes_dag_max_concurrency_to_pattern() -> None:
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="dag",
            pattern="dag_plan_execute",
            llm=FakeLLM([]),
            dag_max_concurrency=2,
            skill_manager=NoSkillManager(),
        )
    )

    pattern, execution_type = adapter._build_pattern()

    assert execution_type == "agent_dag"
    assert pattern.max_concurrency == 2


def test_execution_adapter_passes_react_iteration_budget_to_patterns() -> None:
    for pattern_name in ("react", "auto"):
        adapter = AgentExecutionAdapter(
            AgentExecutionConfig(
                name=pattern_name,
                pattern=pattern_name,
                llm=FakeLLM([]),
                react_max_iterations=17,
                skill_manager=NoSkillManager(),
            )
        )

        pattern, _ = adapter._build_pattern()
        react_pattern = pattern.react_pattern if pattern_name == "auto" else pattern
        assert react_pattern.max_iterations == 17


def test_execution_adapter_routes_auto_to_auto() -> None:
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="auto",
            pattern="auto",
            llm=FakeLLM([]),
            skill_manager=NoSkillManager(),
        )
    )

    pattern, execution_type = adapter._build_pattern()

    assert execution_type == "agent_auto"
    assert pattern.__class__.__name__ == "AutoPattern"
    assert pattern.dag_pattern.max_concurrency == 4


def test_execution_adapter_passes_tool_concurrency_to_react_children() -> None:
    # The tool-concurrency config must reach the ReAct child on every route that
    # can run ReAct: single_call, react, and auto. auto is the default for
    # standalone non-v1 tasks, so it is the common path for enabling the feature;
    # it previously built a default ReActPattern() and silently dropped the
    # config (regression guard).
    def build_react_child(pattern: str) -> Any:
        adapter = AgentExecutionAdapter(
            AgentExecutionConfig(
                name=pattern,
                pattern=pattern,
                llm=FakeLLM([]),
                tool_parallel_enabled=True,
                tool_max_concurrency=7,
                skill_manager=NoSkillManager(),
            )
        )
        built, _ = adapter._build_pattern()
        return built.react_pattern if pattern == "auto" else built

    for pattern in ("single_call", "react", "auto"):
        react = build_react_child(pattern)
        assert react.tool_parallel_enabled is True, pattern
        assert react.tool_max_concurrency == 7, pattern


@pytest.mark.asyncio
async def test_execution_adapter_executes_auto_final_answer() -> None:
    llm = FakeLLM(
        [auto_decision("final_answer", answer="hello", reason="Greeting only.")]
    )
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="auto",
            pattern="auto",
            llm=llm,
            service_id="auto-service",
            skill_manager=NoSkillManager(),
        )
    )

    result = await adapter.execute(task="hi", task_id="auto-final-exec")

    assert result["success"] is True
    assert result["output"] == "hello"
    assert result["metadata"]["execution_type"] == "agent_auto"
    assert result["agent_result"]["pattern"] == "AutoPattern"


@pytest.mark.asyncio
async def test_execution_adapter_executes_auto_react() -> None:
    llm = FakeLLM(
        [
            auto_decision("react", reason="Needs ReAct."),
            "react done",
        ]
    )
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="auto",
            pattern="auto",
            llm=llm,
            service_id="auto-service",
            skill_manager=NoSkillManager(),
        )
    )

    result = await adapter.execute(task="Use react", task_id="auto-react-exec")

    assert result["success"] is True
    assert result["output"] == "react done"
    assert result["metadata"]["execution_type"] == "agent_auto"
    assert result["agent_result"]["auto_decision"]["action"] == "react"


@pytest.mark.asyncio
async def test_execution_adapter_executes_auto_plan_execute() -> None:
    llm = FakeLLM(
        [
            auto_decision("plan_execute", reason="Needs DAG."),
            dag_plan([{"id": "answer", "task": "Answer directly"}]),
            "dag done",
            dag_completion("dag done"),
        ]
    )
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="auto",
            pattern="auto",
            llm=llm,
            service_id="auto-service",
            skill_manager=NoSkillManager(),
        )
    )

    result = await adapter.execute(task="Use DAG", task_id="auto-dag-exec")

    assert result["success"] is True
    assert result["output"] == "dag done"
    assert result["metadata"]["execution_type"] == "agent_auto"
    assert result["agent_result"]["auto_decision"]["action"] == "plan_execute"


@pytest.mark.asyncio
async def test_execution_adapter_exposes_pause_and_message_controls() -> None:
    llm = BlockingLLM(
        {
            "content": "",
            "tool_calls": [
                {
                    "id": "call-noop",
                    "name": "noop",
                    "args": {},
                }
            ],
        }
    )
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="control",
            pattern="react",
            llm=llm,
            tools=[FakeTool()],
            service_id="control-service",
            skill_manager=NoSkillManager(),
        )
    )

    status = adapter.start(task="Wait", task_id="control-exec")
    assert status["status"] == "running"

    handle = adapter.registry.get("control-exec")
    assert handle is not None
    assert handle.task is not None
    await llm.started.wait()
    assert adapter.pause("control-exec", reason="pause from test") is True
    assert await adapter.post_user_message(
        "control-exec",
        "Follow-up",
        request_interrupt=False,
    )
    llm.release.set()
    result = await handle.task

    final_status = adapter.get_status("control-exec")
    assert result["status"] == "interrupted"
    assert final_status is not None
    assert final_status["status"] == "interrupted"
    assert final_status["is_resumable"] is True


@pytest.mark.asyncio
@pytest.mark.parametrize("scenario", ["fresh", "replay", "conflicting_content"])
async def test_execution_adapter_post_user_message_reports_fresh_vs_replay(
    scenario: str,
) -> None:
    """This layer forwards the registry's report unmodified as a bare
    UserMessageInjectionOutcome (dropping the raw context, which nothing
    past this boundary reads): a first write is POSTED_FRESH, a repeat of
    the same turn id with the same content short-circuits as
    POSTED_REPLAY, and a repeat with different content still raises."""
    llm = BlockingLLM(
        {
            "content": "",
            "tool_calls": [
                {
                    "id": "call-noop",
                    "name": "noop",
                    "args": {},
                }
            ],
        }
    )
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="fresh-replay",
            pattern="react",
            llm=llm,
            tools=[FakeTool()],
            service_id="fresh-replay-service",
            skill_manager=NoSkillManager(),
        )
    )
    adapter.start(task="Wait", task_id="fresh-replay-exec")
    handle = adapter.registry.get("fresh-replay-exec")
    assert handle is not None
    await llm.started.wait()
    assert adapter.pause("fresh-replay-exec", reason="pause from test") is True

    first = await adapter.post_user_message(
        "fresh-replay-exec",
        "Choose B",
        turn_id="turn-adapter-fresh-replay",
        request_interrupt=False,
    )
    assert first is UserMessageInjectionOutcome.POSTED_FRESH

    if scenario == "replay":
        second = await adapter.post_user_message(
            "fresh-replay-exec",
            "Choose B",
            turn_id="turn-adapter-fresh-replay",
            request_interrupt=False,
        )
        assert second is UserMessageInjectionOutcome.POSTED_REPLAY
    elif scenario == "conflicting_content":
        with pytest.raises(ValueError, match="different user message"):
            await adapter.post_user_message(
                "fresh-replay-exec",
                "Choose C",
                turn_id="turn-adapter-fresh-replay",
                request_interrupt=False,
            )

    llm.release.set()
    await handle.task


@pytest.mark.asyncio
async def test_execution_adapter_exposes_cancel_control() -> None:
    llm = BlockingLLM()
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="cancel",
            pattern="react",
            llm=llm,
            service_id="cancel-service",
            skill_manager=NoSkillManager(),
        )
    )

    adapter.start(task="Wait", task_id="cancel-exec")

    handle = adapter.registry.get("cancel-exec")
    assert handle is not None
    assert handle.task is not None
    assert adapter.cancel("cancel-exec", reason="cancel from test") is True
    with pytest.raises(asyncio.CancelledError):
        await handle.task
    for _ in range(20):
        if adapter.get_status("cancel-exec") is None:
            break
        await asyncio.sleep(0)
    assert adapter.get_status("cancel-exec") is None


@pytest.mark.asyncio
async def test_execution_adapter_forwards_outbound_messages() -> None:
    sent_messages: list[dict[str, Any]] = []
    llm = FakeLLM(
        [
            {
                "content": "",
                "tool_calls": [
                    {
                        "id": "call-message",
                        "name": "send_message",
                        "args": {
                            "message": "Still working",
                            "message_type": "progress",
                            "expect_response": False,
                        },
                    }
                ],
            },
            "done",
        ]
    )
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="outbound",
            pattern="react",
            llm=llm,
            outbound_message_handler=sent_messages.append,
            skill_manager=NoSkillManager(),
        )
    )

    result = await adapter.execute(task="Send progress", task_id="outbound-exec")

    assert result["success"] is True
    assert result["output"] == "done"
    assert len(sent_messages) == 1
    outbound_message = sent_messages[0]
    assert outbound_message["type"] == "agent_message"
    assert outbound_message["execution_id"] == "outbound-exec"
    assert outbound_message["message"] == "Still working"
    assert outbound_message["message_type"] == "progress"
    assert outbound_message["expect_response"] is False
    assert outbound_message["visible"] is True
    assert outbound_message["step_id"] == outbound_message["metadata"]["step_id"]


@pytest.mark.asyncio
@pytest.mark.parametrize(
    ("control_name", "control_args"),
    [
        (
            "send_message",
            {
                "message": "Should stay internal",
                "message_type": "progress",
                "expect_response": False,
            },
        ),
        (
            "ask_user_question",
            {
                "message": "Should stay internal",
                "interactions": [],
            },
        ),
    ],
)
async def test_execution_adapter_rejects_outbound_control_calls_when_disabled(
    control_name: str,
    control_args: dict[str, Any],
) -> None:
    sent_messages: list[dict[str, Any]] = []
    work_tool = FakeTool()
    llm = FakeLLM(
        [
            {
                "tool_calls": [
                    {
                        "id": "call-work-before",
                        "function": {
                            "name": "noop",
                            "arguments": json.dumps({"value": "must-not-run"}),
                        },
                    },
                    {
                        "id": "call-control",
                        "function": {
                            "name": control_name,
                            "arguments": json.dumps(control_args),
                        },
                    },
                    {
                        "id": "call-work-after",
                        "function": {
                            "name": "noop",
                            "arguments": json.dumps({"value": "must-not-run"}),
                        },
                    },
                ]
            },
            {
                "tool_calls": [
                    {
                        "id": "call-final",
                        "function": {
                            "name": "final_answer",
                            "arguments": json.dumps(
                                {
                                    "response_language": "en",
                                    "answer": "done",
                                    "outcome": "completed",
                                }
                            ),
                        },
                    }
                ]
            },
        ]
    )
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="noninteractive",
            pattern="single_call",
            llm=llm,
            tools=[work_tool],
            outbound_message_handler=sent_messages.append,
            skills_enabled=False,
            user_interaction_enabled=False,
        )
    )

    result = await adapter.execute(task="Stay internal", task_id="internal-exec")

    assert result["success"] is True
    assert result["output"] == "done"
    assert sent_messages == []
    assert work_tool.calls == []
    assert [schema["function"]["name"] for schema in llm.calls[0]["tools"]] == [
        "noop",
        "final_answer",
    ]
    assert [schema["function"]["name"] for schema in llm.calls[1]["tools"]] == [
        "final_answer"
    ]
    cancelled_work_ids = {
        message.get("tool_call_id")
        for message in llm.calls[1]["messages"]
        if message.get("role") == "tool" and "cancelled" in message["content"]
    }
    assert cancelled_work_ids == {"call-work-before", "call-work-after"}
    assert "call ask_user_question" not in llm.calls[0]["messages"][0]["content"]


@pytest.mark.asyncio
async def test_disabled_control_prescan_runs_when_control_is_first(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    cancelled_batches: list[list[str]] = []
    original_cancel = ReActPattern._cancel_tool_calls

    def record_cancelled_batch(
        self: ReActPattern,
        tool_calls: list[dict[str, Any]],
        *args: Any,
        **kwargs: Any,
    ) -> None:
        cancelled_batches.append([str(call.get("id")) for call in tool_calls])
        original_cancel(self, tool_calls, *args, **kwargs)

    monkeypatch.setattr(ReActPattern, "_cancel_tool_calls", record_cancelled_batch)
    work_tool = FakeTool()
    llm = FakeLLM(
        [
            {
                "tool_calls": [
                    {
                        "id": "call-control",
                        "function": {
                            "name": "send_message",
                            "arguments": json.dumps(
                                {
                                    "message": "Do not send",
                                    "message_type": "progress",
                                    "expect_response": False,
                                }
                            ),
                        },
                    },
                    {
                        "id": "call-work-after",
                        "function": {
                            "name": "noop",
                            "arguments": json.dumps({"value": "must-not-run"}),
                        },
                    },
                ]
            },
            {
                "tool_calls": [
                    {
                        "id": "call-final",
                        "function": {
                            "name": "final_answer",
                            "arguments": json.dumps(
                                {
                                    "response_language": "en",
                                    "answer": "done",
                                    "outcome": "completed",
                                }
                            ),
                        },
                    }
                ]
            },
        ]
    )
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="noninteractive",
            pattern="single_call",
            llm=llm,
            tools=[work_tool],
            skills_enabled=False,
            user_interaction_enabled=False,
        )
    )

    result = await adapter.execute(task="Stay internal", task_id="internal-exec")

    assert result["success"] is True
    assert work_tool.calls == []
    assert cancelled_batches[0] == []
    assert ["call-work-after"] in cancelled_batches


def test_execution_adapter_uses_last_assistant_message_when_output_missing() -> None:
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="fallback",
            pattern="react",
            llm=FakeLLM([]),
            skill_manager=NoSkillManager(),
        )
    )
    context = SimpleNamespace(
        messages=[
            SimpleNamespace(role="user", content="question"),
            SimpleNamespace(role="assistant", content="answer from context"),
        ]
    )

    result = adapter._normalize_result(
        result={"success": True, "context": context},
        execution_type="agent_react",
        execution_id="fallback-exec",
    )

    assert result["output"] == "answer from context"


def _plain_react_adapter() -> AgentExecutionAdapter:
    return AgentExecutionAdapter(
        AgentExecutionConfig(
            name="provider-failure",
            pattern="react",
            llm=FakeLLM([]),
            skill_manager=NoSkillManager(),
        )
    )


def test_execution_adapter_promotes_model_error_keys_and_keeps_output_backfill() -> (
    None
):
    aggregate = "All 1 patterns failed or returned unsuccessful results."
    model_error = {
        "kind": "access_denied",
        "status_code": 403,
        "provider_code": "provider_code_4204",
        "message": "Model is decommissioned",
    }

    result = _plain_react_adapter()._normalize_result(
        result={
            "success": False,
            "error": aggregate,
            "diagnostic_error": "Provider API error (403): denied",
            "model_error": model_error,
        },
        execution_type="agent_react",
        execution_id="provider-failure-exec",
    )

    assert result["diagnostic_error"] == "Provider API error (403): denied"
    assert result["model_error"] == model_error
    assert result["output"] == aggregate
    assert result["error"] == aggregate


def test_execution_adapter_propagates_allowlisted_tool_failure_code() -> None:
    result = _plain_react_adapter()._normalize_result(
        result={
            "success": False,
            "status": "invalid_tool_protocol",
            "error": "truncated_tool_arguments",
            "failure_code": "excel_workbook_access_denied",
        },
        execution_type="agent_react",
        execution_id="client-safe-error-exec",
    )

    assert result["failure_code"] == "excel_workbook_access_denied"


@pytest.mark.parametrize("status", ["error", "max_iterations", "model_error"])
def test_execution_adapter_propagates_failure_code_on_any_failed_status(status):
    result = _plain_react_adapter()._normalize_result(
        result={
            "success": False,
            "status": status,
            "error": "failed",
            "failure_code": "excel_workbook_locked",
        },
        execution_type="agent_react",
        execution_id="failure-code-status-exec",
    )

    assert result["failure_code"] == "excel_workbook_locked"


@pytest.mark.parametrize("value", ["arbitrary", "x" * 501, 123, None])
def test_execution_adapter_rejects_unallowlisted_tool_failure_code(
    value: Any,
) -> None:
    result = _plain_react_adapter()._normalize_result(
        result={
            "success": False,
            "status": "invalid_tool_protocol",
            "error": "truncated_tool_arguments",
            "failure_code": value,
        },
        execution_type="agent_react",
        execution_id="invalid-client-safe-error-exec",
    )

    assert "failure_code" not in result


@pytest.mark.parametrize(
    ("diagnostic_error", "model_error"),
    [
        ("", "not a dict"),
        ("   ", ["kind", "access_denied"]),
        (None, None),
        (403, 403),
    ],
)
def test_execution_adapter_ignores_malformed_model_error_keys(
    diagnostic_error: Any, model_error: Any
) -> None:
    result = _plain_react_adapter()._normalize_result(
        result={
            "success": False,
            "error": "All 1 patterns failed or returned unsuccessful results.",
            "diagnostic_error": diagnostic_error,
            "model_error": model_error,
        },
        execution_type="agent_react",
        execution_id="provider-failure-malformed",
    )

    assert "diagnostic_error" not in result
    assert "model_error" not in result


def test_execution_adapter_hides_internal_error_for_interrupted_result() -> None:
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="interrupted",
            pattern="react",
            llm=FakeLLM([]),
            skill_manager=NoSkillManager(),
        )
    )

    result = adapter._normalize_result(
        result={
            "status": "interrupted",
            "success": False,
            "error": "ReActPattern interrupted.",
        },
        execution_type="agent_react",
        execution_id="interrupted-exec",
    )

    assert result["output"] == INTERRUPTED_USER_MESSAGE
    assert result["error"] == "ReActPattern interrupted."


@pytest.mark.parametrize("reason", ["max_iterations", "step_failed"])
def test_execution_adapter_preserves_completion_outcome(reason: str) -> None:
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="partial",
            pattern="react",
            llm=FakeLLM([]),
            skill_manager=NoSkillManager(),
        )
    )

    result = adapter._normalize_result(
        result={
            "status": "completed",
            "success": True,
            "output": "One item remains.",
            "completion_outcome": "partial",
            "termination_reason": reason,
        },
        execution_type="agent_react",
        execution_id="partial-exec",
    )

    assert result["completion_outcome"] == "partial"
    assert result["metadata"]["completion_outcome"] == "partial"
    assert result["termination_reason"] == reason
    assert result["metadata"]["termination_reason"] == reason


def _normalized_outcome(rating: Any) -> Any:
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(name="test", pattern="react", llm=FakeLLM([]))
    )
    result = adapter._normalize_result(
        result={"success": True, "output": "An answer.", "completion_outcome": rating},
        execution_type="agent_react",
        execution_id="rating-exec",
    )
    return result.get("completion_outcome")


def test_completion_outcomes_single_source(monkeypatch: pytest.MonkeyPatch) -> None:
    samples = [*sorted(COMPLETION_OUTCOMES), "other", None]
    passed = {rating for rating in samples if _normalized_outcome(rating) is not None}

    assert passed == COMPLETION_OUTCOMES

    # The gate reads the shared constant: a rating added to it is let through.
    monkeypatch.setattr(
        execution_adapter_module,
        "COMPLETION_OUTCOMES",
        COMPLETION_OUTCOMES | {"extra"},
    )
    assert _normalized_outcome("extra") == "extra"


@pytest.mark.parametrize("reason", [None, "provider token=secret", [], {}])
def test_execution_adapter_does_not_promote_unknown_termination_reason(
    reason: Any,
) -> None:
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(name="test", pattern="dag", llm=FakeLLM([]))
    )
    result = adapter._normalize_result(
        result={
            "success": True,
            "output": "Partial result",
            "termination_reason": reason,
        },
        execution_type="agent_dag",
        execution_id="test",
    )
    assert "termination_reason" not in result
    assert "termination_reason" not in result["metadata"]


@pytest.mark.asyncio
@pytest.mark.parametrize("remove_tool", [False, True])
async def test_execution_adapter_resume_refreshes_cached_runner_tools(
    remove_tool: bool,
) -> None:
    old_tool = FakeTool()
    new_tool = FakeTool()
    old_memory = InMemoryMemoryStore()
    new_memory = InMemoryMemoryStore()
    llm = FakeLLM(
        [
            {
                "tool_calls": [
                    {
                        "id": "call-ask",
                        "name": "ask_user_question",
                        "args": {
                            "message": "Reconnect the data source, then continue."
                        },
                    }
                ]
            }
        ]
    )
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="refresh-tools",
            pattern="react",
            llm=llm,
            tools=[old_tool],
            memory_store=old_memory,
            execution_metadata={
                MEMORY_RETRIEVAL_SCOPE_FINGERPRINT_METADATA_KEY: "scope-a"
            },
            tracer=TracerCheckpointStore(),
            skill_manager=NoSkillManager(),
        )
    )
    waiting = await adapter.execute(task="Read data", task_id="refresh-tools-exec")
    assert waiting["status"] == "waiting_for_user"
    handle = adapter.registry.get("refresh-tools-exec")
    assert handle is not None
    assert handle.runner.agent.tools == [old_tool]
    assert handle.runner.agent.memory_store is old_memory

    await adapter.post_user_message(
        "refresh-tools-exec", "Connection settings updated.", request_interrupt=False
    )
    # AgentService rebuilds its tools before resuming an existing runner.
    # The refreshed objects (including removals) must reach that runner too.
    adapter.config.tools = [] if remove_tool else [new_tool]
    adapter.config.memory_store = new_memory
    adapter.config.execution_metadata[
        MEMORY_RETRIEVAL_SCOPE_FINGERPRINT_METADATA_KEY
    ] = "scope-b"
    # Even if the model repeats the old tool name, a removed tool must not run.
    llm.responses.append(
        {"tool_calls": [{"id": "call-noop", "name": "noop", "args": {}}]}
    )
    llm.responses.append("done")

    resumed = await adapter.resume(
        "refresh-tools-exec",
        metadata={MEMORY_RETRIEVAL_SCOPE_FINGERPRINT_METADATA_KEY: "spoofed"},
    )

    assert resumed is not None
    assert resumed["status"] == "completed"
    assert old_tool.calls == []
    assert old_tool.setup_calls == ["refresh-tools-exec"]
    assert old_tool.teardown_calls == ["refresh-tools-exec"]
    assert new_tool.calls == ([] if remove_tool else [{}])
    assert handle.runner.agent.tools == adapter.config.tools
    assert handle.runner.agent.memory_store is new_memory
    resumed_context = resumed["agent_result"]["context"]
    assert (
        resumed_context.metadata[MEMORY_RETRIEVAL_SCOPE_FINGERPRINT_METADATA_KEY]
        == "scope-b"
    )
    resumed_names = {schema["function"]["name"] for schema in llm.calls[1]["tools"]}
    assert ("noop" in resumed_names) is not remove_tool


@pytest.mark.asyncio
async def test_execution_adapter_resume_restores_from_tracer_after_restart() -> None:
    tracer = TracerCheckpointStore()
    first_llm = BlockingLLM(
        {
            "content": "",
            "tool_calls": [
                {
                    "id": "call-noop",
                    "name": "noop",
                    "args": {},
                }
            ],
        }
    )
    first_adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="restart",
            pattern="react",
            llm=first_llm,
            tools=[FakeTool()],
            tracer=tracer,
            service_id="restart-service",
            skill_manager=NoSkillManager(),
        )
    )

    first_adapter.start(task="Wait for resume", task_id="restart-exec")
    first_handle = first_adapter.registry.get("restart-exec")
    assert first_handle is not None
    assert first_handle.task is not None
    await first_llm.started.wait()
    assert first_adapter.pause("restart-exec", reason="pause before restart") is True
    first_llm.release.set()

    interrupted = await first_handle.task

    assert interrupted["status"] == "interrupted"
    await first_adapter.post_user_message(
        "restart-exec",
        "Resume with concise answer.",
        request_interrupt=False,
    )

    resumed_llm = FakeLLM(["resumed done"])
    resumed_adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="restart",
            pattern="react",
            llm=resumed_llm,
            tools=[FakeTool()],
            tracer=tracer,
            service_id="restart-service",
            skill_manager=NoSkillManager(),
        )
    )

    resumed = await resumed_adapter.resume("restart-exec")

    assert resumed is not None
    assert resumed["success"] is True
    assert resumed["status"] == "completed"
    assert resumed["output"] == "resumed done"
    assert resumed["metadata"]["execution_type"] == "agent_react"
    assert resumed_adapter.get_status("restart-exec") is None
    context_messages = resumed["agent_result"]["context"].messages
    assert any(
        message.role == "user" and message.content == "Resume with concise answer."
        for message in context_messages
    )


@pytest.mark.asyncio
async def test_execution_adapter_posts_user_message_after_restart() -> None:
    tracer = TracerCheckpointStore()
    first_llm = BlockingLLM(
        {
            "content": "",
            "tool_calls": [
                {
                    "id": "call-noop",
                    "name": "noop",
                    "args": {},
                }
            ],
        }
    )
    first_adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="restart-message",
            pattern="react",
            llm=first_llm,
            tools=[FakeTool()],
            tracer=tracer,
            skill_manager=NoSkillManager(),
        )
    )

    first_adapter.start(task="Wait for message", task_id="restart-message-exec")
    first_handle = first_adapter.registry.get("restart-message-exec")
    assert first_handle is not None
    assert first_handle.task is not None
    await first_llm.started.wait()
    assert first_adapter.pause("restart-message-exec", reason="pause before restart")
    first_llm.release.set()
    interrupted = await first_handle.task
    assert interrupted["status"] == "interrupted"

    restarted_adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="restart-message",
            pattern="react",
            llm=FakeLLM(["resumed after message"]),
            tools=[FakeTool()],
            tracer=tracer,
            skill_manager=NoSkillManager(),
        )
    )

    assert await restarted_adapter.post_user_message(
        "restart-message-exec",
        "New message after process restart.",
        request_interrupt=False,
    )
    resumed = await restarted_adapter.resume("restart-message-exec")

    assert resumed is not None
    assert resumed["success"] is True
    context_messages = resumed["agent_result"]["context"].messages
    assert any(
        message.role == "user"
        and message.content == "New message after process restart."
        for message in context_messages
    )


@pytest.mark.asyncio
async def test_execution_adapter_resume_uses_handler_installed_after_post_user_message() -> (
    None
):
    """A resumed run must use the outbound handler installed on the host's
    config, even when the runner handle already existed before that
    installation happened.

    post_user_message builds and registers a runner via _build_runner()
    when no handle exists yet, copying config.outbound_message_handler at
    construction time. Every non-WebSocket resume caller (task_resume.py,
    the SaaS dispatcher) calls post_user_message before it installs its
    outbound handler, so the runner would otherwise be frozen with a None
    handler and resume() would silently drop the resumed agent's next
    message (#1328).
    """
    tracer = TracerCheckpointStore()
    first_llm = BlockingLLM(
        {
            "content": "",
            "tool_calls": [
                {
                    "id": "call-noop",
                    "name": "noop",
                    "args": {},
                }
            ],
        }
    )
    first_adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="resume-handler-ordering",
            pattern="react",
            llm=first_llm,
            tools=[FakeTool()],
            tracer=tracer,
            skill_manager=NoSkillManager(),
        )
    )

    first_adapter.start(task="Wait for message", task_id="resume-handler-ordering-exec")
    first_handle = first_adapter.registry.get("resume-handler-ordering-exec")
    assert first_handle is not None
    assert first_handle.task is not None
    await first_llm.started.wait()
    assert first_adapter.pause(
        "resume-handler-ordering-exec", reason="pause before restart"
    )
    first_llm.release.set()
    interrupted = await first_handle.task
    assert interrupted["status"] == "interrupted"

    sent_messages: list[dict[str, Any]] = []
    restarted_llm = FakeLLM(
        [
            {
                "content": "",
                "tool_calls": [
                    {
                        "id": "call-message",
                        "name": "send_message",
                        "args": {
                            "message": "Still working",
                            "message_type": "progress",
                            "expect_response": False,
                        },
                    }
                ],
            },
            "resumed done",
        ]
    )
    restarted_adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="resume-handler-ordering",
            pattern="react",
            llm=restarted_llm,
            tools=[FakeTool()],
            tracer=tracer,
            outbound_message_handler=None,
            skill_manager=NoSkillManager(),
        )
    )

    # post_user_message runs first, while config.outbound_message_handler
    # is still None, so it would build and register the runner handler-less.
    assert await restarted_adapter.post_user_message(
        "resume-handler-ordering-exec",
        "New message after process restart.",
        request_interrupt=False,
    )

    # The host installs its outbound handler only now, after the runner
    # handle already exists (mirrors execute_resume_background's ordering).
    restarted_adapter.config.outbound_message_handler = sent_messages.append

    resumed = await restarted_adapter.resume("resume-handler-ordering-exec")

    assert resumed is not None
    assert resumed["success"] is True
    assert len(sent_messages) == 1
    assert sent_messages[0]["type"] == "agent_message"
    assert sent_messages[0]["message"] == "Still working"


@pytest.mark.asyncio
async def test_set_interrupt_checker_propagates_to_prebuilt_adapter() -> None:
    # The mid-run quota checker is normally installed before a run, but
    # set_interrupt_checker must also push onto an already-built adapter — the
    # only path that updates enforcement on an already-executing task.
    service = AgentService(
        name="interrupt-service",
        id="interrupt-service",
        pattern="react",
        llm=cast(Any, FakeLLM([])),
        tools=cast(Any, []),
        tool_config=None,
    )
    service.allowed_skills = []
    service._execution_adapter = service._build_execution_adapter()

    def checker() -> None:
        return None

    service.set_interrupt_checker(checker)
    assert service._execution_adapter.config.interrupt_checker is checker
    service.set_interrupt_checker(None)
    assert service._execution_adapter.config.interrupt_checker is None


def _placeholder_warning_records(caplog: pytest.LogCaptureFixture) -> list[str]:
    return [
        record.getMessage()
        for record in caplog.records
        if "produced no output" in record.getMessage()
    ]


def test_execution_adapter_warns_when_a_successful_run_produced_no_output(
    caplog: pytest.LogCaptureFixture,
) -> None:
    """The placeholder erases the evidence, so the substitution must be logged."""

    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="silent",
            pattern="react",
            llm=FakeLLM([]),
            skill_manager=NoSkillManager(),
        )
    )

    with caplog.at_level("WARNING", logger="xagent.core.agent.execution_adapter"):
        result = adapter._normalize_result(
            result={"success": True, "status": "completed"},
            execution_type="agent_react",
            execution_id="silent-exec",
        )

    assert result["output"] == NO_OUTPUT_PLACEHOLDER
    assert len(_placeholder_warning_records(caplog)) == 1


@pytest.mark.parametrize(
    "paused",
    [
        pytest.param(
            {
                "success": False,
                "status": "waiting_for_user",
                "message": "Which region did you mean?",
                "message_type": "question",
            },
            id="send-message",
        ),
        pytest.param(
            {
                "success": False,
                "status": "waiting_for_user",
                "message": "Pick one",
                "interactions": [{"type": "select", "field": "x", "label": "X"}],
            },
            id="ask-user-question",
        ),
    ],
)
def test_execution_adapter_stays_silent_when_a_paused_run_has_no_output(
    paused: dict[str, Any], caplog: pytest.LogCaptureFixture
) -> None:
    """A pause carries only its message, so emptiness there is not a defect.

    Warning on emptiness alone would fire on the ordinary first-turn
    clarification and drown the diagnostic it exists to provide.
    """

    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(
            name="paused",
            pattern="react",
            llm=FakeLLM([]),
            skill_manager=NoSkillManager(),
        )
    )

    with caplog.at_level("WARNING", logger="xagent.core.agent.execution_adapter"):
        adapter._normalize_result(
            result=paused,
            execution_type="agent_react",
            execution_id="paused-exec",
        )

    assert _placeholder_warning_records(caplog) == []


@pytest.mark.parametrize(
    ("agent_result", "expected"),
    [
        ({"success": False, "status": "invalid_tool_protocol"}, "model_output_invalid"),
        (
            {"success": False, "interruption_reason": "llm_unavailable"},
            "llm_unavailable",
        ),
        (
            {
                "success": False,
                "error": "All 1 patterns failed",
                "interruption_reason": "persistence_failure",
            },
            "persistence_failure",
        ),
    ],
)
def test_execution_adapter_forwards_interruption_reason(
    agent_result: dict[str, Any], expected: str
) -> None:
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(name="test", pattern="react", llm=FakeLLM([]))
    )
    result = adapter._normalize_result(
        result={"output": "", **agent_result},
        execution_type="agent_react",
        execution_id="interrupted",
    )
    assert result["interruption_reason"] == expected
    assert type(result["interruption_reason"]) is str
    assert result["metadata"]["interruption_reason"] == expected


@pytest.mark.parametrize(
    "agent_result",
    [
        {"success": False, "error": "bad request"},
        {"success": False, "interruption_reason": "not_a_real_reason"},
        {"success": False, "interruption_reason": 42},
        {"success": True, "output": "done", "interruption_reason": "llm_unavailable"},
    ],
)
def test_execution_adapter_does_not_forward_invalid_interruption_reason(
    agent_result: dict[str, Any],
) -> None:
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(name="test", pattern="react", llm=FakeLLM([]))
    )
    result = adapter._normalize_result(
        result=agent_result,
        execution_type="agent_react",
        execution_id="not-interrupted",
    )
    assert "interruption_reason" not in result
    assert "interruption_reason" not in result["metadata"]


@pytest.mark.parametrize(
    "agent_result",
    [
        {"success": True, "output": "ok", "finish_reason": 123},
        {"success": True, "output": "ok", "finish_reason": "  "},
        {"success": False, "error": "x", "empty_final_answer": "true"},
        {"success": False, "error": "x", "empty_final_answer": 1},
        {"success": True, "output": "ok", "metadata": {"first_answer_delta_at": 5}},
        {"success": True, "output": "ok", "metadata": "not a dict"},
        {"success": True, "output": "ok"},
    ],
)
def test_normalize_result_lifts_only_well_typed_classification(
    agent_result: dict[str, Any],
) -> None:
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(name="test", pattern="react", llm=FakeLLM([]))
    )

    normalized = adapter._normalize_result(
        result=agent_result, execution_type="agent_react", execution_id="1"
    )

    for key in ("finish_reason", "empty_final_answer", "first_answer_delta_at"):
        assert key not in normalized


@pytest.mark.parametrize(
    ("agent_result", "expected"),
    [
        ({"success": True, "output": ""}, True),
        ({"success": True}, True),
        ({"success": True, "output": "ok"}, False),
    ],
)
def test_normalize_result_flags_a_missing_output(
    agent_result: dict[str, Any], expected: bool
) -> None:
    adapter = AgentExecutionAdapter(
        AgentExecutionConfig(name="test", pattern="react", llm=FakeLLM([]))
    )

    normalized = adapter._normalize_result(
        result=agent_result, execution_type="agent_react", execution_id="1"
    )

    assert normalized.get("output_missing", False) is expected
    if expected:
        assert normalized["output"] == NO_OUTPUT_PLACEHOLDER