PipelinePhasePolicy

NexusLabs.Needlr.AgentFramework.Workflows

NexusLabs.Needlr.AgentFramework.Workflows.Sequential

PipelinePhasePolicy Class

Configures runtime behavior for a PipelinePhase, including async lifecycle hooks and an optional phase-level token budget.

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

Inheritance System.Object 🡒 PipelinePhasePolicy

Implements System.IEquatable<PipelinePhasePolicy>

Example

var policy = new PipelinePhasePolicy
{
    OnEnterAsync = (ctx, ct) =>
    {
        Console.WriteLine($"Entering phase: {ctx.PhaseName}");
        return ValueTask.CompletedTask;
    },
    OnExitAsync = (ctx, ct) =>
    {
        Console.WriteLine($"Exiting phase: {ctx.PhaseName}");
        return ValueTask.CompletedTask;
    },
    TokenBudget = 50_000,
};

Remarks

This is intentionally distinct from StageExecutionPolicy. Phase policies control cross-stage concerns (budget scope, workspace reconfiguration), while stage policies control per-stage behavior (skip, retry, validation).

OnEnterAsync fires before any stage pre-work in the phase — before ShouldSkip evaluation, before prompt construction, before executor invocation. This guarantees that workspace/state configuration is applied before any stage can observe it.

OnExitAsync fires after the last stage completes (or on phase failure), in a finally block. It always runs regardless of success or failure, enabling cleanup and summary logic.

Properties

PipelinePhasePolicy.OnEnterAsync Property

Async callback invoked before the first stage in the phase executes. Fires before any stage pre-work (ShouldSkip, prompt construction, executor invocation). Fires even if all stages in the phase will be skipped. Not called if the phase has zero stages and no callback is set.

public System.Func<NexusLabs.Needlr.AgentFramework.Workflows.Sequential.PhaseContext,System.Threading.CancellationToken,System.Threading.Tasks.ValueTask>? OnEnterAsync { get; init; }

Property Value

System.Func<PhaseContext,System.Threading.CancellationToken,System.Threading.Tasks.ValueTask>

PipelinePhasePolicy.OnExitAsync Property

Async callback invoked after the last stage in the phase completes (or on phase failure/cancellation). Runs in a finally block — always fires regardless of success or failure.

public System.Func<NexusLabs.Needlr.AgentFramework.Workflows.Sequential.PhaseContext,System.Threading.CancellationToken,System.Threading.Tasks.ValueTask>? OnExitAsync { get; init; }

Property Value

System.Func<PhaseContext,System.Threading.CancellationToken,System.Threading.Tasks.ValueTask>

PipelinePhasePolicy.TokenBudget Property

Optional phase-level token budget. When set, the runner scopes a budget tracker for the entire phase. Individual stage budgets (TokenBudget) create child scopes within the phase budget scope.

public System.Nullable<long> TokenBudget { get; init; }

Property Value

System.Nullable<System.Int64>