NexusLabs.Foundry.MicrosoftAgentFramework.Diagnostics

NexusLabs.Foundry.MicrosoftAgentFramework

NexusLabs.Foundry.MicrosoftAgentFramework.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.Foundry.MicrosoftAgentFramework.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.
HarnessArtifactDiagnostics	Privacy-safe, structured evidence for one artifact offload or rehydration decision. Carries only categorical classifications, byte counts, and a bounded reference identity — never an artifact body, a serialized raw result, a workspace path, an owner user/orchestration/session identity, or a raw exception message. Every instance is produced by NexusLabs.Foundry.MicrosoftAgentFramework.Diagnostics.HarnessArtifactDiagnostics.ForOffload(NexusLabs.Foundry.MicrosoftAgentFramework.Diagnostics.HarnessArtifactOutcomeCategory,NexusLabs.Foundry.MicrosoftAgentFramework.Diagnostics.HarnessArtifactContentCategory,NexusLabs.Foundry.MicrosoftAgentFramework.Diagnostics.HarnessArtifactDecisionReason,System.Int32,System.Int32,System.String) or NexusLabs.Foundry.MicrosoftAgentFramework.Diagnostics.HarnessArtifactDiagnostics.ForRehydration(NexusLabs.Foundry.MicrosoftAgentFramework.Diagnostics.HarnessArtifactOutcomeCategory,NexusLabs.Foundry.MicrosoftAgentFramework.Diagnostics.HarnessArtifactDecisionReason,System.Nullable{System.Int32},System.Int32,System.String), each of which only accepts the outcome and reason values valid for that operation, so a snapshot can never mix the two decisions' state machines.
HarnessContextAttribution	Privacy-safe UTF-8 byte attribution for one artifact offload or rehydration decision: how many bytes were observed coming in, and how many artifact-derived bytes actually resulted from the decision. Always measured in UTF-8 bytes regardless of the operation, so an offload's "shrink to a reference" and a rehydration's "expand from a reference" are reported through the same two-number shape. Never carries the artifact body itself — only byte counts and, transitively via ReferenceId on the snapshot this attribution rides along with, a bounded reference identity. OutputUtf8Bytes is null for failure and recovery-required outcomes; the caller may still emit a separate bounded error string for those outcomes, but that string is not part of the artifact-derived output counted here.
HarnessContextCategoryContribution	One category's contribution to a successful compaction/assembly decision's final size. The sum of every Size across a HarnessContextDiagnostics instance's CategoryContributions always equals that instance's FinalSize exactly, because both are computed from the same final entries using the same estimator that governed the policy decision.
HarnessContextDiagnostics	Privacy-safe, structured evidence for one hybrid context compaction/assembly decision. Carries only categorical outcomes/stages, an explicit measurement unit, sizes, an attempt count, per-category size/entry-count contributions, and a final sequence-validity flag — never raw message text, artifact bodies, workspace paths, owner identities, tool arguments/results, exception text, or classifier output text. Every instance is produced by NexusLabs.Foundry.MicrosoftAgentFramework.Diagnostics.HarnessContextDiagnostics.ForSuccess(NexusLabs.Foundry.MicrosoftAgentFramework.Diagnostics.HarnessContextCompactionOutcome,NexusLabs.Foundry.MicrosoftAgentFramework.Diagnostics.HarnessContextMeasurementUnit,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Collections.Generic.IReadOnlyList{NexusLabs.Foundry.MicrosoftAgentFramework.Diagnostics.HarnessContextAssemblyStageCategory},System.Collections.Generic.IReadOnlyList{NexusLabs.Foundry.MicrosoftAgentFramework.Diagnostics.HarnessContextCategoryContribution}) or NexusLabs.Foundry.MicrosoftAgentFramework.Diagnostics.HarnessContextDiagnostics.ForTermination(NexusLabs.Foundry.MicrosoftAgentFramework.Diagnostics.HarnessContextCompactionOutcome,NexusLabs.Foundry.MicrosoftAgentFramework.Diagnostics.HarnessContextMeasurementUnit,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Collections.Generic.IReadOnlyList{NexusLabs.Foundry.MicrosoftAgentFramework.Diagnostics.HarnessContextAssemblyStageCategory}), mirroring exactly the success/termination split of the internal assembly result this snapshot describes.
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 Foundry's diagnostics middleware creates System.Diagnostics.Activity spans for chat completion calls.
DiagnosticsTimelineEntryKind	Identifies the kind of event a DiagnosticsTimelineEntry represents.
HarnessArtifactContentCategory	The kind of content an artifact offload or rehydration decision was made about. Distinguishes an ordinary tool invocation result from a previously-rehydrated recoverable context segment being re-inlined by the offload transform's threshold bypass, so that bypass path remains separately inspectable from an ordinary below-threshold decision.
HarnessArtifactDecisionReason	The stable, explicit reason category behind one HarnessArtifactOutcomeCategory. Every value is assigned by a deterministic mapping at the point a decision is made — never derived by parsing a human-readable evidence string. The first ten members are only ever paired with an offload outcome; the last five are only ever paired with a rehydration outcome.
HarnessArtifactOperationCategory	Which of the two explicit artifact decisions a HarnessArtifactDiagnostics snapshot describes. Every snapshot belongs to exactly one category, and each category has its own closed set of valid HarnessArtifactOutcomeCategory and HarnessArtifactDecisionReason values.
HarnessArtifactOutcomeCategory	The explicit outcome of one artifact offload or rehydration decision. The five members through RecoveryRequired are only ever paired with Offload; the five members from Resolved onward are only ever paired with Rehydration. A single unified enum keeps every outcome inspectable through one categorical dimension without merging the two decisions' otherwise-disjoint state machines.
HarnessContextAssemblyStageCategory	Public, privacy-safe mirror of Harness.Context.HarnessContextAssemblyStage: one step performed while producing a compaction/assembly decision, recorded in execution order in Stages so the reduction path can be inspected without exposing any entry content.
HarnessContextCategory	Public, privacy-safe mirror of Harness.Context.HarnessContextEntryKind: the structural classification a final context entry contributes to CategoryContributions under. Every value here corresponds 1:1 to an internal entry kind, so a per-category byte/entry count can be reported without ever exposing entry content.
HarnessContextCompactionOutcome	Public, privacy-safe mirror of Harness.Context.HarnessContextAssemblyOutcome: the explicit categorical outcome of one hybrid context compaction/assembly attempt. The two termination members double as the explicit termination category carried by HarnessContextDiagnostics — there is no separate, redundant termination-category field.
HarnessContextMeasurementUnit	The explicit unit a Harness.Context.IHarnessContextSizeEstimator reports its integer size estimates in. Every size, threshold, and limit carried by HarnessContextDiagnostics is expressed in whatever unit the estimator that produced it declares — this enum exists so a generic integer is never silently mislabeled as a provider token count.
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.