"""
Type definitions for Kivot Agents.
"""

from dataclasses import dataclass
from typing import Any, Dict, List, Optional


@dataclass
class AgentResult:
    """
    Result returned by KivotRunner.run().

    Compatible with official OpenAI Agents SDK result structure.
    """

    final_output: str
    """Final text output from the agent."""

    messages: List[Dict[str, Any]]
    """Complete conversation history including system, user, assistant, and tool messages."""

    usage: Optional[Dict[str, Any]] = None
    """Token usage statistics.

    In standalone mode: {input_tokens, output_tokens, total_tokens, cost_usd}.
    In durable mode: {prompt_tokens, completion_tokens, total_tokens} (from Go activity).
    """

    def __str__(self) -> str:
        return self.final_output
