NexusLabs.Needlr.AgentFramework.Diagnostics

NexusLabs.Needlr.AgentFramework

NexusLabs.Needlr.AgentFramework.Diagnostics Namespace

Classes
AgentFrameworkMetricsOptions	Configuration options for the agent framework's OpenTelemetry metrics and tracing.
AgentRunDiagnosticsBuilder	Thread-safe accumulator for diagnostics captured during a single agent run. Implements IDiagnosticsSink so writers (middleware, loops) record through a stable interface rather than coupling to the concrete builder.
AgentRunDiagnosticsTimelineExtensions	Extensions for producing ordered timeline views of an IAgentRunDiagnostics.
AgentRunDiagnosticsTranscriptExtensions	Extensions for rendering an IAgentRunDiagnostics as a human-readable markdown transcript.
ChatCompletionCollectorHolder	DI-registered singleton that holds the IChatCompletionCollector instance. The diagnostics middleware sets the real collector during factory construction; consumers resolve this to access it. Unlike a static holder, each DI container has its own instance, making it testable and thread-safe across containers.
ChatCompletionDiagnostics	Diagnostics for a single LLM chat completion call within an agent run.
DiagnosticsCharCounter	Computes character counts of chat messages, responses, tool arguments, and tool results for diagnostics capture. Character counts are a direct programmatic measure of payload size — distinct from the LLM-provider-reported TokenUsage — and are useful for detecting chat-reducer drift, prompt bloat, and unexpectedly large tool responses during evaluation.
DiagnosticsFunctionInvocationExtensions	Extension methods for wiring DiagnosticsFunctionInvokingChatClient into an MEAI chat client pipeline.
DiagnosticsFunctionInvokingChatClient	A Microsoft.Extensions.AI.FunctionInvokingChatClient that records per-tool-call diagnostics, OTel metrics, and Activity spans for every function invocation. This is the MEAI-native equivalent of the MAF DiagnosticsFunctionCallingMiddleware in Workflows.
DiagnosticsRecordingChatClient	Microsoft.Extensions.AI.DelegatingChatClient that routes calls through a NexusLabs.Needlr.AgentFramework.Diagnostics.DiagnosticsChatClientMiddleware and is detectable via GetService. Because this extends Microsoft.Extensions.AI.DelegatingChatClient, MEAI's GetService walks the delegation chain and returns this instance when queried by type — enabling idempotent middleware installation.
DiagnosticsTimelineEntry	A single entry in an agent run's ordered timeline of chat completions and tool calls.
PipelineMetricsOptions	Configuration options for pipeline-shape OpenTelemetry metrics emitted by IPipelineMetrics. Sibling of AgentFrameworkMetricsOptions — that type scopes the per-agent-run meter; this one scopes the pipeline-runner meter.
StageTermination	Describes why a pipeline stage terminated. Framework cases carry structured metadata (e.g. MaxIterationsReached knows the limit and the iterations used); application narrative goes through Custom.
StageTermination.BudgetPressure	The token budget tracker reported usage above the configured budget pressure threshold, and the loop ran one final finalization iteration before terminating.
StageTermination.Cancelled	The loop was cancelled via System.Threading.CancellationToken.
StageTermination.Completed	The stage's IsComplete predicate returned true after an iteration — the stage achieved its goal.
StageTermination.CompletedEarlyAfterToolCall	The IsComplete predicate returned true after a tool call within an iteration. This is a success termination — the stage achieved its goal and the loop exited early to avoid a wasted chat completion call.
StageTermination.Custom	Application-specific termination cause not covered by framework cases. Use this from an onLoopCompleted callback when a stage has app-specific semantics (e.g. "Reconciled — 7 outstanding issues").
StageTermination.Failed	The stage threw an exception, OR the iterative loop reported an unrecoverable error (in which case the loop's error message is wrapped in an System.InvalidOperationException here).
StageTermination.MaxIterationsReached	The loop exhausted its configured iteration limit without the IsComplete predicate returning true.
StageTermination.MaxToolCallsReached	The cumulative tool-call count across all iterations exceeded the configured MaxTotalToolCalls limit.
StageTermination.NaturalCompletion	The model produced a text response without requesting tool calls, signalling natural completion of the task.
StageTermination.Skipped	The stage was skipped via a ShouldSkip predicate on StageExecutionPolicy. Reason is optional because the current predicate signature does not supply one.
StageTermination.StallDetected	The loop detected that consecutive iterations produced nearly identical token usage, indicating the LLM is repeating the same work without making progress.
TeeDiagnosticsSink	An IDiagnosticsSink that dispatches every record to N inner sinks. Owns its own sequence counters so all sinks see consistent sequence numbers.
TokenUsage	Token usage breakdown for a single LLM call or aggregate across an agent run.
ToolCallCollectorHolder	DI-registered singleton that holds the IToolCallCollector instance. The diagnostics middleware sets the real collector during factory construction; consumers resolve this to access it. Unlike a static holder, each DI container has its own instance, making it testable and thread-safe across containers.
ToolCallDiagnostics	Diagnostics for a single tool/function invocation within an agent run.
WorkflowRunOptions	Options for running a workflow with diagnostics and progress reporting. Consolidates the parameters for RunWithDiagnosticsAsync into a single record to avoid excessive parameter counts.

Structs
GenAiTokenUsageTags	Strongly-typed bag of optional tags attached to a RecordTokenUsage(string, long, GenAiTokenUsageTags) measurement. Mirrors the tag schema written by MEAI's Microsoft.Extensions.AI.OpenTelemetryChatClient on the same gen_ai.client.token.usage histogram so the resulting series share a label set and aggregate cleanly under a single OpenTelemetry MetricStreamIdentity.

Interfaces
IAgentDiagnosticsAccessor	Provides access to the diagnostics captured during the most recent agent run in the current async flow. Uses the mutable-holder System.Threading.AsyncLocal<> pattern so that writes from child async flows (inside middleware) are visible to the parent scope.
IAgentDiagnosticsWriter	Write-side interface for storing diagnostics captured by middleware. Separated from IAgentDiagnosticsAccessor (the read-side) so that middleware can resolve this from DI without casting to a concrete type.
IAgentMetrics	Records agent execution metrics for observability. The default implementation emits System.Diagnostics.Metrics.Meter counters/histograms and System.Diagnostics.ActivitySource activities compatible with OpenTelemetry.
IAgentRunDiagnostics	Immutable view of diagnostics captured during a single agent run, including token usage, per-call timing, tool call details, and success/failure state.
IAgentStageResult	Result of a single agent stage within a multi-agent pipeline or group chat workflow, combining the response text with the captured diagnostics for that stage.
IChatCompletionCollector	Provides access to per-LLM-call completion diagnostics captured by the chat client middleware. Used by pipeline run extensions to correlate LLM call timing with agent turns.
IDagNodeResult	Diagnostics for a single node within a DAG workflow execution, including edge connectivity, timing offsets relative to the workflow start, and the NodeKind discriminator that distinguishes agent nodes from reducer nodes.
IDagRunResult	Aggregated result of a DAG workflow run, extending IPipelineRunResult with per-node diagnostics, edge metadata, and parallel branch grouping.
IDiagnosticsSink	Accepts diagnostic records produced during an agent run. Writers (middleware, orchestration loops) call these methods to record individual chat completions and tool calls. The sink is responsible for storage and aggregation.
IGenAiTokenMetrics	Records measurements on the OpenTelemetry gen_ai.client.token.usage histogram for token-type categories that Microsoft.Extensions.AI.OpenTelemetryChatClient does not emit itself (today: cache_read and reasoning).
IInFlightAgentDiagnosticsAccessor	Read-only accessor that exposes a snapshot of the diagnostics being accumulated for the currently in-flight agent run on the calling async flow. The post-run sibling is LastRunDiagnostics.
IPipelineMetrics	Records pipeline-shape execution metrics for observability. The default implementation emits System.Diagnostics.Metrics.Meter counters / histograms and ActivitySource activities compatible with OpenTelemetry. Sibling of IAgentMetrics — that interface scopes to per-agent-run signals; this one scopes to per-pipeline and per-stage signals emitted by SequentialPipelineRunner.
IPipelineRunResult	Aggregated result of a multi-agent pipeline run, providing per-stage diagnostics alongside the response text from each agent.
IStageTermination	Contract for any value that describes why a pipeline stage terminated. Implemented by the framework's closed StageTermination hierarchy (12 framework cases including the Custom escape hatch) and — optionally — by consumer-defined types when a typed extension case is required.
IToolCallCollector	Provides access to per-tool-call diagnostics captured by the function-calling middleware. Used by pipeline run extensions to prevent silent tool call data loss when AsyncLocal diagnostics builders don't propagate across workflow infrastructure.
IToolMetricsAccessor	Allows tools to attach custom domain-specific metrics during execution. Metrics are collected by the diagnostics function-calling middleware and included in CustomMetrics.

Enums
ChatCompletionActivityMode	Controls how Needlr's diagnostics middleware creates System.Diagnostics.Activity spans for chat completion calls.
DiagnosticsTimelineEntryKind	Identifies the kind of event a DiagnosticsTimelineEntry represents.
NodeKind	Discriminates between agent nodes (backed by an LLM) and reducer nodes (pure deterministic functions) in a DAG workflow result.
StageOutcome	The outcome of a pipeline stage execution.