SequentialPipelineRunner

NexusLabs.Needlr.AgentFramework.Workflows

NexusLabs.Needlr.AgentFramework.Workflows.Sequential

SequentialPipelineRunner Class

Executes a linear sequence of PipelineStage instances, evaluating policies (skip, retry, budget) and producing an NexusLabs.Needlr.AgentFramework.Diagnostics.IPipelineRunResult with per-stage diagnostics.

public sealed class SequentialPipelineRunner

Inheritance System.Object 🡒 SequentialPipelineRunner

Example

var runner = new SequentialPipelineRunner(diagnosticsAccessor, budgetTracker, progressFactory);
var stages = new[]
{
    new PipelineStage("Writer", new AgentStageExecutor(writerAgent, ctx => "Write a draft.")),
    new PipelineStage("Editor", new AgentStageExecutor(editorAgent, ctx => "Edit the draft.")),
};
var result = await runner.RunAsync(workspace, stages, options: null, cancellationToken);

Remarks

This runner is a peer of NexusLabs.Needlr.AgentFramework.Workflows.GraphWorkflowRunner for linear pipelines. It supports hybrid agent/programmatic stages via IStageExecutor, conditional skipping, post-validation with retries, per-stage and overall token budgets, and structured progress reporting.

Constructors

SequentialPipelineRunner(IAgentDiagnosticsAccessor, ITokenBudgetTracker, IProgressReporterFactory) Constructor

Initializes a new SequentialPipelineRunner.

public SequentialPipelineRunner(NexusLabs.Needlr.AgentFramework.Diagnostics.IAgentDiagnosticsAccessor diagnosticsAccessor, NexusLabs.Needlr.AgentFramework.Budget.ITokenBudgetTracker budgetTracker, NexusLabs.Needlr.AgentFramework.Progress.IProgressReporterFactory progressReporterFactory);

Parameters

diagnosticsAccessor NexusLabs.Needlr.AgentFramework.Diagnostics.IAgentDiagnosticsAccessor

Accessor for capturing per-stage agent diagnostics.

budgetTracker NexusLabs.Needlr.AgentFramework.Budget.ITokenBudgetTracker

Token budget tracker for scoping per-stage and pipeline-level budgets.

progressReporterFactory NexusLabs.Needlr.AgentFramework.Progress.IProgressReporterFactory

Factory for creating progress reporters.

Methods

SequentialPipelineRunner.RunAsync(IWorkspace, IReadOnlyList<PipelineStage>, SequentialPipelineOptions, CancellationToken) Method

Runs all pipeline stages sequentially, applying policies and collecting results.

public System.Threading.Tasks.Task<NexusLabs.Needlr.AgentFramework.Diagnostics.IPipelineRunResult> RunAsync(NexusLabs.Needlr.AgentFramework.Workspace.IWorkspace workspace, System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.AgentFramework.Workflows.Sequential.PipelineStage> stages, NexusLabs.Needlr.AgentFramework.Workflows.Sequential.SequentialPipelineOptions? options, System.Threading.CancellationToken cancellationToken);

Parameters

workspace NexusLabs.Needlr.AgentFramework.Workspace.IWorkspace

The shared workspace for file I/O across stages.

stages System.Collections.Generic.IReadOnlyList<PipelineStage>

The ordered list of stages to execute.

options SequentialPipelineOptions

Optional pipeline-level configuration.

cancellationToken System.Threading.CancellationToken

Token to observe for cancellation.

Returns

System.Threading.Tasks.Task<NexusLabs.Needlr.AgentFramework.Diagnostics.IPipelineRunResult>
An NexusLabs.Needlr.AgentFramework.Diagnostics.IPipelineRunResult describing the pipeline outcome.

SequentialPipelineRunner.RunAsync<TState>(IWorkspace, IReadOnlyList<PipelineStage>, TState, SequentialPipelineOptions, CancellationToken) Method

Runs all pipeline stages sequentially with a shared typed state object, applying policies and collecting results.

public System.Threading.Tasks.Task<NexusLabs.Needlr.AgentFramework.Diagnostics.IPipelineRunResult> RunAsync<TState>(NexusLabs.Needlr.AgentFramework.Workspace.IWorkspace workspace, System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.AgentFramework.Workflows.Sequential.PipelineStage> stages, TState state, NexusLabs.Needlr.AgentFramework.Workflows.Sequential.SequentialPipelineOptions? options, System.Threading.CancellationToken cancellationToken)
    where TState : class;

Type parameters

TState

The type of the shared pipeline state.

Parameters

workspace NexusLabs.Needlr.AgentFramework.Workspace.IWorkspace

The shared workspace for file I/O across stages.

stages System.Collections.Generic.IReadOnlyList<PipelineStage>

The ordered list of stages to execute.

state TState

A shared state object accessible to all stages via GetRequiredState<T>().

options SequentialPipelineOptions

Optional pipeline-level configuration.

cancellationToken System.Threading.CancellationToken

Token to observe for cancellation.

Returns

System.Threading.Tasks.Task<NexusLabs.Needlr.AgentFramework.Diagnostics.IPipelineRunResult>
An NexusLabs.Needlr.AgentFramework.Diagnostics.IPipelineRunResult describing the pipeline outcome.

SequentialPipelineRunner.RunPhasedAsync(IWorkspace, IReadOnlyList<PipelinePhase>, SequentialPipelineOptions, CancellationToken) Method

Runs a phased pipeline where stages are grouped into named phases with lifecycle hooks and optional phase-level token budgets.

public System.Threading.Tasks.Task<NexusLabs.Needlr.AgentFramework.Diagnostics.IPipelineRunResult> RunPhasedAsync(NexusLabs.Needlr.AgentFramework.Workspace.IWorkspace workspace, System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.AgentFramework.Workflows.Sequential.PipelinePhase> phases, NexusLabs.Needlr.AgentFramework.Workflows.Sequential.SequentialPipelineOptions? options, System.Threading.CancellationToken cancellationToken);

Parameters

workspace NexusLabs.Needlr.AgentFramework.Workspace.IWorkspace

The shared workspace for file I/O across stages.

phases System.Collections.Generic.IReadOnlyList<PipelinePhase>

The ordered list of phases, each containing stages.

options SequentialPipelineOptions

Optional pipeline-level configuration.

cancellationToken System.Threading.CancellationToken

Token to observe for cancellation.

Returns

System.Threading.Tasks.Task<NexusLabs.Needlr.AgentFramework.Diagnostics.IPipelineRunResult>
An NexusLabs.Needlr.AgentFramework.Diagnostics.IPipelineRunResult describing the pipeline outcome.

SequentialPipelineRunner.RunPhasedAsync<TState>(IWorkspace, IReadOnlyList<PipelinePhase>, TState, SequentialPipelineOptions, CancellationToken) Method

Runs a phased pipeline with a shared typed state object accessible to both phase lifecycle hooks and stage executors.

public System.Threading.Tasks.Task<NexusLabs.Needlr.AgentFramework.Diagnostics.IPipelineRunResult> RunPhasedAsync<TState>(NexusLabs.Needlr.AgentFramework.Workspace.IWorkspace workspace, System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.AgentFramework.Workflows.Sequential.PipelinePhase> phases, TState state, NexusLabs.Needlr.AgentFramework.Workflows.Sequential.SequentialPipelineOptions? options, System.Threading.CancellationToken cancellationToken)
    where TState : class;

Type parameters

TState

The type of the shared pipeline state.

Parameters

workspace NexusLabs.Needlr.AgentFramework.Workspace.IWorkspace

The shared workspace for file I/O across stages.

phases System.Collections.Generic.IReadOnlyList<PipelinePhase>

The ordered list of phases, each containing stages.

state TState

A shared state object accessible via GetRequiredState<T>() and GetRequiredState<T>().

options SequentialPipelineOptions

Optional pipeline-level configuration.

cancellationToken System.Threading.CancellationToken

Token to observe for cancellation.

Returns

System.Threading.Tasks.Task<NexusLabs.Needlr.AgentFramework.Diagnostics.IPipelineRunResult>
An NexusLabs.Needlr.AgentFramework.Diagnostics.IPipelineRunResult describing the pipeline outcome.