StageExecutionContext

NexusLabs.Needlr.AgentFramework.Workflows

NexusLabs.Needlr.AgentFramework.Workflows.Sequential

StageExecutionContext Class

Provides typed access to the pipeline's shared state during stage execution.

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

Inheritance System.Object 🡒 StageExecutionContext

Implements System.IEquatable<StageExecutionContext>

Example

public async Task<StageExecutionResult> ExecuteAsync(
    StageExecutionContext context,
    CancellationToken cancellationToken)
{
    Console.WriteLine($"Running stage {context.StageIndex + 1}/{context.TotalStages}: {context.StageName}");
    if (context.PhaseName is not null)
        Console.WriteLine($"  Phase: {context.PhaseName} (stage {context.StageIndexInPhase + 1}/{context.TotalStagesInPhase})");
    return StageExecutionResult.Success(context.StageName, diagnostics: null, responseText: null);
}

Constructors

StageExecutionContext(IWorkspace, IAgentDiagnosticsAccessor, IProgressReporter, int, int, string, CancellationToken, object, string, Nullable<int>, Nullable<int>, Nullable<int>) Constructor

Provides typed access to the pipeline's shared state during stage execution.

public StageExecutionContext(NexusLabs.Needlr.AgentFramework.Workspace.IWorkspace Workspace, NexusLabs.Needlr.AgentFramework.Diagnostics.IAgentDiagnosticsAccessor DiagnosticsAccessor, NexusLabs.Needlr.AgentFramework.Progress.IProgressReporter? ProgressReporter, int StageIndex, int TotalStages, string StageName, System.Threading.CancellationToken CallerCancellationToken=default(System.Threading.CancellationToken), object? PipelineState=null, string? PhaseName=null, System.Nullable<int> PhaseIndex=null, System.Nullable<int> StageIndexInPhase=null, System.Nullable<int> TotalStagesInPhase=null);

Parameters

Workspace NexusLabs.Needlr.AgentFramework.Workspace.IWorkspace

The shared workspace for reading/writing files across stages.

DiagnosticsAccessor NexusLabs.Needlr.AgentFramework.Diagnostics.IAgentDiagnosticsAccessor

Accessor for capturing per-stage diagnostics.

ProgressReporter NexusLabs.Needlr.AgentFramework.Progress.IProgressReporter

Optional progress reporter for emitting pipeline events.

StageIndex System.Int32

Zero-based index of the current stage in the pipeline.

TotalStages System.Int32

Total number of stages in the pipeline.

StageName System.String

Human-readable name of the current stage.

CallerCancellationToken System.Threading.CancellationToken

The original caller's cancellation token. Decorators that create linked tokens (e.g. TimeoutExecutor) should check this to distinguish user cancellation from internal timeouts.

PipelineState System.Object

Optional shared state object passed to all stages in the pipeline. Use GetRequiredState<T>() to retrieve it with type safety.

PhaseName System.String

The name of the pipeline phase this stage belongs to, or null when running a flat (non-phased) pipeline.

PhaseIndex System.Nullable<System.Int32>

Zero-based index of the current phase, or null for flat pipelines.

StageIndexInPhase System.Nullable<System.Int32>

Zero-based index of the current stage within its phase, or null for flat pipelines.

TotalStagesInPhase System.Nullable<System.Int32>

Total number of stages in the current phase, or null for flat pipelines.

Example

public async Task<StageExecutionResult> ExecuteAsync(
    StageExecutionContext context,
    CancellationToken cancellationToken)
{
    Console.WriteLine($"Running stage {context.StageIndex + 1}/{context.TotalStages}: {context.StageName}");
    if (context.PhaseName is not null)
        Console.WriteLine($"  Phase: {context.PhaseName} (stage {context.StageIndexInPhase + 1}/{context.TotalStagesInPhase})");
    return StageExecutionResult.Success(context.StageName, diagnostics: null, responseText: null);
}

Properties

StageExecutionContext.CallerCancellationToken Property

The original caller's cancellation token. Decorators that create linked tokens (e.g. TimeoutExecutor) should check this to distinguish user cancellation from internal timeouts.

public System.Threading.CancellationToken CallerCancellationToken { get; init; }

Property Value

System.Threading.CancellationToken

StageExecutionContext.DiagnosticsAccessor Property

Accessor for capturing per-stage diagnostics.

public NexusLabs.Needlr.AgentFramework.Diagnostics.IAgentDiagnosticsAccessor DiagnosticsAccessor { get; init; }

Property Value

NexusLabs.Needlr.AgentFramework.Diagnostics.IAgentDiagnosticsAccessor

StageExecutionContext.PhaseIndex Property

Zero-based index of the current phase, or null for flat pipelines.

public System.Nullable<int> PhaseIndex { get; init; }

Property Value

System.Nullable<System.Int32>

StageExecutionContext.PhaseName Property

The name of the pipeline phase this stage belongs to, or null when running a flat (non-phased) pipeline.

public string? PhaseName { get; init; }

Property Value

System.String

StageExecutionContext.PipelineState Property

Optional shared state object passed to all stages in the pipeline. Use GetRequiredState<T>() to retrieve it with type safety.

public object? PipelineState { get; init; }

Property Value

System.Object

StageExecutionContext.ProgressReporter Property

Optional progress reporter for emitting pipeline events.

public NexusLabs.Needlr.AgentFramework.Progress.IProgressReporter? ProgressReporter { get; init; }

Property Value

NexusLabs.Needlr.AgentFramework.Progress.IProgressReporter

StageExecutionContext.StageIndex Property

Zero-based index of the current stage in the pipeline.

public int StageIndex { get; init; }

Property Value

System.Int32

StageExecutionContext.StageIndexInPhase Property

Zero-based index of the current stage within its phase, or null for flat pipelines.

public System.Nullable<int> StageIndexInPhase { get; init; }

Property Value

System.Nullable<System.Int32>

StageExecutionContext.StageName Property

Human-readable name of the current stage.

public string StageName { get; init; }

Property Value

System.String

StageExecutionContext.TotalStages Property

Total number of stages in the pipeline.

public int TotalStages { get; init; }

Property Value

System.Int32

StageExecutionContext.TotalStagesInPhase Property

Total number of stages in the current phase, or null for flat pipelines.

public System.Nullable<int> TotalStagesInPhase { get; init; }

Property Value

System.Nullable<System.Int32>

StageExecutionContext.Workspace Property

The shared workspace for reading/writing files across stages.

public NexusLabs.Needlr.AgentFramework.Workspace.IWorkspace Workspace { get; init; }

Property Value

NexusLabs.Needlr.AgentFramework.Workspace.IWorkspace

Methods

StageExecutionContext.GetRequiredState<T>() Method

Gets the typed pipeline state, or throws if no state was provided or the type doesn't match.

public T GetRequiredState<T>()
    where T : class;

Type parameters

T

The expected pipeline state type.

Returns

T
The pipeline state cast to T.

Exceptions

System.InvalidOperationException
Thrown when PipelineState is null or not of type T.