attune/work-summary/sessions/2026-01-27-manual-execution-feature.md

Manual Execution Feature Implementation

Date: 2026-01-27
Status: ✅ Complete
Feature: Direct action execution via API without triggers/rules

Overview

Implemented the ability to execute actions directly via the API without requiring a trigger, sensor, or rule. This enables manual testing, ad-hoc task execution, and API-driven workflows.

Problem Statement

Previously, the only way to execute an action in Attune was through the event-driven automation flow:

Sensor → Trigger → Event → Rule → Enforcement → Execution

There was no way to directly execute an action with parameters via the API. The E2E test test_execute_action_directly was skipped with the reason: "Manual execution API not yet implemented."

Solution

API Endpoint

Implemented POST /api/v1/executions/execute endpoint:

Request:

{
  "action_ref": "slack.post_message",
  "parameters": {
    "channel": "#alerts",
    "message": "Manual test"
  }
}

Response (201 Created):

{
  "data": {
    "id": 123,
    "action_ref": "slack.post_message",
    "status": "Requested",
    "config": {
      "channel": "#alerts",
      "message": "Manual test"
    },
    "parent": null,
    "enforcement": null,
    "created": "2026-01-27T17:00:00Z",
    "updated": "2026-01-27T17:00:00Z"
  }
}

Implementation Details

Files Modified:

1. crates/api/src/dto/execution.rs - Added CreateExecutionRequest DTO

   pub struct CreateExecutionRequest {
       pub action_ref: String,
       pub parameters: Option<JsonValue>,
   }
   

2. crates/api/src/routes/executions.rs - Added create_execution handler

   • Validates action exists using ActionRepository::find_by_ref()
   • Creates execution with ExecutionRepository::create()
   • Sets status to ExecutionStatus::Requested
   • Publishes ExecutionRequestedPayload to RabbitMQ
   • Returns 201 Created with execution details

3. crates/api/src/dto/mod.rs - Exported new DTO

4. tests/test_e2e_basic.py - Enabled and implemented test

   • Removed @pytest.mark.skip decorator
   • Implemented full test: create action → execute → verify
   • Fixed test fixture to handle pack already exists (409 Conflict)

Flow

1. API receives request → Validates action exists
2. Create execution record → Status: Requested, no enforcement/parent
3. Publish to queue → ExecutionRequestedPayload on attune.executions exchange
4. Return response → 201 Created with execution ID and details
5. Executor picks up → (existing executor service handles the queued execution)

Key Technical Decisions

1. Status = Requested - Uses existing enum variant for queued executions
2. No enforcement/parent - Manual executions are top-level, not tied to rules
3. Optional MQ - Gracefully handles when publisher is not configured
4. Repository pattern - Uses Create trait for consistent database access
5. Separate endpoint - Used /executions/execute instead of POST /executions to avoid route conflicts

Testing

E2E Test Results

cd tests && ./venvs/e2e/bin/pytest test_e2e_basic.py -v

All 6 tests passing:

• ✅ test_api_health
• ✅ test_authentication
• ✅ test_pack_registration
• ✅ test_create_simple_action
• ✅ test_create_automation_rule
• ✅ test_execute_action_directly (NEW - previously skipped)

Test Coverage

The new test verifies:

1. Action creation succeeds
2. Manual execution request accepted (201 Created)
3. Execution has correct action_ref and parameters
4. Execution status is valid (requested, scheduling, scheduled, running)
5. Execution can be retrieved by ID

Use Cases

1. Manual Testing

   • Execute actions during development
   • Test action behavior with different parameters
   • Debug action failures

2. Ad-hoc Operations

   • Administrative tasks without creating rules
   • One-off notifications or alerts
   • Emergency response actions

3. API-Driven Workflows

   • External systems trigger actions directly
   • REST API integrations
   • Scheduled jobs from external schedulers

4. Action Development

   • Quick feedback loop during action development
   • Test parameter validation
   • Verify action outputs

API Documentation

Endpoint: POST /api/v1/executions/execute

Authentication: Required (Bearer token)

Request Body:

Field	Type	Required	Description
action_ref	string	Yes	Action reference (e.g., "pack.action")
parameters	object	No	Action parameters as JSON object

Response Codes:

• 201 Created - Execution created and queued
• 400 Bad Request - Invalid request body
• 401 Unauthorized - Missing or invalid token
• 404 Not Found - Action not found
• 500 Internal Server Error - Server error

OpenAPI: Auto-documented via utoipa

Future Enhancements

1. Synchronous execution - Wait for execution to complete before returning
2. Execution callbacks - Webhook notifications when execution completes
3. Batch execution - Execute multiple actions in one request
4. Execution templates - Save common execution configurations
5. Execution scheduling - Schedule manual executions for future time

Impact

Before:

• ✅ Event-driven automation (sensor → trigger → rule → action)
• ❌ No manual action execution
• ❌ No API-driven workflows
• ⏭️ Test skipped (1 of 6)

After:

• ✅ Event-driven automation (existing)
• ✅ Manual action execution (new)
• ✅ API-driven workflows (new)
• ✅ All tests passing (6 of 6)

Documentation Updates

• ✅ CHANGELOG.md - Feature announcement with examples
• ✅ work-summary/2026-01-27-manual-execution-feature.md - This document
• ✅ Test documentation in test_e2e_basic.py - Updated class docstring

Related Work

• Sensor Service Fix - Fixed repository pattern issues that would have affected this feature
• Webhook Schema - Consolidated schema working correctly with all execution types
• E2E Testing - Full test coverage ensures feature works end-to-end

Verification Commands

# Rebuild API service
cargo build -p attune-api

# Restart API service
pkill attune-api
./target/debug/attune-api > /tmp/attune-api.log 2>&1 &

# Run E2E tests
cd tests
./venvs/e2e/bin/pytest test_e2e_basic.py -v

# Test manual execution directly
curl -X POST http://localhost:8080/api/v1/executions/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action_ref": "test_pack.echo",
    "parameters": {"message": "Hello World"}
  }'

Success Metrics

• ✅ API endpoint implemented and documented
• ✅ Execution creation working correctly
• ✅ Message queue integration functional
• ✅ All E2E tests passing (6/6)
• ✅ Test previously skipped now enabled and passing
• ✅ Zero compilation errors
• ✅ API service successfully restarted

---

Conclusion: The manual execution feature is fully implemented, tested, and ready for production use. Users can now execute actions directly via the API without requiring the full automation setup, enabling faster testing and more flexible workflows.