chore: import upstream snapshot with attribution

showcase/integrations/ms-agent-dotnet/agent/tests/A2uiSecondaryToolCallerTests.cs

@@ -0,0 +1,90 @@
+using Xunit;
+
+namespace MsAgentDotnet.AgentTests;
+
+// Exercises A2uiSecondaryToolCaller.ParseDesignToolArguments, the response-body
+// parser that backs the A2UI secondary tool caller. The parser must:
+//   * return the tool-call arguments on a well-formed response,
+//   * return null for the expected "no usable tool call" cases, and
+//   * throw A2uiUpstreamResponseException (NOT an uncaught KeyNotFoundException
+//     or JsonException) for a structurally-malformed-but-2xx body, carrying the
+//     upstream body for server-side logging.
+public class A2uiSecondaryToolCallerParseTests
+{
+    private const string DesignTool = "_design_a2ui_surface";
+
+    [Fact]
+    public void WellFormedToolCall_ReturnsArguments()
+    {
+        var body = $$"""
+        {
+          "choices": [
+            { "message": { "tool_calls": [
+              { "function": { "name": "{{DesignTool}}", "arguments": "{\"surfaceId\":\"s\"}" } }
+            ] } }
+          ]
+        }
+        """;
+
+        var result = A2uiSecondaryToolCaller.ParseDesignToolArguments(body);
+
+        Assert.Equal("{\"surfaceId\":\"s\"}", result);
+    }
+
+    [Theory]
+    [InlineData("{\"choices\":[]}")]                              // empty choices
+    [InlineData("{\"other\":1}")]                                  // no choices
+    [InlineData("{\"choices\":[{\"message\":{}}]}")]               // no tool_calls
+    [InlineData("{\"choices\":[{\"message\":{\"tool_calls\":[]}}]}")] // empty tool_calls
+    public void NoUsableToolCall_ReturnsNull(string body)
+    {
+        Assert.Null(A2uiSecondaryToolCaller.ParseDesignToolArguments(body));
+    }
+
+    [Fact]
+    public void WrongToolName_ReturnsNull()
+    {
+        var body = """
+        {"choices":[{"message":{"tool_calls":[{"function":{"name":"other","arguments":"{}"}}]}}]}
+        """;
+
+        Assert.Null(A2uiSecondaryToolCaller.ParseDesignToolArguments(body));
+    }
+
+    [Fact]
+    public void NonJsonBody_Throws_WithBodyCaptured()
+    {
+        const string body = "not json at all";
+
+        var ex = Assert.Throws<A2uiUpstreamResponseException>(
+            () => A2uiSecondaryToolCaller.ParseDesignToolArguments(body));
+
+        Assert.Equal(body, ex.Body);
+    }
+
+    [Fact]
+    public void ChoiceWithoutMessage_Throws_InsteadOfKeyNotFound()
+    {
+        // A choice object that lacks "message" — the bare GetProperty would
+        // have thrown an uncaught KeyNotFoundException before the guard.
+        const string body = "{\"choices\":[{\"index\":0}]}";
+
+        var ex = Assert.Throws<A2uiUpstreamResponseException>(
+            () => A2uiSecondaryToolCaller.ParseDesignToolArguments(body));
+
+        Assert.Equal(body, ex.Body);
+    }
+
+    [Fact]
+    public void ToolCallWithoutFunction_Throws_InsteadOfKeyNotFound()
+    {
+        // A tool_calls entry that lacks "function" — the bare GetProperty would
+        // have thrown an uncaught KeyNotFoundException before the guard.
+        const string body = "{\"choices\":[{\"message\":{\"tool_calls\":[{\"id\":\"x\"}]}}]}";
+
+        var ex = Assert.Throws<A2uiUpstreamResponseException>(
+            () => A2uiSecondaryToolCaller.ParseDesignToolArguments(body));
+
+        Assert.Equal(body, ex.Body);
+    }
+}

showcase/integrations/ms-agent-dotnet/agent/tests/AimockHeaderPropagationTests.cs

@@ -0,0 +1,143 @@
+using System.ClientModel.Primitives;
+using Microsoft.AspNetCore.Http;
+using Xunit;
+
+namespace MsAgentDotnet.AgentTests;
+
+// Red-green regression test for the .NET header-forwarding root cause.
+//
+// The bug: AimockHeaderMiddleware set the inbound x-aimock-context header into
+// an AsyncLocal, then `await _next(context)` pumped the AG-UI SSE response on an
+// ExecutionContext branch that did NOT inherit that AsyncLocal value. So when
+// the outbound OpenAI call was made (deep inside the SSE pump), the policy read
+// an empty header set -> x-aimock-context was NOT forwarded -> aimock strict
+// mode returned 503 -> hung/aborted turns.
+//
+// The fix: stash the headers on HttpContext.Items and read them via
+// IHttpContextAccessor. HttpContext flows across the SSE-pump ExecutionContext
+// boundary (the server seeds the accessor's holder at request entry, before any
+// middleware, and every branch of the request's async tree shares that holder).
+//
+// These tests reproduce the ExecutionContext boundary the SSE pump crosses:
+// capture an ExecutionContext snapshot at "response start" and run the outbound
+// read inside that captured context via ExecutionContext.Run, exactly as the
+// SSE pump does. The AsyncLocal-set-after-capture value is invisible there; the
+// HttpContext.Items value (read through the accessor singleton) survives.
+public class AimockHeaderPropagationTests
+{
+    private const string AimockHeader = "x-aimock-context";
+    private const string Slug = "gen-ui-chat";
+
+    // Demonstrates the ROOT CAUSE: an AsyncLocal set AFTER an ExecutionContext
+    // snapshot is captured is NOT visible when that snapshot is later run. This
+    // is precisely the AG-UI SSE-pump boundary the old middleware lost the
+    // header across. (RED for the old design.)
+    [Fact]
+    public void AsyncLocalSetAfterSnapshot_IsInvisibleAcrossExecutionContextBoundary()
+    {
+        var asyncLocal = new AsyncLocal<string?>();
+
+        // SSE pump captures the ambient ExecutionContext at response-start,
+        // BEFORE the middleware sets its AsyncLocal for this request.
+        var capturedAtResponseStart = ExecutionContext.Capture()!;
+
+        // Middleware sets the header into the AsyncLocal (old design).
+        asyncLocal.Value = Slug;
+
+        // Outbound LLM call runs inside the captured (pre-set) context.
+        string? observedAtOutbound = "SENTINEL";
+        ExecutionContext.Run(capturedAtResponseStart, _ =>
+        {
+            observedAtOutbound = asyncLocal.Value;
+        }, null);
+
+        // The header is LOST -> this is the 503-causing bug.
+        Assert.Null(observedAtOutbound);
+    }
+
+    // Demonstrates the FIX: HttpContext.Items read via IHttpContextAccessor
+    // survives the same ExecutionContext boundary, because the accessor's holder
+    // (seeded once, ambient) points at the same mutable HttpContext regardless
+    // of which captured ExecutionContext snapshot the outbound read runs on.
+    // (GREEN for the new design.)
+    [Fact]
+    public void HttpContextItems_SurvivesExecutionContextBoundary_ViaAccessor()
+    {
+        var accessor = new HttpContextAccessor();
+        var httpContext = new DefaultHttpContext();
+        accessor.HttpContext = httpContext;
+
+        // SSE pump captures the ambient ExecutionContext at response-start,
+        // BEFORE the middleware stashes the header on HttpContext.Items.
+        var capturedAtResponseStart = ExecutionContext.Capture()!;
+
+        // Middleware stashes the inbound x-* headers on HttpContext.Items (fix).
+        var inbound = new Dictionary<string, string> { [AimockHeader] = Slug };
+        AimockHeaderContext.Set(httpContext, inbound);
+
+        // Outbound LLM call runs inside the captured (pre-set) context, reading
+        // through the accessor exactly as AimockHeaderPolicy.ApplyHeadersAndDiag does.
+        Dictionary<string, string> observedAtOutbound = new();
+        ExecutionContext.Run(capturedAtResponseStart, _ =>
+        {
+            observedAtOutbound = AimockHeaderContext.Get(accessor.HttpContext);
+        }, null);
+
+        // The header is PRESENT at the outbound boundary -> forwarded -> 200.
+        Assert.True(observedAtOutbound.ContainsKey(AimockHeader));
+        Assert.Equal(Slug, observedAtOutbound[AimockHeader]);
+    }
+
+    // End-to-end through the actual policy: the seeded static accessor lets the
+    // production policy forward x-aimock-context onto a real outbound request
+    // message, even when the policy runs inside a pre-captured ExecutionContext.
+    [Fact]
+    public async Task Policy_ForwardsAimockContext_OntoOutboundRequest_AcrossBoundary()
+    {
+        var accessor = new HttpContextAccessor();
+        var httpContext = new DefaultHttpContext();
+        accessor.HttpContext = httpContext;
+        AimockHeaderPolicy.HttpContextAccessor = accessor;
+
+        // SSE pump captures context BEFORE the header is stashed.
+        var capturedAtResponseStart = ExecutionContext.Capture()!;
+
+        AimockHeaderContext.Set(httpContext, new Dictionary<string, string> { [AimockHeader] = Slug });
+
+        // Build a real outbound pipeline message and run it through the policy
+        // inside the captured context (mimicking the SSE-pump outbound call).
+        var policy = new AimockHeaderPolicy();
+        var pipeline = ClientPipeline.Create();
+        using var message = pipeline.CreateMessage();
+        message.Request.Method = "POST";
+        message.Request.Uri = new Uri("http://localhost:1/v1/chat/completions");
+
+        // The header policy at index 0, followed by a terminal no-op so
+        // ProcessNext has a successor to hand off to (and we never make a real
+        // network call).
+        var policies = new PipelinePolicy[] { policy, new TerminalPolicy() };
+
+        var tcs = new TaskCompletionSource();
+        ExecutionContext.Run(capturedAtResponseStart, _ =>
+        {
+            policy.Process(message, policies, 0);
+            tcs.SetResult();
+        }, null);
+        await tcs.Task;
+
+        Assert.True(message.Request.Headers.TryGetValue(AimockHeader, out var forwarded));
+        Assert.Equal(Slug, forwarded);
+    }
+
+    // Terminal pipeline policy: does nothing (does not call ProcessNext), so the
+    // policy chain stops here without making a real network request.
+    private sealed class TerminalPolicy : PipelinePolicy
+    {
+        public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+        {
+        }
+
+        public override ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+            => ValueTask.CompletedTask;
+    }
+}

showcase/integrations/ms-agent-dotnet/agent/tests/CvdiagEmissionTests.cs

@@ -0,0 +1,184 @@
+using System.Text.Json;
+using Copilotkit.Showcase.Cvdiag;
+using Xunit;
+
+namespace MsAgentDotnet.AgentTests;
+
+// Red-green proof for the L1-F backend CVDIAG instrumentation (spec §3).
+//
+// RED (before CvdiagBackend existed): the type does not compile / the 11
+// boundary emit methods do not exist, so this suite fails to build.
+// GREEN: CvdiagBackend, armed via CVDIAG_BACKEND_EMITTER=on, emits each of the
+// 11 backend boundaries, and the backend.error.caught path scrubs PII from the
+// exception message.
+//
+// We capture stdout (the emitter writes one single-line JSON per event to
+// Console.Out) and assert the boundary set + scrub behavior. The PocketBase
+// background write is disabled (no PbWriteUrl) so the test never touches the
+// network.
+//
+// These tests redirect Console.Out to capture the emitter's stdout. xUnit does
+// not parallelize tests within a single class, but other test classes could run
+// concurrently and write to the shared Console — so the suite is pinned to a
+// non-parallel collection to keep the capture deterministic.
+[CollectionDefinition("CvdiagStdout", DisableParallelization = true)]
+public sealed class CvdiagStdoutCollection { }
+
+[Collection("CvdiagStdout")]
+public class CvdiagEmissionTests
+{
+    private static IReadOnlyDictionary<string, string?> ArmedEnv() => new Dictionary<string, string?>
+    {
+        ["CVDIAG_BACKEND_EMITTER"] = "on",
+        // DEBUG tier so EVERY backend boundary is included — backend.sse.event is
+        // debug-tier-only in the §6 tier matrix. DEBUG fail-closes unless the env
+        // is non-production AND an allow-list is set, so satisfy both here.
+        ["CVDIAG_DEBUG"] = "1",
+        ["SHOWCASE_ENV"] = "development",
+        ["CVDIAG_DEBUG_ALLOW_LIST"] = "gen-ui-chat",
+    };
+
+    private static CvdiagBackend.RequestContext Ctx() => new()
+    {
+        Slug = "gen-ui-chat",
+        Demo = "default",
+        TestId = "017f22e2-79b0-7cc3-98c4-dc0c0c07398f",
+        IngressMs = 1000,
+    };
+
+    private sealed class StdoutCapture : IDisposable
+    {
+        private readonly System.IO.TextWriter _original;
+        private readonly System.IO.StringWriter _buffer = new();
+        public StdoutCapture()
+        {
+            _original = Console.Out;
+            Console.SetOut(_buffer);
+        }
+        public string Text => _buffer.ToString();
+        public void Dispose() => Console.SetOut(_original);
+    }
+
+    private static List<string> Boundaries(string stdout)
+    {
+        var found = new List<string>();
+        foreach (var line in stdout.Split('\n', StringSplitOptions.RemoveEmptyEntries))
+        {
+            try
+            {
+                using var doc = JsonDocument.Parse(line);
+                if (doc.RootElement.TryGetProperty("boundary", out var b))
+                {
+                    found.Add(b.GetString()!);
+                }
+            }
+            catch
+            {
+                // non-JSON noise — ignore
+            }
+        }
+        return found;
+    }
+
+    // (1) All 11 backend boundaries fire for a synthetic agent invocation.
+    [Fact]
+    public void AllElevenBackendBoundaries_Fire_WhenArmed()
+    {
+        var backend = new CvdiagBackend(ArmedEnv());
+        Assert.True(backend.IsEnabled);
+        var ctx = Ctx();
+
+        using var cap = new StdoutCapture();
+
+        var http = new Microsoft.AspNetCore.Http.DefaultHttpContext();
+        http.Request.Method = "POST";
+        http.Request.Path = "/gen-ui-chat";
+
+        backend.EmitRequestIngress(ctx, http);
+        backend.EmitAgentEnter(ctx, "gen-ui-chat", "gpt-4o-mini");
+        backend.EmitLlmCallStart(ctx, "openai", "gpt-4o-mini", 128);
+        backend.EmitLlmCallHeartbeat(ctx, 10_000);
+        backend.EmitLlmCallResponse(ctx, "openai", "gpt-4o-mini", 256, 1500, null);
+        backend.EmitSseFirstByte(ctx, 350);
+        backend.EmitSseEvent(ctx, "message", 64, 0);
+        backend.EmitSseAborted(ctx, "client_disconnect", 1024);
+        backend.EmitAgentExit(ctx, "ok", 2000);
+        backend.EmitResponseComplete(ctx, 200, 4096, 2000, 5);
+        backend.EmitErrorCaught(ctx, new InvalidOperationException("boom"));
+
+        var boundaries = Boundaries(cap.Text);
+        var expected = new[]
+        {
+            "backend.request.ingress", "backend.agent.enter", "backend.llm.call.start",
+            "backend.llm.call.heartbeat", "backend.llm.call.response", "backend.sse.first_byte",
+            "backend.sse.event", "backend.sse.aborted", "backend.agent.exit",
+            "backend.response.complete", "backend.error.caught",
+        };
+        foreach (var b in expected)
+        {
+            Assert.Contains(b, boundaries);
+        }
+        Assert.Equal(11, expected.Length);
+    }
+
+    // (2) OFF by default: with no CVDIAG_BACKEND_EMITTER, the layer is a no-op.
+    [Fact]
+    public void Disabled_ByDefault_EmitsNothing()
+    {
+        var backend = new CvdiagBackend(new Dictionary<string, string?>());
+        Assert.False(backend.IsEnabled);
+
+        using var cap = new StdoutCapture();
+        var ctx = Ctx();
+        backend.EmitAgentEnter(ctx, "x", "y");
+        backend.EmitErrorCaught(ctx, new Exception("nope"));
+
+        Assert.Empty(Boundaries(cap.Text));
+    }
+
+    // (3) PII scrub: a secret-shaped token in the exception message is redacted.
+    [Fact]
+    public void ErrorCaught_ScrubsPii_FromMessage()
+    {
+        var backend = new CvdiagBackend(ArmedEnv());
+        var ctx = Ctx();
+
+        using var cap = new StdoutCapture();
+        backend.EmitErrorCaught(ctx,
+            new InvalidOperationException("upstream rejected key sk-test-1234567890 with Bearer abc123def456"));
+
+        var line = cap.Text.Split('\n', StringSplitOptions.RemoveEmptyEntries)
+            .First(l => l.Contains("backend.error.caught"));
+        Assert.DoesNotContain("sk-test-1234567890", line);
+        Assert.DoesNotContain("abc123def456", line);
+        Assert.Contains("[REDACTED]", line);
+    }
+
+    // (3b) Scrub helper directly (unit-level): bearer + sk- keys redacted, cap at 512B.
+    [Fact]
+    public void Scrub_RedactsSecrets_AndCaps()
+    {
+        Assert.Equal("[REDACTED]", CvdiagBackend.Scrub("sk-abcdefgh12345"));
+        Assert.DoesNotContain("topsecret", CvdiagBackend.Scrub("Bearer topsecret-token"));
+        var big = new string('x', 2000);
+        Assert.True(System.Text.Encoding.UTF8.GetByteCount(CvdiagBackend.Scrub(big)) <= 512);
+    }
+
+    // (3c) URL userinfo: a `scheme://user:pass@host` authority and the colon-less
+    // `scheme://token@host` form both leak credentials in connection-error text.
+    // Mirrors scrubSecrets' URL_USERINFO_REGEX (harness/src/cvdiag/scrub.ts).
+    [Fact]
+    public void Scrub_RedactsUrlUserinfo_AndBareToken()
+    {
+        var withPass = CvdiagBackend.Scrub("connect failed: https://user:pass@example.com/x");
+        Assert.DoesNotContain("user:pass", withPass);
+        Assert.DoesNotContain("pass@", withPass);
+        Assert.Contains("[REDACTED]@", withPass);
+        Assert.Contains("example.com", withPass); // host preserved
+
+        var bareToken = CvdiagBackend.Scrub("connect failed: https://ghp_token@example.com/x");
+        Assert.DoesNotContain("ghp_token", bareToken);
+        Assert.Contains("[REDACTED]@", bareToken);
+        Assert.Contains("example.com", bareToken); // host preserved
+    }
+}

showcase/integrations/ms-agent-dotnet/agent/tests/SharedStateAgent.Tests.csproj

@@ -0,0 +1,32 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net9.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <IsPackable>false</IsPackable>
+    <IsTestProject>true</IsTestProject>
+    <!-- The production project is Microsoft.NET.Sdk.Web and has <Program> as a partial class for WebApplicationFactory-style tests. We only care about SharedStateAgent shape checks, so disable default Web build items leaking in. -->
+    <RootNamespace>MsAgentDotnet.AgentTests</RootNamespace>
+    <AssemblyName>SharedStateAgent.Tests</AssemblyName>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.11.1" />
+    <PackageReference Include="xunit" Version="2.9.2" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="2.8.2" />
+  </ItemGroup>
+
+  <!-- Needed so the header-propagation tests can use DefaultHttpContext /
+       HttpContextAccessor (Microsoft.AspNetCore.Http types). The production
+       project is a Web SDK app, but a project reference does not flow the
+       ASP.NET shared framework, so reference it explicitly here. -->
+  <ItemGroup>
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\ProverbsAgent.csproj" />
+  </ItemGroup>
+
+</Project>

showcase/integrations/ms-agent-dotnet/agent/tests/SharedStateAgentStreamingTests.cs

@@ -0,0 +1,277 @@
+using System.Runtime.CompilerServices;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Xunit;
+
+using SSA = SharedStateAgent;
+
+namespace MsAgentDotnet.AgentTests;
+
+/// <summary>
+/// Tests covering the SharedStateAgent streaming path. Specifically that the
+/// caller-supplied IEnumerable&lt;ChatMessage&gt; is enumerated exactly once,
+/// so single-use iterators (e.g. yield-based generators) don't silently yield
+/// nothing on a second pass and lose user context on the summary request.
+/// </summary>
+public class SharedStateAgentStreamingTests
+{
+    // SharedStateAgent's ctor validates that JsonSerializerOptions can resolve
+    // JsonElement. Attach the reflection-based DefaultJsonTypeInfoResolver so
+    // the ctor's shape check succeeds (production uses the source-gen context).
+    private static JsonSerializerOptions CreateSerializerOptions() =>
+        new(JsonSerializerDefaults.Web)
+        {
+            TypeInfoResolver = new System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver(),
+        };
+
+
+    // Minimal AIAgent fake: records invocations + yields nothing. We don't care
+    // what the inner agent produces for the enumeration-count test; we just
+    // need the SharedStateAgent wrapper to call us and have us observe the
+    // `messages` IEnumerable.
+    private sealed class RecordingAgent : AIAgent
+    {
+        public int RunStreamingCalls { get; private set; }
+        public List<List<ChatMessage>> CapturedMessageSnapshots { get; } = new();
+
+        public override AgentThread GetNewThread() => throw new NotImplementedException();
+
+        public override AgentThread DeserializeThread(JsonElement serializedThread, JsonSerializerOptions? jsonSerializerOptions = null)
+            => throw new NotImplementedException();
+
+        public override Task<AgentRunResponse> RunAsync(IEnumerable<ChatMessage> messages, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default)
+        {
+            var list = messages.ToList();
+            CapturedMessageSnapshots.Add(list);
+            return Task.FromResult(new AgentRunResponse());
+        }
+
+        public override async IAsyncEnumerable<AgentRunResponseUpdate> RunStreamingAsync(
+            IEnumerable<ChatMessage> messages,
+            AgentThread? thread = null,
+            AgentRunOptions? options = null,
+            [EnumeratorCancellation] CancellationToken cancellationToken = default)
+        {
+            RunStreamingCalls++;
+            // Materialize the incoming messages to capture them. (The outer
+            // SharedStateAgent is expected to have already materialized them
+            // once — we don't re-enumerate the caller's original iterator.)
+            var snapshot = messages.ToList();
+            CapturedMessageSnapshots.Add(snapshot);
+            await Task.CompletedTask;
+            yield break;
+        }
+    }
+
+    // IEnumerable wrapper that records how many times GetEnumerator is called
+    // so tests can assert the expected enumeration count.
+    //
+    // NOTE: this tracker does NOT enforce a single-use contract at the
+    // iterator level — a second `GetEnumerator()` call still returns a fresh,
+    // valid enumerator over the same backing array. Tests must explicitly
+    // `Assert.Equal(1, messages.EnumerationCount)` to catch double-enumeration
+    // regressions. The name reflects what the type actually does (counts
+    // enumerations) rather than what it does not do (enforce single use).
+    private sealed class EnumerationCountingMessages : IEnumerable<ChatMessage>
+    {
+        private readonly ChatMessage[] _messages;
+        private int _enumerations;
+
+        public int EnumerationCount => _enumerations;
+
+        public EnumerationCountingMessages(params ChatMessage[] messages)
+        {
+            _messages = messages;
+        }
+
+        public IEnumerator<ChatMessage> GetEnumerator()
+        {
+            _enumerations++;
+            return ((IEnumerable<ChatMessage>)_messages).GetEnumerator();
+        }
+
+        System.Collections.IEnumerator System.Collections.IEnumerable.GetEnumerator() => GetEnumerator();
+    }
+
+    [Fact]
+    public async Task RunStreamingAsync_NoAgUiState_EnumeratesCallerMessagesOnce()
+    {
+        // When there's no AG-UI state attached, the non-structured path runs.
+        // Even here a naive implementation could accidentally enumerate twice
+        // (e.g. for logging). Verify we only enumerate the caller's iterator
+        // a single time — we then pass the materialized list to the inner
+        // agent.
+        var inner = new RecordingAgent();
+        var agent = new SSA(inner, CreateSerializerOptions());
+        var messages = new EnumerationCountingMessages(new ChatMessage(ChatRole.User, "hi"));
+
+        await foreach (var _ in agent.RunStreamingAsync(messages).ConfigureAwait(false))
+        {
+            // drain
+        }
+
+        Assert.Equal(1, messages.EnumerationCount);
+        Assert.Equal(1, inner.RunStreamingCalls);
+    }
+
+    [Fact]
+    public async Task RunStreamingAsync_WithSalesState_EnumeratesCallerMessagesOnce()
+    {
+        // With sales state attached, SharedStateAgent runs the two-pass
+        // structured-output flow: firstRunMessages and secondRunMessages both
+        // need the caller's message list. A previous bug enumerated `messages`
+        // for each of those appends — a yield-based generator would silently
+        // yield nothing on the second pass, and the summary request would run
+        // without user context.
+        var inner = new RecordingAgent();
+        var agent = new SSA(inner, CreateSerializerOptions());
+        var messages = new EnumerationCountingMessages(new ChatMessage(ChatRole.User, "update my pipeline"));
+
+        // Attach sales-shaped ag_ui_state so the structured-output path runs.
+        var statePayload = JsonDocument.Parse("{\"todos\":[{\"id\":\"a\",\"title\":\"Deal 1\"}]}").RootElement;
+        var chatOptions = new ChatOptions
+        {
+            AdditionalProperties = new AdditionalPropertiesDictionary
+            {
+                ["ag_ui_state"] = statePayload,
+            },
+        };
+        var options = new ChatClientAgentRunOptions { ChatOptions = chatOptions };
+
+        await foreach (var _ in agent.RunStreamingAsync(messages, options: options).ConfigureAwait(false))
+        {
+            // drain
+        }
+
+        // The critical assertion: caller's iterator was enumerated exactly
+        // once, regardless of how many times SharedStateAgent needs to compose
+        // derived message lists internally.
+        Assert.Equal(1, messages.EnumerationCount);
+    }
+
+    // Inner agent that emits a controllable sequence of text-only updates on
+    // the first RunStreamingAsync call and nothing on subsequent calls. Used
+    // to exercise the buffered-text cap and the deserialize-success paths.
+    private sealed class TextEmittingAgent : AIAgent
+    {
+        private readonly IReadOnlyList<string> _firstPassChunks;
+        private readonly string? _secondPassChunk;
+        private int _callCount;
+
+        public TextEmittingAgent(IReadOnlyList<string> firstPassChunks, string? secondPassChunk = null)
+        {
+            _firstPassChunks = firstPassChunks;
+            _secondPassChunk = secondPassChunk;
+        }
+
+        public override AgentThread GetNewThread() => throw new NotImplementedException();
+
+        public override AgentThread DeserializeThread(JsonElement serializedThread, JsonSerializerOptions? jsonSerializerOptions = null)
+            => throw new NotImplementedException();
+
+        public override Task<AgentRunResponse> RunAsync(IEnumerable<ChatMessage> messages, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default)
+            => Task.FromResult(new AgentRunResponse());
+
+        public override async IAsyncEnumerable<AgentRunResponseUpdate> RunStreamingAsync(
+            IEnumerable<ChatMessage> messages,
+            AgentThread? thread = null,
+            AgentRunOptions? options = null,
+            [EnumeratorCancellation] CancellationToken cancellationToken = default)
+        {
+            var call = Interlocked.Increment(ref _callCount);
+            var chunks = call == 1 ? _firstPassChunks : (_secondPassChunk is null ? Array.Empty<string>() : new[] { _secondPassChunk });
+            foreach (var chunk in chunks)
+            {
+                yield return new AgentRunResponseUpdate
+                {
+                    Role = ChatRole.Assistant,
+                    Contents = [new TextContent(chunk)],
+                };
+            }
+            await Task.CompletedTask;
+        }
+    }
+
+    [Fact]
+    public async Task RunStreamingAsync_BufferedTextCap_DropsUpdatesBeyondCap()
+    {
+        // Pathological first-pass response: emit many text chunks whose total
+        // length exceeds MaxBufferedTextChars. The deserialize will fail
+        // (plain text is not valid JSON for SalesStateSnapshot), so we fall
+        // back to replaying the buffered text updates. The total replayed
+        // character count must NOT exceed the cap plus the largest single
+        // chunk size — anything beyond that signals the cap isn't enforced.
+        const int chunkSize = 10_000;
+        const int chunkCount = 150; // 1.5 MB total — exceeds the 1 MB cap.
+        var chunks = Enumerable.Range(0, chunkCount).Select(_ => new string('x', chunkSize)).ToArray();
+        var inner = new TextEmittingAgent(chunks);
+        var agent = new SSA(inner, CreateSerializerOptions());
+
+        var statePayload = JsonDocument.Parse("{\"todos\":[{\"id\":\"a\",\"title\":\"Deal 1\"}]}").RootElement;
+        var chatOptions = new ChatOptions
+        {
+            AdditionalProperties = new AdditionalPropertiesDictionary
+            {
+                ["ag_ui_state"] = statePayload,
+            },
+        };
+        var options = new ChatClientAgentRunOptions { ChatOptions = chatOptions };
+
+        var totalReplayedChars = 0;
+        await foreach (var update in agent.RunStreamingAsync(new[] { new ChatMessage(ChatRole.User, "hi") }, options: options))
+        {
+            foreach (var c in update.Contents.OfType<TextContent>())
+            {
+                totalReplayedChars += c.Text?.Length ?? 0;
+            }
+        }
+
+        // Replay must be bounded strictly by the cap. The buffering admission
+        // check is pre-increment: a chunk that WOULD cross the cap is rejected
+        // in full (no partial admission), and already-admitted chunks are
+        // kept. So the replayed total is always <= MaxBufferedTextChars — no
+        // slack. If enforcement ever becomes post-increment (admit first, then
+        // check), the bound would loosen to <= MaxBufferedTextChars + chunkSize
+        // and this assertion would need to relax accordingly.
+        Assert.True(
+            totalReplayedChars <= SSA.MaxBufferedTextChars,
+            $"Replayed {totalReplayedChars} chars; cap is {SSA.MaxBufferedTextChars}.");
+    }
+
+    [Fact]
+    public async Task RunStreamingAsync_DeserializeSuccess_NoSalesData_SkipsDataContentEmit()
+    {
+        // First-pass produces a syntactically valid SalesStateSnapshot with
+        // an empty todos array. TryDeserialize succeeds, but
+        // ShouldEmitStateSnapshot returns false because todos is empty, so no
+        // DataContent is emitted. The second pass (for the summary) is
+        // allowed to run; we assert the absence of DataContent across the
+        // full output rather than counting exact updates.
+        var firstPass = new[] { "{\"todos\":[]}" };
+        var inner = new TextEmittingAgent(firstPass, secondPassChunk: "ok");
+        var agent = new SSA(inner, CreateSerializerOptions());
+
+        var statePayload = JsonDocument.Parse("{\"todos\":[{\"id\":\"a\",\"title\":\"Deal 1\"}]}").RootElement;
+        var chatOptions = new ChatOptions
+        {
+            AdditionalProperties = new AdditionalPropertiesDictionary
+            {
+                ["ag_ui_state"] = statePayload,
+            },
+        };
+        var options = new ChatClientAgentRunOptions { ChatOptions = chatOptions };
+
+        var hasDataContent = false;
+        await foreach (var update in agent.RunStreamingAsync(new[] { new ChatMessage(ChatRole.User, "hi") }, options: options))
+        {
+            if (update.Contents.Any(c => c is DataContent))
+            {
+                hasDataContent = true;
+            }
+        }
+
+        Assert.False(hasDataContent, "Empty-todos snapshot must not be emitted as DataContent.");
+    }
+}

showcase/integrations/ms-agent-dotnet/agent/tests/SharedStateAgentTests.cs

@@ -0,0 +1,65 @@
+using System.Text.Json;
+using Xunit;
+
+// Alias the production type (declared in the default/global namespace) so the
+// test file doesn't need to repeat `global::SharedStateAgent` at every call
+// site. Access is via InternalsVisibleTo on the production csproj.
+using SSA = SharedStateAgent;
+
+namespace MsAgentDotnet.AgentTests;
+
+public class StateContainsSalesDataTests
+{
+    private static JsonElement Parse(string json) => JsonDocument.Parse(json).RootElement;
+
+    public static IEnumerable<object[]> Cases()
+    {
+        // Case 1: state is a JSON null value (ValueKind == Null)
+        yield return new object[] { "JsonNullValue", Parse("null"), false };
+
+        // Case 2: state is an array (not an object)
+        yield return new object[] { "TopLevelArray", Parse("[1,2,3]"), false };
+
+        // Case 3: state is an object but todos is missing
+        yield return new object[] { "TodosMissing", Parse("{\"other\":1}"), false };
+
+        // Case 4: todos is an empty array
+        yield return new object[] { "TodosEmptyArray", Parse("{\"todos\":[]}"), false };
+
+        // Case 5: todos is a non-array value (an object)
+        yield return new object[] { "TodosAsObject", Parse("{\"todos\":{}}"), false };
+
+        // Case 6: todos is a non-array primitive (a string)
+        yield return new object[] { "TodosAsString", Parse("{\"todos\":\"nope\"}"), false };
+
+        // Case 7: todos is an array with non-object elements
+        yield return new object[] { "TodosArrayOfPrimitives", Parse("{\"todos\":[1,2,3]}"), false };
+
+        // Case 8: todos is populated with object elements
+        yield return new object[]
+        {
+            "TodosPopulatedWithObjects",
+            Parse("{\"todos\":[{\"id\":\"a\",\"title\":\"T1\",\"stage\":\"prospect\"}]}"),
+            true,
+        };
+    }
+
+    [Theory]
+    [MemberData(nameof(Cases))]
+    public void StateContainsSalesData_ReturnsExpected(string label, JsonElement state, bool expected)
+    {
+        // label is included for test-runner readability only; silence unused warnings.
+        _ = label;
+        var actual = SSA.StateContainsSalesData(state);
+        Assert.Equal(expected, actual);
+    }
+
+    [Fact]
+    public void StateContainsSalesData_MissingState_UndefinedValueKind_ReturnsFalse()
+    {
+        // JsonElement default (ValueKind == Undefined) simulates "no state attached".
+        var undefined = default(JsonElement);
+        Assert.Equal(JsonValueKind.Undefined, undefined.ValueKind);
+        Assert.False(SSA.StateContainsSalesData(undefined));
+    }
+}

showcase/integrations/ms-agent-dotnet/agent/tests/TypesTests.cs

@@ -0,0 +1,448 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.Logging.Abstractions;
+using Xunit;
+
+namespace MsAgentDotnet.AgentTests;
+
+/// <summary>
+/// Shape and serialization tests for <see cref="SalesTodo"/>, <see cref="SalesState"/>,
+/// <see cref="SalesStateSnapshot"/>, and <see cref="FlightInfo"/>. These types replaced
+/// a primitive-obsession implementation (free-form string stages, int money values,
+/// parallel <c>Status</c> + <c>StatusColor</c> strings) with typed enums, decimals,
+/// and derived properties; the tests pin the wire format so downstream clients
+/// don't silently break.
+/// </summary>
+public class SalesTodoShapeTests
+{
+    private static JsonSerializerOptions NewOptions()
+    {
+        var opts = new JsonSerializerOptions();
+        opts.Converters.Add(new JsonStringEnumConverter());
+        return opts;
+    }
+
+    [Fact]
+    public void SalesTodo_Stage_SerializesAsEnumMemberName()
+    {
+        // Stage is a typed SalesStage enum; it serializes as the enum member
+        // name so both callers and the model see a closed set of legal values.
+        var todo = new SalesTodo { Id = "t1", Stage = SalesStage.Qualified, Value = 1000m };
+
+        var json = JsonSerializer.Serialize(todo, NewOptions());
+
+        Assert.Contains("\"stage\":\"Qualified\"", json);
+    }
+
+    [Fact]
+    public void SalesTodo_Value_SerializesAsDecimalNumber()
+    {
+        // Value is decimal (money). Verify it round-trips as a JSON number
+        // (not a quoted string) and preserves fractional precision.
+        var todo = new SalesTodo { Id = "t2", Value = 1234.56m };
+
+        var json = JsonSerializer.Serialize(todo, NewOptions());
+        var doc = JsonDocument.Parse(json).RootElement;
+
+        Assert.Equal(JsonValueKind.Number, doc.GetProperty("value").ValueKind);
+        Assert.Equal(1234.56m, doc.GetProperty("value").GetDecimal());
+    }
+
+    [Fact]
+    public void SalesTodo_Value_Negative_Throws()
+    {
+        // Value is money; negative values are not a legal business state.
+        // The init accessor rejects them with ArgumentOutOfRangeException.
+        Assert.Throws<ArgumentOutOfRangeException>(() =>
+            new SalesTodo { Id = "neg", Value = -1000m });
+    }
+
+    [Fact]
+    public void SalesTodo_Value_Zero_Allowed()
+    {
+        // Zero is a legal amount (e.g. an unpriced prospect).
+        var todo = new SalesTodo { Id = "zero", Value = 0m };
+        Assert.Equal(0m, todo.Value);
+    }
+
+    [Fact]
+    public void SalesTodo_DueDate_SerializesAsIsoDate()
+    {
+        // DueDate is a nullable DateOnly; System.Text.Json emits DateOnly as
+        // the ISO-8601 YYYY-MM-DD form.
+        var todo = new SalesTodo { Id = "t3", DueDate = new DateOnly(2026, 4, 20) };
+
+        var json = JsonSerializer.Serialize(todo, NewOptions());
+
+        Assert.Contains("\"dueDate\":\"2026-04-20\"", json);
+    }
+
+    [Fact]
+    public void SalesTodo_DueDate_NullIsSerializedAsJsonNull()
+    {
+        var todo = new SalesTodo { Id = "t4", DueDate = null };
+
+        var json = JsonSerializer.Serialize(todo, NewOptions());
+
+        Assert.Contains("\"dueDate\":null", json);
+    }
+
+    [Fact]
+    public void SalesTodo_RequiredId_CompilesAndRoundTrips()
+    {
+        // The `required` keyword forces callers to explicitly provide an Id.
+        // This test is mostly a compile-time anchor; at runtime we just
+        // confirm the value we set round-trips unchanged.
+        var todo = new SalesTodo { Id = "explicit-id" };
+        var json = JsonSerializer.Serialize(todo, NewOptions());
+        var round = JsonSerializer.Deserialize<SalesTodo>(json, NewOptions());
+
+        Assert.NotNull(round);
+        Assert.Equal("explicit-id", round!.Id);
+    }
+
+    [Fact]
+    public void SalesTodo_NewPending_AssignsNonEmptyGuidId()
+    {
+        // NewPending is the explicit factory for "server should assign an
+        // id". It generates a 16-hex-char id so callers never have to know
+        // about the empty-string sentinel that ReplaceTodos backfills.
+        var todo = SalesTodo.NewPending(title: "deal");
+
+        Assert.False(string.IsNullOrEmpty(todo.Id));
+        Assert.Equal(16, todo.Id.Length);
+        Assert.Equal("deal", todo.Title);
+    }
+
+    [Fact]
+    public void SalesTodo_Currency_SerializesAsEnumMemberName()
+    {
+        var todo = new SalesTodo { Id = "t5", Currency = Currency.EUR };
+
+        var json = JsonSerializer.Serialize(todo, NewOptions());
+
+        Assert.Contains("\"currency\":\"EUR\"", json);
+    }
+
+    [Theory]
+    [InlineData(SalesStage.Prospect, false)]
+    [InlineData(SalesStage.Qualified, false)]
+    [InlineData(SalesStage.Proposal, false)]
+    [InlineData(SalesStage.Negotiation, false)]
+    [InlineData(SalesStage.ClosedWon, true)]
+    [InlineData(SalesStage.ClosedLost, true)]
+    public void SalesTodo_Completed_IsDerivedFromStage(SalesStage stage, bool expectedCompleted)
+    {
+        // Completed used to be an independent bool that could contradict
+        // Stage (e.g. ClosedWon + Completed=false). It's now a computed
+        // property so the pair cannot disagree.
+        var todo = new SalesTodo { Id = "d", Stage = stage };
+        Assert.Equal(expectedCompleted, todo.Completed);
+    }
+}
+
+public class SalesStateEncapsulationTests
+{
+    [Fact]
+    public void SalesState_Todos_IsReadOnly_AtCompileTime()
+    {
+        // The Todos property is IReadOnlyList<SalesTodo> with no public
+        // setter. Verified via reflection so a regression (adding a setter
+        // or reverting to a mutable List<>) breaks the build-time contract.
+        var prop = typeof(SalesState).GetProperty(nameof(SalesState.Todos));
+        Assert.NotNull(prop);
+        Assert.Equal(typeof(IReadOnlyList<SalesTodo>), prop!.PropertyType);
+        Assert.Null(prop.SetMethod);
+    }
+
+    [Fact]
+    public void SalesState_ReplaceTodos_BackfillsEmptyIds()
+    {
+        // ReplaceTodos is the single writer for SalesState.Todos. Empty-id
+        // todos (the documented sentinel for "server assigns") are backfilled
+        // with a freshly generated Guid-derived id; non-empty ids are kept.
+        var state = new SalesState();
+        state.ReplaceTodos(new[]
+        {
+            new SalesTodo { Id = "", Title = "A" },
+            new SalesTodo { Id = "keep-me", Title = "B" },
+        });
+
+        Assert.Equal(2, state.Todos.Count);
+        Assert.False(string.IsNullOrEmpty(state.Todos[0].Id));
+        Assert.NotEqual("", state.Todos[0].Id);
+        // 16 hex chars = 64 bits of entropy — safe for demo scale.
+        Assert.Equal(16, state.Todos[0].Id.Length);
+        Assert.Equal("keep-me", state.Todos[1].Id);
+    }
+
+    [Fact]
+    public void SalesState_ReplaceTodos_PublishedListIsReadOnly()
+    {
+        // The published list must be IReadOnlyList and must NOT alias the
+        // caller's input collection, so external mutation after publish
+        // cannot leak into the state.
+        var state = new SalesState();
+        var source = new List<SalesTodo>
+        {
+            new() { Id = "x", Title = "X" },
+        };
+        state.ReplaceTodos(source);
+
+        source.Clear();
+        Assert.Single(state.Todos);
+    }
+
+    [Fact]
+    public void SalesStateSnapshot_IsRecordWrappingReadOnlyList()
+    {
+        // SalesStateSnapshot was previously a near-duplicate mutable class.
+        // It is now an immutable record wrapping IReadOnlyList<SalesTodo>.
+        var snapshot = new SalesStateSnapshot(new[]
+        {
+            new SalesTodo { Id = "a", Title = "A" },
+        });
+
+        Assert.Single(snapshot.Todos);
+        Assert.Equal("a", snapshot.Todos[0].Id);
+
+        // Records provide value-based equality.
+        var same = snapshot with { };
+        Assert.Equal(snapshot, same);
+    }
+
+    [Fact]
+    public void SalesStateSnapshot_SerializesTodosKey()
+    {
+        // The wire-format key is lowercase "todos" via JsonPropertyName,
+        // even without a camelCase naming policy.
+        var snapshot = new SalesStateSnapshot(Array.Empty<SalesTodo>());
+        var opts = new JsonSerializerOptions();
+        opts.Converters.Add(new JsonStringEnumConverter());
+        var json = JsonSerializer.Serialize(snapshot, opts);
+
+        Assert.Contains("\"todos\":", json);
+    }
+}
+
+public class FlightInfoShapeTests
+{
+    private static JsonSerializerOptions NewOptions()
+    {
+        var opts = new JsonSerializerOptions();
+        opts.Converters.Add(new JsonStringEnumConverter());
+        return opts;
+    }
+
+    [Fact]
+    public void FlightInfo_StatusColor_DerivedFromStatus_OnTimeGreen()
+    {
+        var flight = new FlightInfo { Status = FlightStatus.OnTime };
+        Assert.Equal("green", flight.StatusColor);
+    }
+
+    [Theory]
+    [InlineData(FlightStatus.OnTime, "green")]
+    [InlineData(FlightStatus.Delayed, "yellow")]
+    [InlineData(FlightStatus.Cancelled, "red")]
+    [InlineData(FlightStatus.Boarding, "blue")]
+    public void FlightInfo_StatusColor_MatchesStatus(FlightStatus status, string expectedColor)
+    {
+        // StatusColor is derived from Status — the pair cannot disagree.
+        var flight = new FlightInfo { Status = status };
+        Assert.Equal(expectedColor, flight.StatusColor);
+    }
+
+    [Fact]
+    public void FlightInfo_Price_IsDecimal_Currency_IsEnum()
+    {
+        // Price is a decimal (money) + Currency is a typed enum, replacing
+        // the old "$342" + "USD" pair.
+        var flight = new FlightInfo { Price = 342.00m, Currency = Currency.USD };
+        var opts = NewOptions();
+
+        var json = JsonSerializer.Serialize(flight, opts);
+        var doc = JsonDocument.Parse(json).RootElement;
+
+        Assert.Equal(JsonValueKind.Number, doc.GetProperty("price").ValueKind);
+        Assert.Equal("USD", doc.GetProperty("currency").GetString());
+    }
+}
+
+/// <summary>
+/// Exercises the <see cref="SalesAgentFactory.BuildA2uiResponseFromContent"/>
+/// helper — the content-processing stage of GenerateA2ui, which is the only
+/// part reachable without a live OpenAI client. Each error branch
+/// (JsonException, shape mismatch, malformed components, shape deserialize)
+/// is covered with a controlled input string so regressions that leak raw
+/// ex.Message or swallow errors silently fail loudly.
+/// </summary>
+public class GenerateA2uiErrorBranchTests
+{
+    private const string ErrorId = "test1234";
+
+    private static Microsoft.Extensions.Logging.ILogger NewLogger()
+        => NullLogger.Instance;
+
+    private static JsonElement ParseToElement(object payload)
+    {
+        var json = payload is string value ? value : JsonSerializer.Serialize(payload);
+        return JsonDocument.Parse(json).RootElement;
+    }
+
+    [Fact]
+    public void MalformedJson_ReturnsStructuredError_Category_MalformedLlmOutput()
+    {
+        // Input isn't valid JSON at all — JsonDocument.Parse throws
+        // JsonException on the very first try. Error category and errorId
+        // must be present; no raw exception message.
+        var output = SalesAgentFactory.BuildA2uiResponseFromContent(
+            "This is not JSON at all",
+            ErrorId,
+            NewLogger());
+
+        var doc = ParseToElement(output);
+        Assert.Equal("malformed_llm_output", doc.GetProperty("error").GetString());
+        Assert.Equal(ErrorId, doc.GetProperty("errorId").GetString());
+        Assert.False(string.IsNullOrEmpty(doc.GetProperty("message").GetString()));
+        Assert.False(string.IsNullOrEmpty(doc.GetProperty("remediation").GetString()));
+    }
+
+    [Fact]
+    public void JsonButNotObject_ReturnsStructuredError()
+    {
+        // JSON parses, but the root is an array, not the expected object.
+        var output = SalesAgentFactory.BuildA2uiResponseFromContent(
+            "[1, 2, 3]",
+            ErrorId,
+            NewLogger());
+
+        var doc = ParseToElement(output);
+        Assert.Equal("malformed_llm_output", doc.GetProperty("error").GetString());
+        Assert.Equal(ErrorId, doc.GetProperty("errorId").GetString());
+    }
+
+    [Fact]
+    public void MissingComponentsArray_ReturnsStructuredError()
+    {
+        // Object is otherwise valid but 'components' is missing entirely.
+        var output = SalesAgentFactory.BuildA2uiResponseFromContent(
+            "{\"surfaceId\":\"s1\"}",
+            ErrorId,
+            NewLogger());
+
+        var doc = ParseToElement(output);
+        Assert.Equal("malformed_llm_output", doc.GetProperty("error").GetString());
+    }
+
+    [Fact]
+    public void ComponentsNotArray_ReturnsStructuredError()
+    {
+        // 'components' exists but is a string rather than an array.
+        var output = SalesAgentFactory.BuildA2uiResponseFromContent(
+            "{\"components\":\"not-an-array\"}",
+            ErrorId,
+            NewLogger());
+
+        var doc = ParseToElement(output);
+        Assert.Equal("malformed_llm_output", doc.GetProperty("error").GetString());
+    }
+
+    [Fact]
+    public void WellFormedInput_ReturnsOperationsPayload()
+    {
+        // Happy path: valid shape produces the a2ui_operations envelope with
+        // the nested A2UI v0.9 operations expected by @ag-ui/a2ui-middleware:
+        // createSurface, updateComponents, and (when data present) updateDataModel.
+        var output = SalesAgentFactory.BuildA2uiResponseFromContent(
+            "{\"surfaceId\":\"ds\",\"catalogId\":\"copilotkit://c\",\"components\":[{\"id\":\"root\",\"component\":\"Row\"}],\"data\":{\"k\":1}}",
+            ErrorId,
+            NewLogger());
+
+        var doc = ParseToElement(output);
+        var ops = doc.GetProperty("a2ui_operations");
+        Assert.Equal(JsonValueKind.Array, ops.ValueKind);
+        Assert.Equal(3, ops.GetArrayLength());
+        Assert.Equal("v0.9", ops[0].GetProperty("version").GetString());
+        Assert.Equal("ds", ops[0].GetProperty("createSurface").GetProperty("surfaceId").GetString());
+        Assert.Equal("copilotkit://c", ops[0].GetProperty("createSurface").GetProperty("catalogId").GetString());
+        Assert.Equal("ds", ops[1].GetProperty("updateComponents").GetProperty("surfaceId").GetString());
+        Assert.Equal(JsonValueKind.Array, ops[1].GetProperty("updateComponents").GetProperty("components").ValueKind);
+        Assert.Equal("ds", ops[2].GetProperty("updateDataModel").GetProperty("surfaceId").GetString());
+        Assert.Equal("/", ops[2].GetProperty("updateDataModel").GetProperty("path").GetString());
+        Assert.Equal(1, ops[2].GetProperty("updateDataModel").GetProperty("value").GetProperty("k").GetInt32());
+    }
+
+    [Fact]
+    public void WellFormedInput_NoData_OmitsUpdateDataModel()
+    {
+        // Data is optional; when absent we emit only createSurface and
+        // updateComponents.
+        var output = SalesAgentFactory.BuildA2uiResponseFromContent(
+            "{\"components\":[{\"id\":\"root\",\"component\":\"Row\"}]}",
+            ErrorId,
+            NewLogger());
+
+        var doc = ParseToElement(output);
+        var ops = doc.GetProperty("a2ui_operations");
+        Assert.Equal(2, ops.GetArrayLength());
+    }
+
+    [Fact]
+    public void StructuredError_HasExactlyTheContractKeys()
+    {
+        // Pin the wire contract: clients and the LLM both rely on the four
+        // keys (error, message, remediation, errorId). A regression to raw
+        // ex.Message would drop remediation/errorId and this test would fail.
+        var output = SalesAgentFactory.StructuredError("cat", "msg", "rem", "eid");
+        var doc = ParseToElement(output);
+
+        var keys = new HashSet<string>();
+        foreach (var prop in doc.EnumerateObject())
+        {
+            keys.Add(prop.Name);
+        }
+
+        Assert.Equal(
+            new HashSet<string> { "error", "message", "remediation", "errorId" },
+            keys);
+    }
+
+    [Fact]
+    public void NullContent_ReturnsStructuredError_EmptyLlmOutput()
+    {
+        // result.Text from the upstream chat client can legitimately be null
+        // (content filter tripped, empty completion, model refusal). The old
+        // code propagated that straight into BuildA2uiResponseFromContent,
+        // which did ArgumentNullException.ThrowIfNull(content) — escaping as
+        // an uncaught NRE that broke the structured-error contract. Now the
+        // helper returns a structured empty_llm_output error instead.
+        var output = SalesAgentFactory.BuildA2uiResponseFromContent(
+            null,
+            ErrorId,
+            NewLogger());
+
+        var doc = ParseToElement(output);
+        Assert.Equal("empty_llm_output", doc.GetProperty("error").GetString());
+        Assert.Equal(ErrorId, doc.GetProperty("errorId").GetString());
+        Assert.False(string.IsNullOrEmpty(doc.GetProperty("message").GetString()));
+        Assert.False(string.IsNullOrEmpty(doc.GetProperty("remediation").GetString()));
+    }
+
+    [Fact]
+    public void EmptyContent_ReturnsStructuredError_EmptyLlmOutput()
+    {
+        // Empty string is treated the same as null: the upstream produced no
+        // usable text content. JsonDocument.Parse("") would throw JsonException
+        // and be reported as malformed_llm_output, which is less accurate — an
+        // empty string isn't malformed, it's absent. Guard it up-front.
+        var output = SalesAgentFactory.BuildA2uiResponseFromContent(
+            string.Empty,
+            ErrorId,
+            NewLogger());
+
+        var doc = ParseToElement(output);
+        Assert.Equal("empty_llm_output", doc.GetProperty("error").GetString());
+        Assert.Equal(ErrorId, doc.GetProperty("errorId").GetString());
+    }
+}