"""最小调试工具：把输入原样回显。

它的价值不是业务能力，而是运行时验证：
当你只想确认 tool loop 是否能走通时，`echo` 是最便宜、最确定的测试工具。
"""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any


ECHO_TOOL_DESCRIPTION = "Echo the provided text back to the agent. Useful for verifying tool calling."

ECHO_TOOL_PARAMETERS: dict[str, Any] = {
    "type": "object",
    "properties": {
        "text": {
            "type": "string",
            "description": "The text to echo back.",
        }
    },
    "required": ["text"],
}


def echo_tool(*, text: str) -> str:
    return text


@dataclass(slots=True)
class EchoTool:
    """面向 runtime 的最小内建工具。"""

    name: str = "echo"
    description: str = ECHO_TOOL_DESCRIPTION
    toolset: str = "debug"
    always_available: bool = False
    parameters: dict[str, Any] = field(default_factory=lambda: dict(ECHO_TOOL_PARAMETERS))

    async def execute(self, **kwargs: Any) -> str:
        text = kwargs.get("text")
        if not isinstance(text, str):
            raise ValueError("echo tool requires a string field 'text'")
        return echo_tool(text=text)