[FEATURE]: Support reasonForIncompletion in fail_task event handlers

[uri-simspace]

The feature, motivation and pitch

Please add support for setting reasonForIncompletion when an event handler uses action: "fail_task".

Today, fail_task can be used to mark a task as failed and attach output data, but there is no way to populate the task failure reason from the event payload. For asynchronous integrations, this makes it hard to propagate a meaningful external error back into Conductor.

Our use case is event-driven task completion over RabbitMQ:

• A workflow sends a message using an EVENT task.
• A downstream system processes the request.
• A Conductor event handler receives the response.
• On success we use action: "complete_task".
• On failure we use action: "fail_task".

For the failure case, we need to set both:

1. task output data
2. task.reasonForIncompletion

This would improve task-level observability and also allow the workflow failure reason to contain the same external error when that failed task causes the workflow to fail.

It would also make fail_task align more closely with the Task Update API, which already supports reasonForIncompletion.

Is your feature request related to a specific problem? e.g., "I'm working on X and would like Y to be possible". If this is related to another GitHub issue, please link here too.

Yes.

Here is a minimal example of the current handler:

{
  "name": "result_failed",
  "event": "amqp_queue:example",
  "condition": "$.status == 'failed'",
  "actions": [
    {
      "action": "fail_task",
      "fail_task": {
        "taskId": "${task_id}",
        "output": {
          "actuatorResult": "${invoker_result}",
          "actuatorError": "${error}"
        }
      },
      "expandInlineJSON": false
    }
  ],
  "active": true,
  "evaluatorType": "javascript"
}

Observed behavior:

• the task is marked FAILED
• the output is stored
• the actual task failure reason is not populated from the event payload
• when this task failure causes the workflow to fail, the workflow does not carry the external error as its failure reason

Desired behavior:

• fail_task should optionally accept reasonForIncompletion
• the value should support the same payload expression resolution used for output
• existing handlers should continue to work unchanged when the field is omitted

Alternatives

The current alternatives are possible, but not ideal:

1. Put the error only in output, which preserves the data but does not set the official task failure reason.
2. Bypass the event handler for failures and have the consumer call POST /api/tasks with status=FAILED and reasonForIncompletion.
3. Patch Conductor locally to add support for this.

Option 2 and 3 work around the gap, but native support in event handlers would be cleaner and more consistent.

Additional context

A backward-compatible shape could look like this:

{
  "action": "fail_task",
  "fail_task": {
    "taskId": "${task_id}",
    "reasonForIncompletion": "${error}",
    "output": {
      "actuatorResult": "${invoker_result}",
      "actuatorError": "${error}"
    }
  },
  "expandInlineJSON": false
}

Expected behavior for this example:

• task status becomes FAILED
• task.reasonForIncompletion is set to the resolved value of ${error}
• output continues to be stored exactly as today
• if this failure is terminal for the workflow, the workflow failure reason reflects the same message

From reading the current implementation, this appears to be because EventHandler.TaskDetails does not currently expose a reasonForIncompletion field, and the event-handler task update path only sets status/output/outputMessage.

A possible implementation direction would be:

• add reasonForIncompletion to EventHandler.TaskDetails
• resolve it using the same parameter replacement used for output
• in the event handler task update path, set it on the task before calling updateTask(...)

Happy to contribute a PR for this if the maintainers agree with the direction.