StageExecutionResult

NexusLabs.Needlr.AgentFramework.Workflows

NexusLabs.Needlr.AgentFramework.Workflows.Sequential

StageExecutionResult Class

Describes the outcome of executing a single pipeline stage, including diagnostics, response text, success/failure state, and a typed NexusLabs.Needlr.AgentFramework.Diagnostics.StageTermination describing why the stage terminated.

public sealed record StageExecutionResult : System.IEquatable<NexusLabs.Needlr.AgentFramework.Workflows.Sequential.StageExecutionResult>

Inheritance System.Object 🡒 StageExecutionResult

Implements System.IEquatable<StageExecutionResult>

Example

var result = StageExecutionResult.Success("Writer", diagnostics, "Draft text");
if (result.Succeeded)
    Console.WriteLine($"Stage '{result.StageName}' produced: {result.ResponseText}");

Constructors

StageExecutionResult(string, IAgentRunDiagnostics, string, bool, Exception, FailureDisposition, IStageTermination) Constructor

Describes the outcome of executing a single pipeline stage, including diagnostics, response text, success/failure state, and a typed NexusLabs.Needlr.AgentFramework.Diagnostics.StageTermination describing why the stage terminated.

public StageExecutionResult(string StageName, NexusLabs.Needlr.AgentFramework.Diagnostics.IAgentRunDiagnostics? Diagnostics, string? ResponseText, bool Succeeded, System.Exception? Exception=null, NexusLabs.Needlr.AgentFramework.Workflows.Sequential.FailureDisposition FailureDisposition=NexusLabs.Needlr.AgentFramework.Workflows.Sequential.FailureDisposition.AbortPipeline, NexusLabs.Needlr.AgentFramework.Diagnostics.IStageTermination? Termination=null);

Parameters

StageName System.String

The name of the stage that was executed.

Diagnostics NexusLabs.Needlr.AgentFramework.Diagnostics.IAgentRunDiagnostics

Captured diagnostics for the stage, or null if not available.

ResponseText System.String

The text response produced by the stage, or null for non-agent stages.

Succeeded System.Boolean

Whether the stage completed successfully.

Exception System.Exception

The exception that caused failure, or null on success.

FailureDisposition FailureDisposition

Controls how the pipeline runner handles a failed result. Only meaningful when Succeeded is false.

Termination NexusLabs.Needlr.AgentFramework.Diagnostics.IStageTermination

Typed termination cause for the stage. null when the executor did not specify one (legacy executors, custom executors that do not populate it). Populated automatically by the static factories: Failed(string, Exception, IAgentRunDiagnostics, FailureDisposition, IStageTermination) wraps the exception, Skipped(string, string) wraps the optional reason. Callers can supply an explicit value to override the defaults.

Example

var result = StageExecutionResult.Success("Writer", diagnostics, "Draft text");
if (result.Succeeded)
    Console.WriteLine($"Stage '{result.StageName}' produced: {result.ResponseText}");

Properties

StageExecutionResult.Diagnostics Property

Captured diagnostics for the stage, or null if not available.

public NexusLabs.Needlr.AgentFramework.Diagnostics.IAgentRunDiagnostics? Diagnostics { get; init; }

Property Value

NexusLabs.Needlr.AgentFramework.Diagnostics.IAgentRunDiagnostics

StageExecutionResult.Exception Property

The exception that caused failure, or null on success.

public System.Exception? Exception { get; init; }

Property Value

System.Exception

StageExecutionResult.FailureDisposition Property

Controls how the pipeline runner handles a failed result. Only meaningful when Succeeded is false.

public NexusLabs.Needlr.AgentFramework.Workflows.Sequential.FailureDisposition FailureDisposition { get; init; }

Property Value

FailureDisposition

StageExecutionResult.ResponseText Property

The text response produced by the stage, or null for non-agent stages.

public string? ResponseText { get; init; }

Property Value

System.String

StageExecutionResult.StageName Property

The name of the stage that was executed.

public string StageName { get; init; }

Property Value

System.String

StageExecutionResult.Succeeded Property

Whether the stage completed successfully.

public bool Succeeded { get; init; }

Property Value

System.Boolean

StageExecutionResult.Termination Property

Typed termination cause for the stage. null when the executor did not specify one (legacy executors, custom executors that do not populate it). Populated automatically by the static factories: Failed(string, Exception, IAgentRunDiagnostics, FailureDisposition, IStageTermination) wraps the exception, Skipped(string, string) wraps the optional reason. Callers can supply an explicit value to override the defaults.

public NexusLabs.Needlr.AgentFramework.Diagnostics.IStageTermination? Termination { get; init; }

Property Value

NexusLabs.Needlr.AgentFramework.Diagnostics.IStageTermination

Methods

StageExecutionResult.Failed(string, Exception, IAgentRunDiagnostics, FailureDisposition, IStageTermination) Method

Creates a failed result for a stage.

public static NexusLabs.Needlr.AgentFramework.Workflows.Sequential.StageExecutionResult Failed(string stageName, System.Exception exception, NexusLabs.Needlr.AgentFramework.Diagnostics.IAgentRunDiagnostics? diagnostics=null, NexusLabs.Needlr.AgentFramework.Workflows.Sequential.FailureDisposition disposition=NexusLabs.Needlr.AgentFramework.Workflows.Sequential.FailureDisposition.AbortPipeline, NexusLabs.Needlr.AgentFramework.Diagnostics.IStageTermination? termination=null);

Parameters

stageName System.String

The name of the failed stage.

exception System.Exception

The exception that caused the failure.

diagnostics NexusLabs.Needlr.AgentFramework.Diagnostics.IAgentRunDiagnostics

Captured diagnostics, or null.

disposition FailureDisposition

How the pipeline runner should handle this failure. Defaults to AbortPipeline.

termination NexusLabs.Needlr.AgentFramework.Diagnostics.IStageTermination

Optional typed termination cause. When null, defaults to NexusLabs.Needlr.AgentFramework.Diagnostics.StageTermination.Failed wrapping exception.

Returns

StageExecutionResult
A failed StageExecutionResult.

StageExecutionResult.Skipped(string, string) Method

Creates a result indicating the stage was skipped.

public static NexusLabs.Needlr.AgentFramework.Workflows.Sequential.StageExecutionResult Skipped(string stageName, string? reason=null);

Parameters

stageName System.String

The name of the skipped stage.

reason System.String

Optional free-form reason describing why the stage was skipped. Carried into the populated NexusLabs.Needlr.AgentFramework.Diagnostics.StageTermination.Skipped termination value.

Returns

StageExecutionResult
A successful StageExecutionResult with no diagnostics or response.

StageExecutionResult.Success(string, IAgentRunDiagnostics, string, IStageTermination) Method

Creates a successful result for a stage.

public static NexusLabs.Needlr.AgentFramework.Workflows.Sequential.StageExecutionResult Success(string stageName, NexusLabs.Needlr.AgentFramework.Diagnostics.IAgentRunDiagnostics? diagnostics, string? responseText, NexusLabs.Needlr.AgentFramework.Diagnostics.IStageTermination? termination=null);

Parameters

stageName System.String

The name of the completed stage.

diagnostics NexusLabs.Needlr.AgentFramework.Diagnostics.IAgentRunDiagnostics

Captured diagnostics, or null.

responseText System.String

The text response, or null.

termination NexusLabs.Needlr.AgentFramework.Diagnostics.IStageTermination

Optional typed termination cause.

Returns

StageExecutionResult
A successful StageExecutionResult.