| | | 1 | | using NexusLabs.Needlr.AgentFramework.Diagnostics; |
| | | 2 | | |
| | | 3 | | namespace NexusLabs.Needlr.AgentFramework.Workflows.Sequential; |
| | | 4 | | |
| | | 5 | | /// <summary> |
| | | 6 | | /// Describes the outcome of executing a single pipeline stage, including |
| | | 7 | | /// diagnostics, response text, success/failure state, and a typed |
| | | 8 | | /// <see cref="StageTermination"/> describing why the stage terminated. |
| | | 9 | | /// </summary> |
| | | 10 | | /// <param name="StageName">The name of the stage that was executed.</param> |
| | | 11 | | /// <param name="Diagnostics">Captured diagnostics for the stage, or <see langword="null"/> if not available.</param> |
| | | 12 | | /// <param name="ResponseText">The text response produced by the stage, or <see langword="null"/> for non-agent stages.< |
| | | 13 | | /// <param name="Succeeded">Whether the stage completed successfully.</param> |
| | | 14 | | /// <param name="Exception">The exception that caused failure, or <see langword="null"/> on success.</param> |
| | | 15 | | /// <param name="FailureDisposition">Controls how the pipeline runner handles a failed result. |
| | | 16 | | /// Only meaningful when <paramref name="Succeeded"/> is <see langword="false"/>.</param> |
| | | 17 | | /// <param name="Termination"> |
| | | 18 | | /// Typed termination cause for the stage. <see langword="null"/> when the executor |
| | | 19 | | /// did not specify one (legacy executors, custom executors that do not populate it). |
| | | 20 | | /// Populated automatically by the static factories: <see cref="Failed"/> wraps the |
| | | 21 | | /// exception, <see cref="Skipped"/> wraps the optional reason. Callers can supply |
| | | 22 | | /// an explicit value to override the defaults. |
| | | 23 | | /// </param> |
| | | 24 | | /// <example> |
| | | 25 | | /// <code> |
| | | 26 | | /// var result = StageExecutionResult.Success("Writer", diagnostics, "Draft text"); |
| | | 27 | | /// if (result.Succeeded) |
| | | 28 | | /// Console.WriteLine($"Stage '{result.StageName}' produced: {result.ResponseText}"); |
| | | 29 | | /// </code> |
| | | 30 | | /// </example> |
| | 212 | 31 | | public sealed record StageExecutionResult( |
| | 10 | 32 | | string StageName, |
| | 206 | 33 | | IAgentRunDiagnostics? Diagnostics, |
| | 112 | 34 | | string? ResponseText, |
| | 148 | 35 | | bool Succeeded, |
| | 32 | 36 | | Exception? Exception = null, |
| | 23 | 37 | | FailureDisposition FailureDisposition = FailureDisposition.AbortPipeline, |
| | 351 | 38 | | IStageTermination? Termination = null) |
| | | 39 | | { |
| | | 40 | | /// <summary> |
| | | 41 | | /// Creates a successful result for a stage. |
| | | 42 | | /// </summary> |
| | | 43 | | /// <param name="stageName">The name of the completed stage.</param> |
| | | 44 | | /// <param name="diagnostics">Captured diagnostics, or <see langword="null"/>.</param> |
| | | 45 | | /// <param name="responseText">The text response, or <see langword="null"/>.</param> |
| | | 46 | | /// <param name="termination">Optional typed termination cause.</param> |
| | | 47 | | /// <returns>A successful <see cref="StageExecutionResult"/>.</returns> |
| | | 48 | | public static StageExecutionResult Success( |
| | | 49 | | string stageName, |
| | | 50 | | IAgentRunDiagnostics? diagnostics, |
| | | 51 | | string? responseText, |
| | | 52 | | IStageTermination? termination = null) => |
| | 161 | 53 | | new(stageName, diagnostics, responseText, Succeeded: true, Termination: termination); |
| | | 54 | | |
| | | 55 | | /// <summary> |
| | | 56 | | /// Creates a failed result for a stage. |
| | | 57 | | /// </summary> |
| | | 58 | | /// <param name="stageName">The name of the failed stage.</param> |
| | | 59 | | /// <param name="exception">The exception that caused the failure.</param> |
| | | 60 | | /// <param name="diagnostics">Captured diagnostics, or <see langword="null"/>.</param> |
| | | 61 | | /// <param name="disposition">How the pipeline runner should handle this failure. |
| | | 62 | | /// Defaults to <see cref="FailureDisposition.AbortPipeline"/>.</param> |
| | | 63 | | /// <param name="termination"> |
| | | 64 | | /// Optional typed termination cause. When <see langword="null"/>, defaults to |
| | | 65 | | /// <see cref="StageTermination.Failed"/> wrapping <paramref name="exception"/>. |
| | | 66 | | /// </param> |
| | | 67 | | /// <returns>A failed <see cref="StageExecutionResult"/>.</returns> |
| | | 68 | | public static StageExecutionResult Failed( |
| | | 69 | | string stageName, |
| | | 70 | | Exception exception, |
| | | 71 | | IAgentRunDiagnostics? diagnostics = null, |
| | | 72 | | FailureDisposition disposition = FailureDisposition.AbortPipeline, |
| | | 73 | | IStageTermination? termination = null) => |
| | 47 | 74 | | new(stageName, diagnostics, ResponseText: null, Succeeded: false, |
| | 47 | 75 | | Exception: exception, FailureDisposition: disposition, |
| | 47 | 76 | | Termination: termination ?? new StageTermination.Failed(exception)); |
| | | 77 | | |
| | | 78 | | /// <summary> |
| | | 79 | | /// Creates a result indicating the stage was skipped. |
| | | 80 | | /// </summary> |
| | | 81 | | /// <param name="stageName">The name of the skipped stage.</param> |
| | | 82 | | /// <param name="reason"> |
| | | 83 | | /// Optional free-form reason describing why the stage was skipped. Carried into |
| | | 84 | | /// the populated <see cref="StageTermination.Skipped"/> termination value. |
| | | 85 | | /// </param> |
| | | 86 | | /// <returns>A successful <see cref="StageExecutionResult"/> with no diagnostics or response.</returns> |
| | | 87 | | public static StageExecutionResult Skipped(string stageName, string? reason = null) => |
| | 2 | 88 | | new(stageName, Diagnostics: null, ResponseText: null, Succeeded: true, |
| | 2 | 89 | | Termination: new StageTermination.Skipped(reason)); |
| | | 90 | | } |