feat(run-tasks-integration): add run tasks integration callback support

[KshitijaChoudhari]

Description

This PR adds complete support for Run Tasks Integration callbacks in python-tfe, enabling users to build webhook servers that receive run task requests from Terraform Cloud/Enterprise and send results back. This feature allows developers to create custom run task integrations that can validate, analyze, or modify Terraform runs at different lifecycle stages.

Motivation and Context

Run Tasks Integration is a critical feature in Terraform Cloud/Enterprise that allows organizations to:

• Build custom validation services that integrate into the Terraform workflow
• Receive webhook notifications when run tasks are triggered
• Send back pass/fail results with detailed outcomes and tags
• Integrate external tools for security scanning, policy enforcement, cost estimation, or compliance checking

This implementation brings python-tfe to feature parity with go-tfe's run tasks integration capabilities, enabling Python users to programmatically handle run task webhooks and callbacks.

Related go-tfe implementation: https://github.com/hashicorp/go-tfe/blob/main/run_task.go

Type of Change

• New feature (non-breaking change which adds functionality)

Changes Made

1. Model Layer

• Added run_task_request.py: Complete Pydantic model for parsing TFC/TFE webhook payloads with 20+ fields including access_token, run_id, workspace details, stage, callback_url, capabilities, etc.
• Added callback models: TaskResultCallbackOptions, TaskResultOutcome, TaskResultStatus, TaskResultTag models for constructing callback responses

2. Resource Layer

• Added run_tasks_integration.py: RunTasksIntegration service with callback() method to send task results back to Terraform Cloud/Enterprise
• Supports pass/failed/running status
• Supports outcomes with detailed error/warning information
• Supports custom tags for result metadata

3. Client Integration

• Updated client.py: Added run_tasks_integration property for easy access to the service

4. Testing

• Added test_run_tasks_integration.py: 15 comprehensive unit tests covering:
  • RunTaskRequest parsing and validation
  • Callback options serialization
  • Status, outcome, and tag models
  • Error handling for invalid data

5. Example Implementation

• Added run_tasks_integration.py: Complete Flask server example demonstrating:
  • Webhook endpoint for receiving run task requests
  • Request parsing and validation
  • Business logic implementation
  • Callback result sending
  • Health check endpoint
  • Optional Flask dependency with clear error messaging

Implementation Details

Architecture

• Webhook-First Design: RunTaskRequest model parses incoming TFC/TFE webhooks
• Type-Safe Callbacks: Pydantic models ensure correct data structure for API responses
• Flexible Framework: Core implementation has no Flask dependency; example shows optional Flask integration
• Consistent Patterns: Follows existing pytfe resource patterns for API communication

Key Features

• Full Request Parsing: All 20+ fields from TFC/TFE webhook payloads supported
• Rich Outcomes: Support for multiple outcomes with descriptions, URLs, and custom body content
• Tag Support: Optional tags for categorizing and filtering results
• Status Control: Pass, fail, or running status for long-running operations

Key Files Changed

• run_task_request.py: New - 80 lines (RunTaskRequest model)
• run_tasks_integration.py: New - 120 lines (callback service)
• run_tasks_integration.py: New - 110 lines (Flask example)
• test_run_tasks_integration.py: New - 320 lines (15 unit tests)
• client.py: Modified - Added run_tasks_integration property
• __init__.py: Modified - Export RunTaskRequest model

Testing

Unit Tests

All 15 tests passing:

• RunTaskRequest parsing with all fields
• Partial request parsing
• Callback options validation
• Status enum validation
• Outcome model creation
• Tag model creation
• Invalid data handling

Code Quality

• No go-tfe mentions in code
• No emoji usage
• Consistent import patterns matching other examples
• Type hints throughout

Manual Testing

• Tested RunTaskRequest parsing with real TFC webhook data
• Tested callback options creation programmatically
• Flask server runs successfully on port 5000
• Verified all model serialization/deserialization

Breaking Changes

• No breaking changes
• ℹ️ New feature addition only

Dependencies

• No new core dependencies added
• Flask is optional for the example only (with try/except and clear error message)
• Uses existing Pydantic v2.12+ models
• Uses existing HTTPTransport infrastructure

Backwards Compatibility

• Fully backwards compatible
• New feature addition only
• No changes to existing APIs

Self-Review Checklist

Code Quality

• Follows project style guide and conventions
• No commented-out code or debug statements
• No hardcoded values
• Proper error handling
• No code duplication
• Functions are small and single-purpose
• Descriptive variable/function names

Documentation

• All functions have complete docstrings
• Complex logic has inline comments
• Example includes comprehensive usage instructions
• Flask dependency clearly marked as optional

Testing

• All new code has unit tests (15 tests)
• Edge cases tested
• All tests pass locally (15/15)
• Manual testing completed

Git Hygiene

• Commits are logical and atomic
• Branch based on next-0.1.2
• No conflicts with target branch