Agent executor

class ExecutionStatus(str, Enum):  # noqa: UP042  # StrEnum would change str() of public members
    """Status of agent execution.

    This enum represents the outcome status of an agent execution,
    used by ExecutionResult to indicate how the execution completed.
    Members are ``str`` values (``"success"``, ``"failed"``, ``"timeout"``),
    so they compare equal to those strings.

    Attributes:
        SUCCESS (str): Agent completed execution normally with valid output.
        FAILED (str): Agent encountered an error during execution.
        TIMEOUT (str): Agent execution exceeded configured timeout.

    Examples:
        Checking execution status:

        ```python
        from gepa_adk.ports.agent_executor import ExecutionStatus

        if result.status == ExecutionStatus.SUCCESS:
            print(f"Output: {result.extracted_value}")
        elif result.status == ExecutionStatus.TIMEOUT:
            print(f"Timed out after {result.execution_time_seconds}s")
        elif result.status == ExecutionStatus.FAILED:
            print(f"Error: {result.error_message}")
        ```

    Notes:
        All status values reflect execution outcome, not output quality.
        A successful execution may still produce low-quality output
        that fails scoring.
    """

    SUCCESS = "success"
    FAILED = "failed"
    TIMEOUT = "timeout"

@dataclass
class ExecutionResult:
    """Result of an agent execution.

    Provides consistent return type across all agent types (generator, critic,
    reflection) with status, output, timing, and debugging information.

    Attributes:
        status (ExecutionStatus): Outcome status of the execution.
        session_id (str): ADK session identifier used for this execution.
        extracted_value (str | None): Output text extracted from agent response. None if
            agent produced no output or execution failed.
        error_message (str | None): Error details if status is FAILED or TIMEOUT. None
            for successful executions.
        execution_time_seconds (float): Duration of execution in seconds.
        captured_events (list[Any] | None): ADK events captured during execution for debugging
            and trajectory analysis. None if event capture disabled.

    Examples:
        Successful execution:

        ```python
        result = ExecutionResult(
            status=ExecutionStatus.SUCCESS,
            session_id="sess_123",
            extracted_value="Hello, world!",
            execution_time_seconds=1.5,
        )
        ```

        Failed execution:

        ```python
        result = ExecutionResult(
            status=ExecutionStatus.FAILED,
            session_id="sess_456",
            error_message="Model rate limit exceeded",
            execution_time_seconds=0.2,
        )
        ```

    Notes:
        All captured_events contain raw ADK Event objects for debugging
        and trajectory recording. Events are captured even on timeout
        or failure.
    """

    status: ExecutionStatus
    session_id: str
    extracted_value: str | None = None
    error_message: str | None = None
    execution_time_seconds: float = 0.0
    captured_events: list[Any] | None = field(default=None)

@dataclass(frozen=True, slots=True)
class RetryPolicy:
    """Retry policy for transient session-service errors.

    An executor that honours this policy retries an agent run whose session
    service raised a transient error, such as sqlite's ``database is
    locked``, sleeping ``backoff_seconds`` before the second attempt and
    multiplying the sleep by ``backoff_multiplier`` before each later one.

    Attributes:
        max_attempts (int): Total attempts including the first; ``1``
            disables the retry. Defaults to 3.
        backoff_seconds (float): Sleep before the second attempt, in
            seconds. Defaults to 0.5.
        backoff_multiplier (float): Factor applied to the sleep after each
            retry. Defaults to 2.0.

    Examples:
        The default policy tries three times, sleeping 0.5 s then 1.0 s:

        ```python
        from gepa_adk.ports.agent_executor import RetryPolicy

        policy = RetryPolicy()
        assert policy.max_attempts == 3
        ```

        A stricter policy for a heavily loaded disk:

        ```python
        policy = RetryPolicy(max_attempts=5, backoff_seconds=1.0)
        executor = AgentExecutor(session_service=service, retry_policy=policy)
        ```

    Notes:
        The policy is a frozen value object. Validation runs in
        ``__post_init__`` and raises ``ValueError`` naming the bad field.
    """

    max_attempts: int = 3
    backoff_seconds: float = 0.5
    backoff_multiplier: float = 2.0

    def __post_init__(self) -> None:
        """Validate the policy fields.

        Raises:
            ValueError: If ``max_attempts`` is not an int of at least 1,
                ``backoff_seconds`` is not a number of at least 0, or
                ``backoff_multiplier`` is not a number of at least 1.
        """
        if not _is_int(self.max_attempts) or self.max_attempts < 1:
            raise ValueError(
                f"max_attempts must be an int >= 1, got {self.max_attempts!r}"
            )
        if not _is_number(self.backoff_seconds) or self.backoff_seconds < 0:
            raise ValueError(
                f"backoff_seconds must be a number >= 0, got {self.backoff_seconds!r}"
            )
        if not _is_number(self.backoff_multiplier) or self.backoff_multiplier < 1:
            raise ValueError(
                "backoff_multiplier must be a number >= 1, "
                f"got {self.backoff_multiplier!r}"
            )

@runtime_checkable
class AgentExecutorProtocol(Protocol):
    """Protocol for unified agent execution.

    Defines the interface for executing any ADK agent type (LlmAgent,
    workflow agents) with consistent behavior, session management, and
    result handling.

    This protocol enables:
    - Feature parity across generator, critic, and reflection agents
    - Dependency injection for testing
    - Single point of change for new ADK features

    Examples:
        Using an executor:

        ```python
        executor: AgentExecutorProtocol = AgentExecutor()

        result = await executor.execute_agent(
            agent=my_agent,
            input_text="Hello",
            timeout_seconds=60,
        )

        if result.status == ExecutionStatus.SUCCESS:
            print(result.extracted_value)
        ```

        With instruction override (for evolution):

        ```python
        result = await executor.execute_agent(
            agent=my_agent,
            input_text="Hello",
            instruction_override="You are a helpful assistant.",
        )
        ```

    See Also:
        - [`ExecutionResult`][gepa_adk.ports.agent_executor.ExecutionResult]:
            Return type for execute_agent.
        - [`ExecutionStatus`][gepa_adk.ports.agent_executor.ExecutionStatus]:
            Status enum for execution outcomes.

    Notes:
        All implementations should validate that the agent parameter is a
        valid ADK LlmAgent. The Any type is used here to avoid coupling
        the ports layer to ADK types.
    """

    async def execute_agent(  # noqa: PLR0913  # protocol signature shared by every executor
        self,
        agent: Any,
        input_text: str,
        *,
        input_content: Any | None = None,
        instruction_override: str | None = None,
        output_schema_override: Any | None = None,
        session_state: dict[str, Any] | None = None,
        existing_session_id: str | None = None,
        timeout_seconds: int = 300,
    ) -> ExecutionResult:
        """Execute an agent and return structured result.

        Runs the specified agent with the given input, optionally applying
        instruction or schema overrides for evolution scenarios. Manages
        session lifecycle and captures execution events.

        Args:
            agent (Any): ADK LlmAgent to execute. The agent's tools, output_key,
                and other ADK features are preserved during execution.
            input_text (str): User message to send to the agent. Used as fallback
                if input_content is not provided.
            input_content (Any | None): Optional ADK Content object for multimodal input
                (e.g., video parts). If provided, takes precedence over input_text.
            instruction_override (str | None): If provided, replaces the agent's instruction
                for this execution only. Original agent is not modified.
            output_schema_override (Any | None): If provided, replaces the agent's output
                schema for this execution only (type[BaseModel]). Used for schema evolution.
            session_state (dict[str, Any] | None): Initial state to inject into the
                session. Used for template variable substitution (e.g.,
                {component_text}).
            existing_session_id (str | None): If provided, reuses an existing session instead
                of creating a new one. Useful for critic accessing generator state.
            timeout_seconds (int): Maximum execution time in seconds. Defaults to 300.
                Execution terminates with TIMEOUT status if exceeded.

        Returns:
            ExecutionResult with status, output, and debugging information.

        Raises:
            SessionNotFoundError: If existing_session_id is provided but session
                does not exist.

        Examples:
            Basic execution:

            ```python
            result = await executor.execute_agent(
                agent=greeter,
                input_text="Hello!",
            )
            print(result.extracted_value)  # "Hello! How can I help?"
            ```

            With session state for reflection:

            ```python
            result = await executor.execute_agent(
                agent=reflector,
                input_text="Improve the instruction",
                session_state={
                    "component_text": "Be helpful.",
                    "trials": '[{"score": 0.5}]',
                },
            )
            ```

            Session sharing between agents:

            ```python
            # Generator creates session
            gen_result = await executor.execute_agent(
                agent=generator,
                input_text="Write a story.",
            )

            # Critic reuses generator's session
            critic_result = await executor.execute_agent(
                agent=critic,
                input_text=f"Evaluate: {gen_result.extracted_value}",
                existing_session_id=gen_result.session_id,
            )
            ```

        Notes:
            The agent parameter is typed as Any to avoid coupling to ADK types
            in the ports layer. Implementations should validate that the agent
            is a valid LlmAgent.
        """
        ...