"""通用 Agent 定义。

定义保持纯数据；模型调用、工具执行与持久化仍由既有运行时负责。
"""

from __future__ import annotations

from dataclasses import dataclass, field


@dataclass(frozen=True)
class ExecutionPolicy:
    """一次 Agent 运行的硬性边界。"""

    max_iterations: int = 8

    def __post_init__(self) -> None:
        if self.max_iterations < 1:
            raise ValueError("max_iterations 必须 >= 1")


@dataclass(frozen=True)
class ToolPolicy:
    """本次运行允许暴露给模型的工具名称。空值表示沿用运行时默认工具集。"""

    allowed_tools: tuple[str, ...] = ()


@dataclass(frozen=True)
class AgentDefinition:
    """可组合的 Agent 身份、提示、技能与执行边界。"""

    name: str
    system_prompt: str
    model_hint: str | None = None
    skill_refs: tuple[str, ...] = ()
    tool_policy: ToolPolicy = field(default_factory=ToolPolicy)
    execution_policy: ExecutionPolicy = field(default_factory=ExecutionPolicy)


DEFAULT_CHAT_AGENT = AgentDefinition(
    name="镜师",
    system_prompt="你是魂镜当前默认人物。请使用中文，保持诚实、克制、清晰。",
)