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}");
    return StageExecutionResult.Success(context.StageName, diagnostics: null, responseText: null);
}

Constructors

StageExecutionContext(IWorkspace, IAgentDiagnosticsAccessor, IProgressReporter, int, int, string, CancellationToken, object) 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);

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.

Example

public async Task<StageExecutionResult> ExecuteAsync(
    StageExecutionContext context,
    CancellationToken cancellationToken)
{
    Console.WriteLine($"Running stage {context.StageIndex + 1}/{context.TotalStages}: {context.StageName}");
    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.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.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.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.