IProgressSink

NexusLabs.Needlr.AgentFramework

NexusLabs.Needlr.AgentFramework.Progress

IProgressSink Interface

Receives progress events as they occur during agent/workflow execution. Implement this interface to build SSE streams, console displays, trace diagrams, etc.

public interface IProgressSink

Example

// Auto-discovered by Needlr — no explicit registration needed.
public sealed class ConsoleSink : IProgressSink
{
    public ValueTask OnEventAsync(IProgressEvent e, CancellationToken ct)
    {
        Console.WriteLine($"[{e.WorkflowId}] {e.GetType().Name}");
        return ValueTask.CompletedTask;
    }
}

Remarks

Auto-discovery (simple apps): If Needlr's source generator or reflection-based scanning is active, any class implementing IProgressSink is automatically registered in DI as a singleton. These auto-discovered sinks become the default sinks used by Create(string). You can also register sinks manually via services.AddSingleton<IProgressSink, MySink>() — all DI-registered IProgressSink instances are treated as defaults.

Per-orchestration sinks (complex apps): Use Create(string, IEnumerable<IProgressSink>) to pass sinks explicitly for a specific workflow run. This overload ignores the default sinks entirely, giving multi-tenant or multi-workflow applications full control over which sinks receive events for each orchestration.

Opting out of auto-discovery: Apply NexusLabs.Needlr.DoNotAutoRegisterAttribute to a sink class to prevent Needlr from automatically registering it. This is useful when you want the sink registered only through explicit per-orchestration passing or manual DI registration with a specific lifetime.

Performance: Implementations should be fast — a slow sink delays the agent pipeline. Use ChannelProgressReporter for non-blocking delivery when sinks perform I/O.

Methods

IProgressSink.OnEventAsync(IProgressEvent, CancellationToken) Method

Called for each progress event. Implementations should be fast — a slow sink delays the agent pipeline (use ChannelProgressReporter for non-blocking delivery).

System.Threading.Tasks.ValueTask OnEventAsync(NexusLabs.Needlr.AgentFramework.Progress.IProgressEvent progressEvent, System.Threading.CancellationToken cancellationToken);

Parameters

progressEvent IProgressEvent

cancellationToken System.Threading.CancellationToken

Returns

System.Threading.Tasks.ValueTask