Add task_result and task_stages models matching go-tfe

- Add task_result.py with TaskResult, TaskResultStatus, TaskEnforcementLevel models
- Add task_stages.py with TaskStage, Stage, TaskStageStatus, Actions, Permissions models
- Update run_task.py to import Stage and TaskEnforcementLevel from new modules (remove duplicates)
- Update run_tasks_integration.py to use TaskResultStatus enum from task_result
- Update run_task_request.py to add model_config for proper serialization
- Export all new models in __init__.py
- All 22 unit tests passing
- Matches go-tfe implementation structure

Author: KshitijaChoudhari

src/pytfe/models/__init__.py

@@ -253,13 +253,28 @@
     RunTaskListOptions,
     RunTaskReadOptions,
     RunTaskUpdateOptions,
-    Stage,
-    TaskEnforcementLevel,
 )
 from .run_task_request import (
     RunTaskRequest,
     RunTaskRequestCapabilities,
 )
+from .task_result import (
+    TaskEnforcementLevel,
+    TaskResult,
+    TaskResultStatus,
+    TaskResultStatusTimestamps,
+)
+from .task_stages import (
+    Actions,
+    Permissions,
+    Stage,
+    TaskStage,
+    TaskStageListOptions,
+    TaskStageOverrideOptions,
+    TaskStageReadOptions,
+    TaskStageStatus,
+    TaskStageStatusTimestamps,
+)
 from .run_trigger import (
     RunTrigger,
     RunTriggerCreateOptions,

src/pytfe/models/run_task.py

@@ -7,6 +7,8 @@
 from ..models.common import Pagination
 from .agent import AgentPool
 from .organization import Organization
+from .task_result import TaskEnforcementLevel
+from .task_stages import Stage
 from .workspace_run_task import WorkspaceRunTask
 
 
@@ -37,18 +39,6 @@ class GlobalRunTaskOptions(BaseModel):
     enforcement_level: TaskEnforcementLevel | None = None
 
 
-class Stage(str, Enum):
-    PRE_PLAN = "pre-plan"
-    POST_PLAN = "post-plan"
-    PRE_APPLY = "pre-apply"
-    POST_APPLY = "post-apply"
-
-
-class TaskEnforcementLevel(str, Enum):
-    ADVISORY = "advisory"
-    MANDATORY = "mandatory"
-
-
 class RunTaskIncludeOptions(str, Enum):
     RUN_TASK_WORKSPACE_TASKS = "workspace_tasks"
     RUN_TASK_WORKSPACE = "workspace_tasks.workspace"

src/pytfe/models/run_task_request.py

@@ -18,6 +18,8 @@ class RunTaskRequestCapabilities(BaseModel):
         default=False,
         description="Whether the run task server supports outcomes"
     )
+    
+    model_config = ConfigDict(populate_by_name=True)
 
 
 class RunTaskRequest(BaseModel):

src/pytfe/models/task_result.py

@@ -0,0 +1,74 @@
+"""Task Result models for python-tfe.
+
+This module contains models related to task results in Terraform Cloud/Enterprise.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, ConfigDict, Field
+
+if TYPE_CHECKING:
+    from .task_stages import TaskStage
+
+
+class TaskResultStatus(str, Enum):
+    """Task result status enum."""
+    
+    PASSED = "passed"
+    FAILED = "failed"
+    PENDING = "pending"
+    RUNNING = "running"
+    UNREACHABLE = "unreachable"
+    ERRORED = "errored"
+
+
+class TaskEnforcementLevel(str, Enum):
+    """Task enforcement level enum."""
+    
+    ADVISORY = "advisory"
+    MANDATORY = "mandatory"
+
+
+class TaskResultStatusTimestamps(BaseModel):
+    """Timestamps recorded for a task result."""
+    
+    errored_at: datetime | None = Field(default=None, alias="errored-at")
+    running_at: datetime | None = Field(default=None, alias="running-at")
+    canceled_at: datetime | None = Field(default=None, alias="canceled-at")
+    failed_at: datetime | None = Field(default=None, alias="failed-at")
+    passed_at: datetime | None = Field(default=None, alias="passed-at")
+    
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class TaskResult(BaseModel):
+    """Represents a HCP Terraform or Terraform Enterprise run task result.
+    
+    API Documentation:
+        https://developer.hashicorp.com/terraform/cloud-docs/api-docs/task-results
+    """
+    
+    id: str
+    status: TaskResultStatus
+    message: str
+    status_timestamps: TaskResultStatusTimestamps = Field(alias="status-timestamps")
+    url: str
+    created_at: datetime = Field(alias="created-at")
+    updated_at: datetime = Field(alias="updated-at")
+    task_id: str = Field(alias="task-id")
+    task_name: str = Field(alias="task-name")
+    task_url: str = Field(alias="task-url")
+    workspace_task_id: str = Field(alias="workspace-task-id")
+    workspace_task_enforcement_level: TaskEnforcementLevel = Field(
+        alias="workspace-task-enforcement-level"
+    )
+    agent_pool_id: str | None = Field(default=None, alias="agent-pool-id")
+    
+    # Relationships
+    task_stage: TaskStage | None = Field(default=None, alias="task-stage")
+    
+    model_config = ConfigDict(populate_by_name=True)

src/pytfe/models/task_stages.py

@@ -0,0 +1,119 @@
+"""Task Stage models for python-tfe.
+
+This module contains models related to task stages in Terraform Cloud/Enterprise.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, ConfigDict, Field
+
+if TYPE_CHECKING:
+    from .policy_evaluation import PolicyEvaluation
+    from .run import Run
+    from .task_result import TaskResult
+
+
+class Stage(str, Enum):
+    """Enum representing possible run stages for run tasks."""
+    
+    PRE_PLAN = "pre-plan"
+    POST_PLAN = "post-plan"
+    PRE_APPLY = "pre-apply"
+    POST_APPLY = "post-apply"
+
+
+class TaskStageStatus(str, Enum):
+    """Enum representing all possible statuses for a task stage."""
+    
+    PENDING = "pending"
+    RUNNING = "running"
+    PASSED = "passed"
+    FAILED = "failed"
+    AWAITING_OVERRIDE = "awaiting_override"
+    CANCELED = "canceled"
+    ERRORED = "errored"
+    UNREACHABLE = "unreachable"
+
+
+class Permissions(BaseModel):
+    """Permission types for overriding a task stage."""
+    
+    can_override_policy: bool | None = Field(default=None, alias="can-override-policy")
+    can_override_tasks: bool | None = Field(default=None, alias="can-override-tasks")
+    can_override: bool | None = Field(default=None, alias="can-override")
+    
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class Actions(BaseModel):
+    """Task stage actions."""
+    
+    is_overridable: bool | None = Field(default=None, alias="is-overridable")
+    
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class TaskStageStatusTimestamps(BaseModel):
+    """Timestamps recorded for a task stage."""
+    
+    errored_at: datetime | None = Field(default=None, alias="errored-at")
+    running_at: datetime | None = Field(default=None, alias="running-at")
+    canceled_at: datetime | None = Field(default=None, alias="canceled-at")
+    failed_at: datetime | None = Field(default=None, alias="failed-at")
+    passed_at: datetime | None = Field(default=None, alias="passed-at")
+    
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class TaskStage(BaseModel):
+    """Represents a HCP Terraform or Terraform Enterprise run's task stage.
+    
+    Task stages are where run tasks can occur during a run lifecycle.
+    
+    API Documentation:
+        https://developer.hashicorp.com/terraform/cloud-docs/api-docs/task-stages
+    """
+    
+    id: str
+    stage: Stage
+    status: TaskStageStatus
+    status_timestamps: TaskStageStatusTimestamps = Field(alias="status-timestamps")
+    created_at: datetime = Field(alias="created-at")
+    updated_at: datetime = Field(alias="updated-at")
+    permissions: Permissions | None = None
+    actions: Actions | None = None
+    
+    # Relationships
+    run: Run | None = None
+    task_results: list[TaskResult] = Field(default_factory=list, alias="task-results")
+    policy_evaluations: list[PolicyEvaluation] = Field(
+        default_factory=list, 
+        alias="policy-evaluations"
+    )
+    
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class TaskStageOverrideOptions(BaseModel):
+    """Options for overriding a task stage."""
+    
+    comment: str | None = None
+
+
+class TaskStageReadOptions(BaseModel):
+    """Options for reading a task stage."""
+    
+    include: list[str] | None = None
+
+
+class TaskStageListOptions(BaseModel):
+    """Options for listing task stages."""
+    
+    page_number: int | None = Field(default=None, alias="page[number]")
+    page_size: int | None = Field(default=None, alias="page[size]")
+    
+    model_config = ConfigDict(populate_by_name=True)

src/pytfe/resources/run_tasks_integration.py

@@ -9,26 +9,29 @@
 from typing import Any
 
 from ..errors import TFEError
+from ..models.task_result import TaskResultStatus
 from ._base import _Service
 
 
-class TaskResultStatus:
-    """Task result status enum."""
-    
-    PASSED = "passed"
-    FAILED = "failed"
-    RUNNING = "running"
-
-
 class TaskResultTag:
-    """Tag to enrich outcomes display in TFC/TFE."""
+    """Tag to enrich outcomes display in TFC/TFE.
+    
+    API Documentation:
+        https://developer.hashicorp.com/terraform/enterprise/api-docs/run-tasks/run-tasks-integration#severity-and-status-tags
+    """
 
     def __init__(self, label: str, level: str | None = None):
+        """Initialize a task result tag.
+        
+        Args:
+            label: The label for the tag
+            level: Optional severity level (error, warning, info)
+        """
         self.label = label
         self.level = level
 
     def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary."""
+        """Convert to dictionary for JSON serialization."""
         result = {"label": self.label}
         if self.level:
             result["level"] = self.level
@@ -50,14 +53,23 @@ def __init__(
         url: str | None = None,
         tags: dict[str, list[TaskResultTag]] | None = None,
     ):
+        """Initialize a task result outcome.
+        
+        Args:
+            outcome_id: Unique identifier for the outcome
+            description: Brief description of the outcome
+            body: Detailed body content (supports markdown)
+            url: URL to view more details
+            tags: Dictionary of tag categories to lists of tags
+        """
         self.outcome_id = outcome_id
         self.description = description
         self.body = body
         self.url = url
         self.tags = tags or {}
 
     def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for JSON serialization."""
+        """Convert to dictionary for JSON:API serialization."""
         result: dict[str, Any] = {"type": "task-result-outcomes", "attributes": {}}
 
         if self.outcome_id:
@@ -105,8 +117,16 @@ def __init__(
         self.outcomes = outcomes or []
 
     def validate(self) -> None:
-        """Validate the callback options."""
-        valid_statuses = [TaskResultStatus.PASSED, TaskResultStatus.FAILED, TaskResultStatus.RUNNING]
+        """Validate the callback options.
+        
+        Only passed, failed, and running statuses are allowed for callbacks.
+        pending and errored are not valid callback statuses per TFC/TFE API.
+        """
+        valid_statuses = [
+            TaskResultStatus.PASSED.value,
+            TaskResultStatus.FAILED.value,
+            TaskResultStatus.RUNNING.value
+        ]
         if self.status not in valid_statuses:
             raise TFEError(
                 f"Invalid task result status: {self.status}. "