"""TaskOutcome dataclass aggregating command results for a task.

Provides a structured summary separate from individual CommandResult objects
without reintroducing legacy TaskResult naming. Users can opt into this
via TaskRunner.execute_with_summary() while existing execute() return type
remains a list of CommandResult for backward compatibility.
"""

from __future__ import annotations

from dataclasses import dataclass
from datetime import datetime

from hil_testbench.run.command_result import CommandResult


@dataclass(slots=True)
class TaskOutcome:
    """Aggregate outcome for a single task execution.

    Attributes:
        task_name: Logical task name.
        command_results: List of per-command results.
        success: True if all commands succeeded.
        total_commands: Count of commands executed.
        failed_commands: Count of commands failed.
        start_time: Wall-clock start timestamp.
        end_time: Wall-clock end timestamp.
        duration_seconds: Elapsed time in seconds.
        correlation_id: Runner correlation ID for tracing.
        log_directory: Directory containing JSONL/CSV/log files.
    """

    task_name: str
    command_results: list[CommandResult]
    success: bool
    total_commands: int
    failed_commands: int
    start_time: datetime
    end_time: datetime
    duration_seconds: float
    correlation_id: str | None
    log_directory: str | None

    def failed(self) -> bool:
        """Return True if any command failed."""
        return not self.success

    def commands_by_status(self, success: bool = True) -> list[CommandResult]:
        """Filter command results by success state."""
        return [r for r in self.command_results if r.success is success]
