"""通用 Agent 的任务与计划纯领域契约。"""

from __future__ import annotations

from dataclasses import dataclass
from typing import Literal

TaskStatus = Literal["queued", "running", "waiting_confirmation", "completed", "failed", "cancelled"]
PlanStatus = Literal["draft", "approved", "running", "completed", "failed"]
StepStatus = Literal["pending", "running", "completed", "failed", "skipped"]


@dataclass(frozen=True)
class PlanStep:
    """可追踪的 Agent 计划步骤。"""

    id: str
    title: str
    description: str = ""
    tool: str | None = None
    risk_level: str = "L2"
    status: StepStatus = "pending"
    result_summary: str | None = None


@dataclass(frozen=True)
class Plan:
    """任务的显式执行计划。"""

    steps: tuple[PlanStep, ...]
    assumptions: tuple[str, ...] = ()
    risks: tuple[str, ...] = ()
    status: PlanStatus = "draft"


@dataclass(frozen=True)
class AgentTask:
    """一次 Agent 执行的目标与可选计划。"""

    id: str
    objective: str
    agent_name: str
    run_id: str | None = None
    status: TaskStatus = "queued"
    plan: Plan | None = None
    constraints: tuple[str, ...] = ()