docs: replace stale observability migration guide with current PR's only relevant migration

The old guide documented the move away from setup_observability(otlp_endpoint=...)
which was an earlier-release API change unrelated to this PR and stale enough that
it's more confusing than helpful at this point. Replace it with a short note on the
single migration this PR introduces: callers of
enable_instrumentation(enable_sensitive_data=True) should switch to
enable_sensitive_telemetry(). Cross-link to the Disabling instrumentation section
for the rare 'force on without enabling sensitive data' use case where
enable_instrumentation() still applies.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

.github/workflows/merge-gatekeeper.yml

@@ -2,7 +2,7 @@ name: Merge Gatekeeper
 
 on:
   pull_request:
-    branches: [ "main", "feature*" ]
+    branches: ["main", "feature*"]
   merge_group:
     branches: ["main"]
 
@@ -13,23 +13,105 @@ concurrency:
 jobs:
   merge-gatekeeper:
     runs-on: ubuntu-latest
-    # Restrict permissions of the GITHUB_TOKEN.
-    # Docs: https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs
     permissions:
       checks: read
       statuses: read
     steps:
-      - name: Run Merge Gatekeeper
-        # NOTE: v1 is updated to reflect the latest v1.x.y. Please use any tag/branch that suits your needs:
-        #       https://github.com/upsidr/merge-gatekeeper/tags
-        #       https://github.com/upsidr/merge-gatekeeper/branches
-        uses: upsidr/merge-gatekeeper@v1
+      - name: Wait for required checks
         if: github.event_name == 'pull_request'
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-          timeout: 3600
-          interval: 30
+        uses: actions/github-script@v8
+        env:
+          TIMEOUT_SECONDS: "3600"
+          INTERVAL_SECONDS: "30"
+          SELF_JOB_NAME: ${{ github.job }}
           # "Cleanup artifacts", "Agent", "Prepare", and "Upload results" are check runs
           # created by an org-level GitHub App (MSDO), not by any workflow in this repo.
           # They are outside our control and their transient failures should not block merges.
-          ignored: CodeQL,CodeQL analysis (csharp),Cleanup artifacts,Agent,Prepare,Upload results
+          IGNORED_NAMES: "CodeQL,CodeQL analysis (csharp),Cleanup artifacts,Agent,Prepare,Upload results"
+        with:
+          script: |
+            const timeoutSeconds = Number(process.env.TIMEOUT_SECONDS);
+            const intervalSeconds = Number(process.env.INTERVAL_SECONDS);
+            const selfName = process.env.SELF_JOB_NAME;
+            const ignored = new Set(
+              process.env.IGNORED_NAMES.split(',').map((s) => s.trim()).filter(Boolean),
+            );
+
+            const sha = context.payload.pull_request.head.sha;
+            const { owner, repo } = context.repo;
+
+            const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+            // Mirrors upsidr/merge-gatekeeper: merge combined-statuses and check-runs
+            // for the PR head SHA, with combined-statuses winning on name collision.
+            async function collectChecks() {
+              const merged = new Map();
+
+              const combined = await github.rest.repos.getCombinedStatusForRef({
+                owner, repo, ref: sha, per_page: 100,
+              });
+              for (const s of combined.data.statuses ?? []) {
+                if (!merged.has(s.context)) {
+                  // Combined-status states: success | pending | error | failure
+                  merged.set(s.context, { name: s.context, state: s.state });
+                }
+              }
+
+              const runs = await github.paginate(github.rest.checks.listForRef, {
+                owner, repo, ref: sha, per_page: 100,
+              });
+              for (const r of runs) {
+                if (merged.has(r.name)) continue;
+                let state;
+                if (r.status !== 'completed') {
+                  state = 'pending';
+                } else if (r.conclusion === 'skipped') {
+                  continue; // Skipped runs are dropped, matching the original action.
+                } else if (r.conclusion === 'success' || r.conclusion === 'neutral') {
+                  state = 'success';
+                } else {
+                  // cancelled | timed_out | action_required | stale | failure
+                  state = 'error';
+                }
+                merged.set(r.name, { name: r.name, state });
+              }
+
+              return [...merged.values()];
+            }
+
+            function evaluate(entries) {
+              const failed = [];
+              const pending = [];
+              const succeeded = [];
+              for (const e of entries) {
+                if (e.name === selfName || ignored.has(e.name)) continue;
+                if (e.state === 'success') succeeded.push(e.name);
+                else if (e.state === 'error' || e.state === 'failure') failed.push(e.name);
+                else pending.push(e.name);
+              }
+              return { failed, pending, succeeded };
+            }
+
+            const deadline = Date.now() + timeoutSeconds * 1000;
+            for (;;) {
+              const entries = await collectChecks();
+              const { failed, pending, succeeded } = evaluate(entries);
+
+              core.info(
+                `succeeded=${succeeded.length} pending=${pending.length} failed=${failed.length}`,
+              );
+              if (failed.length) {
+                core.setFailed(`Failing checks: ${failed.join(', ')}`);
+                return;
+              }
+              if (pending.length === 0) {
+                core.info(`All required checks passed: ${succeeded.join(', ') || '(none)'}`);
+                return;
+              }
+              if (Date.now() > deadline) {
+                core.setFailed(`Timed out waiting for: ${pending.join(', ')}`);
+                return;
+              }
+              core.info(`Waiting on (${pending.length}): ${pending.slice(0, 10).join(', ')}${pending.length > 10 ? ', …' : ''}`);
+              await sleep(intervalSeconds * 1000);
+            }

.gitignore

@@ -246,3 +246,5 @@ dotnet/filtered-*.slnx
 # Local tool state
 .omc/
 .omx/
+
+**/issues/

dotnet/agent-framework-dotnet.slnx

@@ -242,6 +242,7 @@
     <Project Path="samples/03-workflows/Declarative/HostedWorkflow/HostedWorkflow.csproj" />
     <Project Path="samples/03-workflows/Declarative/InputArguments/InputArguments.csproj" />
     <Project Path="samples/03-workflows/Declarative/InvokeFunctionTool/InvokeFunctionTool.csproj" />
+    <Project Path="samples/03-workflows/Declarative/InvokeFoundryToolboxMcp/InvokeFoundryToolboxMcp.csproj" />
     <Project Path="samples/03-workflows/Declarative/InvokeHttpRequest/InvokeHttpRequest.csproj" />
     <Project Path="samples/03-workflows/Declarative/InvokeMcpTool/InvokeMcpTool.csproj" />
     <Project Path="samples/03-workflows/Declarative/Marketing/Marketing.csproj" />
@@ -298,6 +299,7 @@
   </Folder>
   <Folder Name="/Samples/03-workflows/Evaluation/">
     <Project Path="samples/03-workflows/Evaluation/Evaluation_WorkflowEval/Evaluation_WorkflowEval.csproj" />
+    <Project Path="samples/03-workflows/Evaluation/Evaluation_WorkflowExpectedOutputs/Evaluation_WorkflowExpectedOutputs.csproj" />
   </Folder>
   <Folder Name="/Samples/04-hosting/">
   </Folder>
@@ -582,6 +584,7 @@
     <Project Path="src/Microsoft.Agents.AI.DurableTask/Microsoft.Agents.AI.DurableTask.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Foundry.Hosting/Microsoft.Agents.AI.Foundry.Hosting.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Foundry/Microsoft.Agents.AI.Foundry.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Harness/Microsoft.Agents.AI.Harness.csproj" />
     <Project Path="src/Microsoft.Agents.AI.GitHub.Copilot/Microsoft.Agents.AI.GitHub.Copilot.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.A2A.AspNetCore/Microsoft.Agents.AI.Hosting.A2A.AspNetCore.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.A2A/Microsoft.Agents.AI.Hosting.A2A.csproj" />
@@ -636,6 +639,7 @@
     <Project Path="tests/Microsoft.Agents.AI.Foundry.UnitTests/Microsoft.Agents.AI.Foundry.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Harness.UnitTests/Microsoft.Agents.AI.Harness.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/Microsoft.Agents.AI.Hosting.A2A.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests.csproj" />

dotnet/agent-framework-release.slnf

@@ -7,6 +7,7 @@
       "src\\Microsoft.Agents.AI.AGUI\\Microsoft.Agents.AI.AGUI.csproj",
       "src\\Microsoft.Agents.AI.Anthropic\\Microsoft.Agents.AI.Anthropic.csproj",
       "src\\Microsoft.Agents.AI.GitHub.Copilot\\Microsoft.Agents.AI.GitHub.Copilot.csproj",
+      "src\\Microsoft.Agents.AI.Harness\\Microsoft.Agents.AI.Harness.csproj",
       "src\\Microsoft.Agents.AI.AzureAI.Persistent\\Microsoft.Agents.AI.AzureAI.Persistent.csproj",
       "src\\Microsoft.Agents.AI.Foundry\\Microsoft.Agents.AI.Foundry.csproj",
       "src\\Microsoft.Agents.AI.Foundry.Hosting\\Microsoft.Agents.AI.Foundry.Hosting.csproj",

dotnet/eng/verify-samples/WorkflowSamples.cs

@@ -478,6 +478,17 @@ internal static class WorkflowSamples
             ExpectedOutputDescription = ["The output should show a workflow invoking a function tool (e.g. a menu plugin) to answer a question about the soup of the day."],
         },
 
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_InvokeFoundryToolboxMcp",
+            ProjectPath = "samples/03-workflows/Declarative/InvokeFoundryToolboxMcp",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME", "FOUNDRY_TOOLBOX_NAME", "FOUNDRY_AGENT_TOOLSET_API_VERSION"],
+            Inputs = ["How do I use Azure OpenAI with my data?"],
+            InputDelayMs = 3000,
+            ExpectedOutputDescription = ["The output should show a workflow using Foundry Toolbox MCP tools to search Microsoft Learn documentation and web search to provide a summary of results."],
+        },
+
         new SampleDefinition
         {
             Name = "Workflow_Declarative_InvokeMcpTool",

dotnet/nuget/nuget-package.props

@@ -1,14 +1,14 @@
 <Project>
   <PropertyGroup>
     <!-- Central version prefix - applies to all nuget packages. -->
-    <VersionPrefix>1.5.0</VersionPrefix>
+    <VersionPrefix>1.6.1</VersionPrefix>
     <RCNumber>1</RCNumber>
-    <DateSuffix>260507</DateSuffix>
+    <DateSuffix>260514</DateSuffix>
     <PackageVersion Condition="'$(IsReleaseCandidate)' == 'true'">$(VersionPrefix)-rc$(RCNumber)</PackageVersion>
     <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).$(DateSuffix).1</PackageVersion>
     <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' == ''">$(VersionPrefix)-preview.$(DateSuffix).1</PackageVersion>
     <PackageVersion Condition="'$(IsReleased)' == 'true'">$(VersionPrefix)</PackageVersion>
-    <GitTag>1.5.0</GitTag>
+    <GitTag>1.6.1</GitTag>
 
     <Configurations>Debug;Release;Publish</Configurations>
     <IsPackable>true</IsPackable>

dotnet/samples/02-agents/AgentsWithFoundry/Agent_Step25_FoundryToolboxMcp/Program.cs

@@ -20,22 +20,18 @@ using OpenAI.Responses;
 #pragma warning disable OPENAI001 // Experimental API
 #pragma warning disable AAIP001  // AgentToolboxes is experimental
 
-// Must match the `<name>` segment of FOUNDRY_TOOLBOX_ENDPOINT.
+// Name of the toolbox to create and connect to.
 const string ToolboxName = "research_toolbox";
 const string Query = "What tools do you have access to?";
 
 string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
     ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
 string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
-string toolboxEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_TOOLBOX_ENDPOINT")
-    ?? throw new InvalidOperationException(
-        "FOUNDRY_TOOLBOX_ENDPOINT is not set. Example: " +
-        "https://<account>.services.ai.azure.com/api/projects/<project>/toolsets/<name>/mcp?api-version=2025-05-01-preview");
 
 TokenCredential credential = new DefaultAzureCredential();
 
 // Comment out if the toolbox already exists in your Foundry project.
-await CreateSampleToolboxAsync(ToolboxName, endpoint, credential);
+var toolboxEndpoint = await CreateSampleToolboxAsync(ToolboxName, endpoint, credential);
 
 // Inject a fresh Azure AI bearer token on every MCP request.
 using var httpClient = new HttpClient(new BearerTokenHandler(credential, "https://ai.azure.com/.default")
@@ -51,6 +47,11 @@ await using McpClient mcpClient = await McpClient.CreateAsync(
         {
             Endpoint = new Uri(toolboxEndpoint),
             Name = "foundry_toolbox",
+            TransportMode = HttpTransportMode.StreamableHttp,
+            AdditionalHeaders = new Dictionary<string, string>
+            {
+                ["Foundry-Features"] = "Toolboxes=V1Preview",
+            },
         },
         httpClient));
 
@@ -74,7 +75,7 @@ Console.WriteLine($"Assistant: {await agent.RunAsync(Query)}");
 // ---------------------------------------------------------------------------
 // Helper: create (or replace) a sample toolbox so the sample runs end-to-end
 // ---------------------------------------------------------------------------
-static async Task CreateSampleToolboxAsync(string name, string endpoint, TokenCredential credential)
+static async Task<string> CreateSampleToolboxAsync(string name, string endpoint, TokenCredential credential)
 {
     // Toolboxes are normally configured in the Foundry portal or a deployment
     // script, not the application itself. This helper exists so the sample can
@@ -103,12 +104,13 @@ static async Task CreateSampleToolboxAsync(string name, string endpoint, TokenCr
         serverUri: new Uri("https://gitmcp.io/Azure/azure-rest-api-specs"),
         toolCallApprovalPolicy: new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.NeverRequireApproval)));
 
-    var created = (await toolboxClient.CreateToolboxVersionAsync(
+    ToolboxVersion created = (await toolboxClient.CreateToolboxVersionAsync(
         name: name,
         tools: [mcpTool],
         description: "Sample toolbox with an MCP tool — created by Agent_Step25 sample.")).Value;
 
     Console.WriteLine($"Created toolbox '{created.Name}' v{created.Version} ({created.Tools.Count} tool(s))");
+    return $"{endpoint}/toolboxes/{created.Name}/mcp?api-version=v{created.Version}";
 }
 
 // ---------------------------------------------------------------------------

dotnet/samples/02-agents/AgentsWithFoundry/Agent_Step25_FoundryToolboxMcp/README.md

@@ -19,10 +19,11 @@ Set the following environment variables:
 ```powershell
 $env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project"
 $env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4-mini"
-$env:FOUNDRY_TOOLBOX_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project/toolsets/research_toolbox/mcp?api-version=2025-05-01-preview"
 ```
 
-The `<name>` segment of `FOUNDRY_TOOLBOX_ENDPOINT` must match the `ToolboxName` constant in `Program.cs`.
+The sample creates a toolbox named `research_toolbox` in your Foundry project on
+startup, then connects to its MCP endpoint at
+`{AZURE_AI_PROJECT_ENDPOINT}/toolboxes/research_toolbox/mcp?api-version=v{version}`.
 
 ## Run the sample
 

dotnet/samples/02-agents/Harness/ConsoleReactiveComponents/TextPanel.cs

@@ -9,42 +9,30 @@ namespace Harness.ConsoleReactiveComponents;
 /// </summary>
 public record TextPanelProps : ConsoleReactiveProps
 {
-    /// <summary>Gets the items to render in the panel.</summary>
-    public IReadOnlyList<object> Items { get; init; } = [];
+    /// <summary>Gets the items to render in the panel. Each item is a pre-rendered
+    /// console string (may include ANSI escape sequences and newlines).</summary>
+    public IReadOnlyList<string> Items { get; init; } = [];
 }
 
 /// <summary>
-/// A component that renders a list of items vertically using a custom render delegate.
+/// A component that renders a list of pre-rendered string items vertically.
 /// Designed for rendering dynamic items in a non-scroll region that may be
 /// re-rendered on each update. If the component's <see cref="ConsoleReactiveComponent.Height"/>
 /// exceeds the number of output lines, leftover lines are erased.
 /// </summary>
 public class TextPanel : ConsoleReactiveComponent<TextPanelProps, ConsoleReactiveState>
 {
-    private readonly Func<object, string> _renderItem;
-
-    /// <summary>
-    /// Initializes a new instance of the <see cref="TextPanel"/> class.
-    /// </summary>
-    /// <param name="renderItem">A delegate that renders an item and returns the text to display (may contain newlines).</param>
-    public TextPanel(Func<object, string> renderItem)
-    {
-        this._renderItem = renderItem;
-    }
-
     /// <summary>
     /// Calculates the height (in lines) needed to render all items.
     /// </summary>
     /// <param name="items">The items to measure.</param>
-    /// <param name="renderItem">The render delegate to use for measuring.</param>
     /// <returns>The total number of lines all items will occupy.</returns>
-    public static int CalculateHeight(IReadOnlyList<object> items, Func<object, string> renderItem)
+    public static int CalculateHeight(IReadOnlyList<string> items)
     {
         int total = 0;
         for (int i = 0; i < items.Count; i++)
         {
-            string text = renderItem(items[i]);
-            total += CountLines(text);
+            total += CountLines(items[i]);
         }
 
         return total;
@@ -57,7 +45,7 @@ public class TextPanel : ConsoleReactiveComponent<TextPanelProps, ConsoleReactiv
 
         for (int i = 0; i < props.Items.Count; i++)
         {
-            string text = this._renderItem(props.Items[i]);
+            string text = props.Items[i];
             string[] lines = text.Split('\n');
             int lineCount = CountLines(text);
 

dotnet/samples/02-agents/Harness/ConsoleReactiveComponents/TextScrollPanel.cs

@@ -9,8 +9,9 @@ namespace Harness.ConsoleReactiveComponents;
 /// </summary>
 public record TextScrollPanelProps : ConsoleReactiveProps
 {
-    /// <summary>Gets the items to render in the scroll panel.</summary>
-    public IReadOnlyList<object> Items { get; init; } = [];
+    /// <summary>Gets the items to render in the scroll panel. Each item is a pre-rendered
+    /// console string (may include ANSI escape sequences and newlines).</summary>
+    public IReadOnlyList<string> Items { get; init; } = [];
 }
 
 /// <summary>
@@ -20,21 +21,17 @@ public record TextScrollPanelProps : ConsoleReactiveProps
 public record TextScrollPanelState(int RenderedCount = 0) : ConsoleReactiveState;
 
 /// <summary>
-/// A component that renders items within a scroll area using a custom render delegate.
+/// A component that renders pre-rendered string items within a scroll area.
 /// All items are considered finalized — only new items since the last render are output.
 /// Use <see cref="Reset"/> to force a full re-render.
 /// </summary>
 public class TextScrollPanel : ConsoleReactiveComponent<TextScrollPanelProps, TextScrollPanelState>
 {
-    private readonly Func<object, string> _renderItem;
-
     /// <summary>
     /// Initializes a new instance of the <see cref="TextScrollPanel"/> class.
     /// </summary>
-    /// <param name="renderItem">A delegate that renders a single item and returns the text to display (may contain newlines).</param>
-    public TextScrollPanel(Func<object, string> renderItem)
+    public TextScrollPanel()
     {
-        this._renderItem = renderItem;
         this.State = new TextScrollPanelState();
     }
 
@@ -60,8 +57,7 @@ public class TextScrollPanel : ConsoleReactiveComponent<TextScrollPanelProps, Te
         // Output only new items since last rendered
         for (int i = state.RenderedCount; i < props.Items.Count; i++)
         {
-            string text = this._renderItem(props.Items[i]);
-            Console.Write(text);
+            Console.Write(props.Items[i]);
         }
 
         // Update state to track what we've rendered

dotnet/samples/02-agents/Harness/Harness_ConsoleSandbox/AppComponent.cs

@@ -1,315 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using Harness.ConsoleReactiveComponents;
-using Harness.ConsoleReactiveFramework;
-
-namespace Harness.ConsoleSandbox;
-
-/// <summary>
-/// Determines which component is shown in the bottom panel.
-/// </summary>
-public enum BottomPanelMode
-{
-    /// <summary>Show the list selection component.</summary>
-    ListSelection,
-
-    /// <summary>Show the text input component.</summary>
-    TextInput
-}
-
-public record AppComponentProps : ConsoleReactiveProps
-{
-    public IReadOnlyList<string> Items { get; init; } = Array.Empty<string>();
-    public IReadOnlyList<object> ScrollItems { get; init; } = [];
-
-    /// <summary>Gets the bottom panel mode.</summary>
-    public BottomPanelMode Mode { get; init; } = BottomPanelMode.ListSelection;
-
-    /// <summary>Gets the prompt string for text input mode.</summary>
-    public string Prompt { get; init; } = "> ";
-
-    /// <summary>Gets the placeholder text shown when the input is empty.</summary>
-    public string Placeholder { get; init; } = "";
-
-    /// <summary>Gets the highlight color for the active list item. Defaults to <see cref="ConsoleColor.Cyan"/>.</summary>
-    public ConsoleColor ListHighlightColor { get; init; } = ConsoleColor.Cyan;
-
-    /// <summary>Gets the placeholder text for the custom text input option in the list. If <c>null</c>, no custom option is shown.</summary>
-    public string? ListCustomTextPlaceholder { get; init; }
-
-    /// <summary>Gets the foreground color for the rule borders. If <c>null</c>, uses the default terminal color.</summary>
-    public ConsoleColor? RuleColor { get; init; }
-}
-
-/// <summary>
-/// Internal state for the <see cref="AppComponent"/>.
-/// </summary>
-public record AppComponentState : ConsoleReactiveState
-{
-    /// <summary>Gets the selected index in list selection mode.</summary>
-    public int SelectedIndex { get; init; }
-
-    /// <summary>Gets the current input text being typed in text input mode.</summary>
-    public string InputText { get; init; } = "";
-
-    /// <summary>Gets the current text being typed into the list's custom text option.</summary>
-    public string ListInputText { get; init; } = "";
-}
-
-public class AppComponent : ConsoleReactiveComponent<AppComponentProps, AppComponentState>
-{
-    private readonly TopBottomRule _rule = new();
-    private readonly ListSelection _listSelection = new();
-    private readonly TextInput _textInput = new();
-    private readonly TextScrollPanel _textScrollPanel;
-    private readonly TextPanel _textPanel;
-    private readonly Func<object, string> _renderItem;
-    private readonly Action<string> _onTextInputSubmit;
-    private readonly Action<string> _onListInputSubmit;
-    private bool _resizedSinceLastRender;
-    private int _lastScrollBottom;
-
-    /// <summary>
-    /// Initializes a new instance of the <see cref="AppComponent"/> class.
-    /// </summary>
-    /// <param name="renderScrollItem">A delegate that renders a single scroll panel item and returns the text to display.</param>
-    /// <param name="onTextInputSubmit">A callback invoked with the input text when the user presses Enter in text input mode.</param>
-    /// <param name="onListInputSubmit">A callback invoked with the selected or typed text when the user presses Enter in list selection mode.</param>
-    public AppComponent(Func<object, string> renderScrollItem, Action<string> onTextInputSubmit, Action<string> onListInputSubmit)
-    {
-        this._renderItem = renderScrollItem;
-        this._onTextInputSubmit = onTextInputSubmit;
-        this._onListInputSubmit = onListInputSubmit;
-        this._textScrollPanel = new TextScrollPanel(renderScrollItem);
-        this._textPanel = new TextPanel(renderScrollItem);
-        this.State = new AppComponentState();
-        KeyEventListener.Instance.KeyPressed += this.OnKeyPressed;
-        ConsoleResizeListener.Instance.ConsoleResized += this.OnConsoleResized;
-    }
-
-    private void OnKeyPressed(object? sender, KeyPressEventArgs e)
-    {
-        if (this.Props!.Mode == BottomPanelMode.TextInput)
-        {
-            this.HandleTextInputKey(e);
-        }
-        else
-        {
-            this.HandleListSelectionKey(e);
-        }
-    }
-
-    private void HandleTextInputKey(KeyPressEventArgs e)
-    {
-        if (e.KeyInfo.Key == ConsoleKey.Enter)
-        {
-            string text = this.State!.InputText;
-            this.SetState(this.State with { InputText = "" });
-            this._onTextInputSubmit(text);
-        }
-        else if (e.KeyInfo.Key == ConsoleKey.Backspace)
-        {
-            if (this.State!.InputText.Length > 0)
-            {
-                this.SetState(this.State with { InputText = this.State.InputText[..^1] });
-            }
-        }
-        else if (e.KeyInfo.KeyChar != '\0' && !char.IsControl(e.KeyInfo.KeyChar))
-        {
-            this.SetState(this.State! with { InputText = this.State.InputText + e.KeyInfo.KeyChar });
-        }
-    }
-
-    private void HandleListSelectionKey(KeyPressEventArgs e)
-    {
-        int maxIndex = this.Props!.Items.Count - 1;
-        if (this.Props.ListCustomTextPlaceholder != null)
-        {
-            maxIndex = this.Props.Items.Count; // extra option at the end
-        }
-
-        bool isOnCustomTextOption = this.Props.ListCustomTextPlaceholder != null
-            && this.State!.SelectedIndex == this.Props.Items.Count;
-
-        if (e.KeyInfo.Key == ConsoleKey.UpArrow)
-        {
-            this.SetState(this.State! with { SelectedIndex = Math.Max(0, this.State.SelectedIndex - 1) });
-        }
-        else if (e.KeyInfo.Key == ConsoleKey.DownArrow)
-        {
-            this.SetState(this.State! with { SelectedIndex = Math.Min(maxIndex, this.State.SelectedIndex + 1) });
-        }
-        else if (e.KeyInfo.Key == ConsoleKey.Enter)
-        {
-            if (isOnCustomTextOption)
-            {
-                string text = this.State!.ListInputText;
-                this.SetState(this.State with { ListInputText = "" });
-                this._onListInputSubmit(text);
-            }
-            else
-            {
-                this._onListInputSubmit(this.Props.Items[this.State!.SelectedIndex]);
-            }
-        }
-        else if (isOnCustomTextOption)
-        {
-            // Typing only works when on the custom text option
-            if (e.KeyInfo.Key == ConsoleKey.Backspace)
-            {
-                if (this.State!.ListInputText.Length > 0)
-                {
-                    this.SetState(this.State with { ListInputText = this.State.ListInputText[..^1] });
-                }
-            }
-            else if (e.KeyInfo.KeyChar != '\0' && !char.IsControl(e.KeyInfo.KeyChar))
-            {
-                this.SetState(this.State! with { ListInputText = this.State.ListInputText + e.KeyInfo.KeyChar });
-            }
-        }
-    }
-
-    private void OnConsoleResized(object? sender, ConsoleResizeEventArgs e)
-    {
-        this._resizedSinceLastRender = true;
-        this.Render();
-    }
-
-    public override void RenderCore(AppComponentProps props, AppComponentState state)
-    {
-        // Determine the text panel height for the last scroll item
-        object? lastItem = props.ScrollItems.Count > 0 ? props.ScrollItems[^1] : null;
-        IReadOnlyList<object> lastItems = lastItem != null ? [lastItem] : [];
-        int textPanelHeight = TextPanel.CalculateHeight(lastItems, this._renderItem);
-        if (textPanelHeight > 0)
-        {
-            textPanelHeight++; // Extra line for spacing between text panel and rule
-        }
-
-        // Build the bottom panel child based on mode
-        ConsoleReactiveComponent bottomChild;
-        int bottomChildHeight;
-
-        if (props.Mode == BottomPanelMode.TextInput)
-        {
-            var textInputProps = new TextInputProps
-            {
-                Prompt = props.Prompt,
-                Text = state.InputText,
-                Placeholder = props.Placeholder
-            };
-
-            bottomChildHeight = TextInput.CalculateHeight(textInputProps, Console.WindowWidth);
-            this._textInput.Width = Console.WindowWidth;
-            this._textInput.Height = bottomChildHeight;
-            this._textInput.Props = textInputProps;
-            bottomChild = this._textInput;
-        }
-        else
-        {
-            var listProps = new ListSelectionProps
-            {
-                Items = props.Items,
-                SelectedIndex = state.SelectedIndex,
-                HighlightColor = props.ListHighlightColor,
-                CustomTextPlaceholder = props.ListCustomTextPlaceholder,
-                CustomText = state.ListInputText
-            };
-
-            bottomChildHeight = ListSelection.CalculateHeight(listProps);
-            this._listSelection.Height = bottomChildHeight;
-            this._listSelection.Props = listProps;
-            bottomChild = this._listSelection;
-        }
-
-        var ruleProps = new TopBottomRuleProps
-        {
-            Width = Console.WindowWidth,
-            Color = props.RuleColor,
-            Children = [bottomChild]
-        };
-
-        int ruleHeight = TopBottomRule.CalculateHeight(ruleProps);
-        int scrollBottom = Console.WindowHeight - ruleHeight - textPanelHeight;
-
-        // If scroll region changed or a clear is needed, reset everything
-        if (this._resizedSinceLastRender || (this._lastScrollBottom != 0 && scrollBottom != this._lastScrollBottom))
-        {
-            Console.Write(AnsiEscapes.EraseEntireScreen);
-            Console.Write(AnsiEscapes.EraseScrollbackBuffer);
-            this._textScrollPanel.Reset();
-            this._resizedSinceLastRender = false;
-        }
-
-        this._lastScrollBottom = scrollBottom;
-
-        Console.Write(AnsiEscapes.SetScrollRegion(scrollBottom));
-
-        // Render text scroll panel in the scroll area (all items except the last)
-        IReadOnlyList<object> scrollItems = props.ScrollItems.Count > 1
-            ? props.ScrollItems.Take(props.ScrollItems.Count - 1).ToList()
-            : [];
-
-        this._textScrollPanel.X = 1;
-        this._textScrollPanel.Y = 1;
-        this._textScrollPanel.Width = Console.WindowWidth;
-        this._textScrollPanel.Height = scrollBottom;
-        this._textScrollPanel.Props = new TextScrollPanelProps
-        {
-            Items = scrollItems
-        };
-        this._textScrollPanel.Render();
-
-        // Render the text panel for the last (dynamic) item just below the scroll region
-        this._textPanel.X = 1;
-        this._textPanel.Y = scrollBottom + 1;
-        this._textPanel.Width = Console.WindowWidth;
-        this._textPanel.Height = textPanelHeight;
-        this._textPanel.Props = new TextPanelProps
-        {
-            Items = lastItems,
-        };
-        this._textPanel.Render();
-
-        // Render the bottom rule + child below the text panel
-        this._rule.X = 1;
-        this._rule.Y = scrollBottom + textPanelHeight + 1;
-        this._rule.Props = ruleProps;
-        this._rule.Render();
-
-        // Position cursor for natural typing appearance
-        if (props.Mode == BottomPanelMode.TextInput)
-        {
-            int promptLength = props.Prompt.Length;
-            int textWidth = Console.WindowWidth - promptLength;
-            int textLength = state.InputText.Length;
-
-            // The TextInput starts at rule.Y + 1 (first row inside the rule)
-            int textInputY = this._rule.Y + 1;
-
-            if (textWidth <= 0 || textLength == 0)
-            {
-                // Cursor right after the prompt
-                Console.Write(AnsiEscapes.MoveCursor(textInputY, promptLength + 1));
-            }
-            else
-            {
-                // Calculate which row and column the cursor lands on
-                int cursorRow = textLength < textWidth ? 0 : 1 + ((textLength - textWidth) / textWidth);
-                int cursorCol = textLength < textWidth ? textLength : (textLength - textWidth) % textWidth;
-                Console.Write(AnsiEscapes.MoveCursor(textInputY + cursorRow, promptLength + cursorCol + 1));
-            }
-        }
-        else if (props.Mode == BottomPanelMode.ListSelection
-            && props.ListCustomTextPlaceholder != null
-            && state.SelectedIndex == props.Items.Count)
-        {
-            // Cursor after the typed text in the custom text option
-            // The custom text option is at rule.Y + 1 + Items.Count (0-based row inside rule)
-            int customOptionY = this._rule.Y + 1 + props.Items.Count;
-            // "> " prefix is 2 chars, then the typed text
-            int cursorCol = 2 + state.ListInputText.Length + 1;
-            Console.Write(AnsiEscapes.MoveCursor(customOptionY, cursorCol));
-        }
-    }
-}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Commands/CommandHandler.cs

@@ -23,7 +23,7 @@ public abstract class CommandHandler
     /// </summary>
     /// <param name="input">The raw user input string.</param>
     /// <param name="session">The current agent session.</param>
-    /// <param name="ux">The UX container for rendering output.</param>
+    /// <param name="ux">The UX state driver for rendering output.</param>
     /// <returns><see langword="true"/> if this handler handled the input; <see langword="false"/> otherwise.</returns>
-    public abstract ValueTask<bool> TryHandleAsync(string input, AgentSession session, HarnessUXContainer ux);
+    public abstract ValueTask<bool> TryHandleAsync(string input, AgentSession session, IUXStateDriver ux);
 }

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Commands/ExitCommandHandler.cs

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+
+namespace Harness.Shared.Console.Commands;
+
+/// <summary>
+/// Handles the <c>/exit</c> command to shut down the console application.
+/// </summary>
+public sealed class ExitCommandHandler : CommandHandler
+{
+    /// <inheritdoc/>
+    public override string? GetHelpText() => "/exit (quit)";
+
+    /// <inheritdoc/>
+    public override ValueTask<bool> TryHandleAsync(string input, AgentSession session, IUXStateDriver ux)
+    {
+        if (!input.Equals("/exit", StringComparison.OrdinalIgnoreCase))
+        {
+            return new ValueTask<bool>(false);
+        }
+
+        ux.RequestShutdown();
+        return new ValueTask<bool>(true);
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Commands/ModeCommandHandler.cs

@@ -7,7 +7,7 @@ namespace Harness.Shared.Console.Commands;
 /// <summary>
 /// Handles the <c>/mode</c> command to display or switch the current agent mode.
 /// </summary>
-internal sealed class ModeCommandHandler : CommandHandler
+public sealed class ModeCommandHandler : CommandHandler
 {
     private readonly AgentModeProvider? _modeProvider;
     private readonly IReadOnlyDictionary<string, ConsoleColor>? _modeColors;
@@ -27,7 +27,7 @@ internal sealed class ModeCommandHandler : CommandHandler
     public override string? GetHelpText() => this._modeProvider is not null ? "/mode [plan|execute] (show or switch mode)" : null;
 
     /// <inheritdoc/>
-    public override async ValueTask<bool> TryHandleAsync(string input, AgentSession session, HarnessUXContainer ux)
+    public override async ValueTask<bool> TryHandleAsync(string input, AgentSession session, IUXStateDriver ux)
     {
         if (!input.StartsWith("/mode ", StringComparison.OrdinalIgnoreCase) && !input.Equals("/mode", StringComparison.OrdinalIgnoreCase))
         {

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Commands/TodoCommandHandler.cs

@@ -7,7 +7,7 @@ namespace Harness.Shared.Console.Commands;
 /// <summary>
 /// Handles the <c>/todos</c> command to display the current todo list.
 /// </summary>
-internal sealed class TodoCommandHandler : CommandHandler
+public sealed class TodoCommandHandler : CommandHandler
 {
     private readonly TodoProvider? _todoProvider;
 
@@ -24,7 +24,7 @@ internal sealed class TodoCommandHandler : CommandHandler
     public override string? GetHelpText() => this._todoProvider is not null ? "/todos (show todo list)" : null;
 
     /// <inheritdoc/>
-    public override async ValueTask<bool> TryHandleAsync(string input, AgentSession session, HarnessUXContainer ux)
+    public override async ValueTask<bool> TryHandleAsync(string input, AgentSession session, IUXStateDriver ux)
     {
         if (!input.Equals("/todos", StringComparison.OrdinalIgnoreCase))
         {

dotnet/samples/02-agents/Harness/Harness_Shared_Console/FollowUpAction.cs

@@ -0,0 +1,59 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console;
+
+/// <summary>
+/// Represents an action returned by an observer at the end of an agent turn.
+/// Subtypes describe either a question to ask the user (<see cref="FollowUpQuestion"/>)
+/// or a message to add directly to the next agent input (<see cref="FollowUpMessage"/>).
+/// </summary>
+public abstract record FollowUpAction;
+
+/// <summary>
+/// Represents a question that should be presented to the user. The
+/// <see cref="Continuation"/> delegate is invoked with the user's answer and the
+/// UX state driver, and returns an optional <see cref="ChatMessage"/> to add to the
+/// next agent invocation.
+/// </summary>
+/// <param name="Prompt">The question text shown to the user.</param>
+/// <param name="Continuation">
+/// Invoked with the user's answer and the UX state driver. The driver lets the
+/// continuation write output (e.g., an action label like "Approved") in addition
+/// to producing an optional <see cref="ChatMessage"/> for the next agent invocation.
+/// </param>
+public abstract record FollowUpQuestion(
+    string Prompt,
+    Func<string, IUXStateDriver, Task<ChatMessage?>> Continuation) : FollowUpAction;
+
+/// <summary>
+/// A free-form text question. The user may type any response.
+/// </summary>
+/// <param name="Prompt">The question text shown to the user.</param>
+/// <param name="Continuation">Continuation that builds the response message.</param>
+public sealed record TextFollowUpQuestion(
+    string Prompt,
+    Func<string, IUXStateDriver, Task<ChatMessage?>> Continuation)
+    : FollowUpQuestion(Prompt, Continuation);
+
+/// <summary>
+/// A choice question. The user picks from <paramref name="Choices"/>, optionally with
+/// the ability to enter custom text when <paramref name="AllowCustomText"/> is true.
+/// </summary>
+/// <param name="Prompt">The question text shown to the user.</param>
+/// <param name="Choices">The list of pre-defined choices.</param>
+/// <param name="AllowCustomText">If true, the user may type a custom response in addition to the listed choices.</param>
+/// <param name="Continuation">Continuation that builds the response message.</param>
+public sealed record ChoiceFollowUpQuestion(
+    string Prompt,
+    IReadOnlyList<string> Choices,
+    bool AllowCustomText,
+    Func<string, IUXStateDriver, Task<ChatMessage?>> Continuation)
+    : FollowUpQuestion(Prompt, Continuation);
+
+/// <summary>
+/// A message to add directly to the next agent invocation without prompting the user.
+/// </summary>
+/// <param name="Message">The chat message to add.</param>
+public sealed record FollowUpMessage(ChatMessage Message) : FollowUpAction;

dotnet/samples/02-agents/Harness/Harness_Shared_Console/HarnessAgentRunner.cs

@@ -0,0 +1,279 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Harness.Shared.Console.Commands;
+using Harness.Shared.Console.Observers;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console;
+
+/// <summary>
+/// Orchestrates agent invocations driven by user-input events from the UI.
+/// The component invokes the runner's input handlers (<see cref="OnUserInputAsync"/>,
+/// <see cref="OnStreamingInputAsync"/>, <see cref="StartAgentTurnAsync"/>) directly;
+/// the runner mutates UI state through the supplied <see cref="IUXStateDriver"/>.
+/// All per-turn follow-up state (pending questions and accumulated responses) lives
+/// in the component's state record — the runner reads/writes it exclusively through
+/// the driver and holds no per-turn fields itself.
+/// </summary>
+public sealed class HarnessAgentRunner : IDisposable
+{
+    private readonly AIAgent _agent;
+    private readonly AgentSession _session;
+    private readonly AgentModeProvider? _modeProvider;
+    private readonly MessageInjectingChatClient? _messageInjector;
+    private readonly IReadOnlyList<CommandHandler> _commandHandlers;
+    private readonly IReadOnlyList<ConsoleObserver> _observers;
+    private readonly IUXStateDriver _ux;
+
+    private readonly SemaphoreSlim _inputGate = new(1, 1);
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="HarnessAgentRunner"/> class.
+    /// </summary>
+    public HarnessAgentRunner(
+        AIAgent agent,
+        AgentSession session,
+        AgentModeProvider? modeProvider,
+        MessageInjectingChatClient? messageInjector,
+        IReadOnlyList<CommandHandler> commandHandlers,
+        IReadOnlyList<ConsoleObserver> observers,
+        IUXStateDriver ux)
+    {
+        this._agent = agent;
+        this._session = session;
+        this._modeProvider = modeProvider;
+        this._messageInjector = messageInjector;
+        this._commandHandlers = commandHandlers;
+        this._observers = observers;
+        this._ux = ux;
+
+        this.HelpText = string.Join(
+            ", ",
+            commandHandlers
+                .Select(h => h.GetHelpText())
+                .Where(t => t is not null)!);
+    }
+
+    /// <summary>
+    /// Gets the help text describing all available commands (joined by ", "), suitable
+    /// for display in the mode-and-help bar. Computed from the supplied
+    /// <c>commandHandlers</c>.
+    /// </summary>
+    public string HelpText { get; }
+
+    /// <inheritdoc/>
+    public void Dispose() => this._inputGate.Dispose();
+
+    /// <summary>
+    /// Handles a top-level user input submission (TextInput mode, no pending question).
+    /// Dispatches to command handlers, or starts an agent turn.
+    /// </summary>
+    internal async Task OnUserInputAsync(string text)
+    {
+        await this._inputGate.WaitAsync().ConfigureAwait(false);
+        try
+        {
+            this._ux.WriteUserInputEcho(text);
+
+            foreach (var handler in this._commandHandlers)
+            {
+                if (await handler.TryHandleAsync(text, this._session, this._ux).ConfigureAwait(false))
+                {
+                    this._ux.CurrentMode = this._modeProvider?.GetMode(this._session);
+                    return;
+                }
+            }
+
+            await this.RunAgentLoopAsync([new ChatMessage(ChatRole.User, text)]).ConfigureAwait(false);
+        }
+        finally
+        {
+            this._inputGate.Release();
+        }
+    }
+
+    /// <summary>
+    /// Handles a user input submission while an agent turn is streaming. The text is
+    /// enqueued via the <see cref="MessageInjectingChatClient"/> so it can be picked up
+    /// by the agent on its next opportunity.
+    /// </summary>
+    internal Task OnStreamingInputAsync(string text)
+    {
+        if (this._messageInjector is null)
+        {
+            return Task.CompletedTask;
+        }
+
+        this._messageInjector.EnqueueMessages(this._session, [new ChatMessage(ChatRole.User, text)]);
+        this._ux.SetQueuedMessages(this._messageInjector.GetPendingMessages(this._session));
+        return Task.CompletedTask;
+    }
+
+    /// <summary>
+    /// Resumes (or completes) a turn after the user has answered all pending follow-up
+    /// questions. The component invokes this with the messages drained from
+    /// <see cref="IUXStateDriver.TakeFollowUpResponses"/>; an empty list simply ends
+    /// the streaming display state without invoking the agent.
+    /// </summary>
+    internal async Task StartAgentTurnAsync(IList<ChatMessage> messages)
+    {
+        await this._inputGate.WaitAsync().ConfigureAwait(false);
+        try
+        {
+            if (messages.Count == 0)
+            {
+                this.CompleteTurn();
+                return;
+            }
+
+            await this.RunAgentLoopAsync(messages).ConfigureAwait(false);
+        }
+        finally
+        {
+            this._inputGate.Release();
+        }
+    }
+
+    private async Task RunAgentLoopAsync(IList<ChatMessage> messages)
+    {
+        IList<ChatMessage>? nextMessages = messages;
+        IReadOnlyList<ChatMessage> lastPendingMessages = this._messageInjector?.GetPendingMessages(this._session) ?? [];
+
+        while (nextMessages is not null)
+        {
+            var runOptions = new AgentRunOptions();
+            foreach (var observer in this._observers)
+            {
+                observer.ConfigureRunOptions(runOptions, this._agent, this._session);
+            }
+
+            this._ux.CurrentMode = this._modeProvider?.GetMode(this._session);
+            this._ux.BeginStreaming();
+            this._ux.BeginStreamingOutput();
+
+            try
+            {
+                await foreach (var update in this._agent.RunStreamingAsync(nextMessages, this._session, runOptions))
+                {
+                    if (this._modeProvider is not null)
+                    {
+                        string currentMode = this._modeProvider.GetMode(this._session);
+                        if (currentMode != this._ux.CurrentMode)
+                        {
+                            this._ux.CurrentMode = currentMode;
+                        }
+                    }
+
+                    foreach (var content in update.Contents)
+                    {
+                        foreach (var observer in this._observers)
+                        {
+                            await observer.OnContentAsync(this._ux, content, this._agent, this._session).ConfigureAwait(false);
+                        }
+                    }
+
+                    if (!string.IsNullOrEmpty(update.Text))
+                    {
+                        foreach (var observer in this._observers)
+                        {
+                            await observer.OnTextAsync(this._ux, update.Text, this._agent, this._session).ConfigureAwait(false);
+                        }
+                    }
+
+                    this.SyncQueuedMessageDisplay(ref lastPendingMessages);
+                }
+            }
+            catch (Exception ex)
+            {
+                await this._ux.WriteInfoLineAsync($"❌ Stream error: {ex.GetType().Name}:\n{ex}", ConsoleColor.Red).ConfigureAwait(false);
+            }
+
+            // Final sync after streaming.
+            this.SyncQueuedMessageDisplay(ref lastPendingMessages);
+
+            this._ux.StopSpinner();
+            await this._ux.EndStreamingOutputAsync().ConfigureAwait(false);
+
+            // Collect FollowUpActions from each observer.
+            var directMessages = new List<ChatMessage>();
+            var questions = new List<FollowUpQuestion>();
+            foreach (var observer in this._observers)
+            {
+                var actions = await observer.OnStreamCompleteAsync(this._ux, this._agent, this._session).ConfigureAwait(false);
+                if (actions is null)
+                {
+                    continue;
+                }
+
+                foreach (var action in actions)
+                {
+                    switch (action)
+                    {
+                        case FollowUpMessage msg:
+                            directMessages.Add(msg.Message);
+                            break;
+                        case FollowUpQuestion q:
+                            questions.Add(q);
+                            break;
+                    }
+                }
+            }
+
+            bool hasFollowUpActions = directMessages.Count > 0 || questions.Count > 0;
+            await this._ux.WriteNoTextWarningAsync(hasFollowUpActions).ConfigureAwait(false);
+
+            // Add any direct messages to the accumulator regardless of whether questions follow —
+            // they're sent on the next agent invocation, either by us (if no questions) or by
+            // the component (after the user finishes answering, via StartAgentTurnAsync).
+            foreach (var msg in directMessages)
+            {
+                this._ux.AddFollowUpResponse(msg);
+            }
+
+            if (questions.Count > 0)
+            {
+                // Pause: hand control back to the UX to collect answers.
+                this._ux.QueueFollowUpQuestions(questions);
+                return;
+            }
+
+            // No questions to ask — drain anything we just accumulated and loop with it.
+            IReadOnlyList<ChatMessage> drained = this._ux.TakeFollowUpResponses();
+            nextMessages = drained.Count > 0 ? [.. drained] : null;
+        }
+
+        this.CompleteTurn();
+    }
+
+    private void CompleteTurn()
+    {
+        this._ux.EndStreaming();
+        this._ux.CurrentMode = this._modeProvider?.GetMode(this._session);
+    }
+
+    /// <summary>
+    /// Synchronizes the queued items display with the message injector's pending messages.
+    /// Messages that have been consumed (drained by the service) are echoed to the output
+    /// area as regular user-input entries.
+    /// </summary>
+    private void SyncQueuedMessageDisplay(ref IReadOnlyList<ChatMessage> lastPendingMessages)
+    {
+        if (this._messageInjector is null)
+        {
+            return;
+        }
+
+        var pending = this._messageInjector.GetPendingMessages(this._session);
+
+        int consumedCount = lastPendingMessages.Count - pending.Count;
+        for (int i = 0; i < consumedCount && i < lastPendingMessages.Count; i++)
+        {
+            string text = lastPendingMessages[i].Text ?? string.Empty;
+            this._ux.WriteUserInputEcho(text);
+        }
+
+        lastPendingMessages = pending;
+        this._ux.SetQueuedMessages(pending);
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/HarnessAppComponent.cs

@@ -3,171 +3,89 @@
 using Harness.ConsoleReactiveComponents;
 using Harness.ConsoleReactiveFramework;
 using Harness.Shared.Console.Components;
+using Microsoft.Extensions.AI;
 
 namespace Harness.Shared.Console;
 
-/// <summary>
-/// Determines which component is shown in the bottom panel.
-/// </summary>
-public enum BottomPanelMode
-{
-    /// <summary>Show the text input component for user input.</summary>
-    TextInput,
-
-    /// <summary>Show the list selection component for interactive prompts.</summary>
-    ListSelection,
-
-    /// <summary>Show a disabled input indicator during agent streaming.</summary>
-    Streaming,
-}
-
-/// <summary>
-/// Event arguments for the <see cref="HarnessAppComponent.InputSubmitted"/> event.
-/// </summary>
-public sealed class InputSubmittedEventArgs : EventArgs
-{
-    /// <summary>
-    /// Initializes a new instance of the <see cref="InputSubmittedEventArgs"/> class.
-    /// </summary>
-    /// <param name="text">The submitted text.</param>
-    /// <param name="mode">The bottom panel mode in which the input was submitted.</param>
-    public InputSubmittedEventArgs(string text, BottomPanelMode mode)
-    {
-        this.Text = text;
-        this.Mode = mode;
-    }
-
-    /// <summary>Gets the submitted text.</summary>
-    public string Text { get; }
-
-    /// <summary>Gets the bottom panel mode in which the input was submitted.</summary>
-    public BottomPanelMode Mode { get; }
-}
-
-/// <summary>
-/// Props for <see cref="HarnessAppComponent"/>.
-/// </summary>
-public record HarnessAppComponentProps : ConsoleReactiveProps
-{
-    /// <summary>Gets or sets the list selection choices (for ListSelection mode).</summary>
-    public IReadOnlyList<string> Items { get; set; } = Array.Empty<string>();
-
-    /// <summary>Gets or sets the scroll items (output entries) to render in the scroll panel.</summary>
-    public IReadOnlyList<object> ScrollItems { get; set; } = [];
-
-    /// <summary>Gets or sets the bottom panel mode.</summary>
-    public BottomPanelMode Mode { get; set; } = BottomPanelMode.TextInput;
-
-    /// <summary>Gets or sets the prompt string for text input mode.</summary>
-    public string Prompt { get; set; } = "You: ";
-
-    /// <summary>Gets or sets the placeholder text shown when the input is empty.</summary>
-    public string Placeholder { get; set; } = "";
-
-    /// <summary>Gets or sets the highlight color for the active list item.</summary>
-    public ConsoleColor ListHighlightColor { get; set; } = ConsoleColor.Cyan;
-
-    /// <summary>Gets or sets the placeholder text for the custom text input option in the list.</summary>
-    public string? ListCustomTextPlaceholder { get; set; }
-
-    /// <summary>Gets or sets the foreground color for the rule borders and mode label.</summary>
-    public ConsoleColor? ModeColor { get; set; }
-
-    /// <summary>Gets or sets the current mode name displayed below the bottom rule (e.g. "plan").</summary>
-    public string? ModeText { get; set; }
-
-    /// <summary>Gets or sets the help text displayed below the bottom rule (available commands).</summary>
-    public string? HelpText { get; set; }
-
-    /// <summary>Gets or sets the title text displayed above the list selection (for interactive prompts).</summary>
-    public string? ListTitle { get; set; }
-
-    /// <summary>Gets or sets a value indicating whether input is enabled during streaming.</summary>
-    public bool InputEnabled { get; set; }
-
-    /// <summary>Gets or sets the prompt to show during streaming when input is disabled.</summary>
-    public string StreamingPrompt { get; set; } = "(agent is running...)";
-
-    /// <summary>Gets or sets a value indicating whether the agent status spinner is visible.</summary>
-    public bool ShowSpinner { get; set; }
-
-    /// <summary>Gets or sets the formatted token usage text to display in the status bar.</summary>
-    public string? UsageText { get; set; }
-
-    /// <summary>Gets or sets the queued input items to display above the rule.</summary>
-    public IReadOnlyList<object> QueuedItems { get; set; } = [];
-}
-
-/// <summary>
-/// Internal state for <see cref="HarnessAppComponent"/>.
-/// </summary>
-public record HarnessAppComponentState : ConsoleReactiveState
-{
-    /// <summary>Gets the selected index in list selection mode.</summary>
-    public int SelectedIndex { get; init; }
-
-    /// <summary>Gets the current input text being typed.</summary>
-    public string InputText { get; init; } = "";
-
-    /// <summary>Gets the current text being typed into the list's custom text option.</summary>
-    public string ListInputText { get; init; } = "";
-
-    /// <summary>Gets the current console width in columns.</summary>
-    public int ConsoleWidth { get; init; }
-
-    /// <summary>Gets the current console height in rows.</summary>
-    public int ConsoleHeight { get; init; }
-}
-
 /// <summary>
 /// The main application component for the Harness console. Manages the scroll region
-/// and bottom panel (text input, list selection, or streaming indicator), and emits
-/// an <see cref="InputSubmitted"/> event when the user submits text in any mode.
+/// and bottom panel (text input, list selection, or streaming indicator). Owns the
+/// <see cref="HarnessConsoleUXStateDriver"/> and routes user input events to the
+/// registered <see cref="HarnessAgentRunner"/>.
 /// </summary>
-public class HarnessAppComponent : ConsoleReactiveComponent<HarnessAppComponentProps, HarnessAppComponentState>, IDisposable
+public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps, HarnessAppComponentState>, IDisposable
 {
     private readonly TopBottomRule _rule = new();
     private readonly ListSelection _listSelection = new();
     private readonly TextInput _textInput = new();
-    private readonly TextScrollPanel _textScrollPanel;
-    private readonly TextPanel _textPanel;
-    private readonly TextPanel _queuedPanel;
+    private readonly TextScrollPanel _textScrollPanel = new();
+    private readonly TextPanel _textPanel = new();
+    private readonly TextPanel _queuedPanel = new();
     private readonly AgentStatus _agentStatus = new();
     private readonly AgentModeAndHelp _modeAndHelp = new();
-    private readonly Func<object, string> _renderItem;
-    private bool _resizedSinceLastRender;
+    private readonly HarnessConsoleUXStateDriver _uxDriver;
+    private readonly TaskCompletionSource<bool> _shutdownTcs = new(TaskCreationOptions.RunContinuationsAsynchronously);
+    private readonly SemaphoreSlim _followUpGate = new(1, 1);
+    private int _scrollRegionBottom;
+    private bool _resizedSinceLastRender = true;
     private bool _deactivated;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="HarnessAppComponent"/> class.
     /// </summary>
-    /// <param name="renderScrollItem">A delegate that renders a single output entry and returns the text to display.</param>
-    public HarnessAppComponent(Func<object, string> renderScrollItem)
+    /// <param name="placeholder">Placeholder text shown when the input is empty.</param>
+    /// <param name="initialMode">The current agent mode, used to colour the rule and prompt.</param>
+    /// <param name="inputEnabled">Whether the bottom-panel input accepts keystrokes during streaming.</param>
+    /// <param name="runnerFactory">Factory invoked with the component's <see cref="IUXStateDriver"/>
+    /// to construct the <see cref="HarnessAgentRunner"/> that owns the agent loop.</param>
+    /// <param name="modeColors">Optional mapping of mode names to console colors.</param>
+    public HarnessAppComponent(
+        string placeholder,
+        string? initialMode,
+        bool inputEnabled,
+        Func<IUXStateDriver, HarnessAgentRunner> runnerFactory,
+        IReadOnlyDictionary<string, ConsoleColor>? modeColors = null)
     {
-        this._renderItem = renderScrollItem;
-        this._textScrollPanel = new TextScrollPanel(renderScrollItem);
-        this._textPanel = new TextPanel(renderScrollItem);
-        this._queuedPanel = new TextPanel(renderScrollItem);
+        this.Props = new ConsoleReactiveProps();
         this.State = new HarnessAppComponentState
         {
+            Mode = BottomPanelMode.TextInput,
+            Prompt = "> ",
+            Placeholder = placeholder,
+            ModeColor = ModeColors.Get(initialMode, modeColors),
+            ModeText = initialMode,
+            InputEnabled = inputEnabled,
             ConsoleWidth = System.Console.WindowWidth,
             ConsoleHeight = System.Console.WindowHeight,
         };
+
+        this._uxDriver = new HarnessConsoleUXStateDriver(
+            getState: () => this.State!,
+            setState: s => this.SetState(s),
+            requestShutdown: () => this._shutdownTcs.TrySetResult(true),
+            modeColors: modeColors);
+
+        this.Runner = runnerFactory(this._uxDriver);
+
+        // Seed help text now that the runner (which knows the registered command handlers)
+        // is available. Direct assignment — no Render is triggered until the caller invokes Render().
+        this.State = this.State with { HelpText = this.Runner.HelpText };
+
         KeyEventListener.Instance.KeyPressed += this.OnKeyPressed;
         ConsoleResizeListener.Instance.ConsoleResized += this.OnConsoleResized;
     }
 
     /// <summary>
-    /// Gets the 1-based row number of the last row in the output scroll region.
+    /// Gets the agent runner that owns the agent loop. Constructed by the factory
+    /// passed to the component's constructor.
     /// </summary>
-    public int ScrollRegionBottom { get; private set; }
+    public HarnessAgentRunner Runner { get; }
 
     /// <summary>
-    /// Occurs when the user submits input via Enter, in any mode (text input, list selection,
-    /// or streaming injection). Consumers inspect <see cref="InputSubmittedEventArgs.Mode"/>
-    /// to decide how to handle the submission.
+    /// Completes when a command handler requests application shutdown (e.g. the user types <c>/exit</c>).
+    /// Awaited by <see cref="HarnessConsole.RunAgentAsync"/>.
     /// </summary>
-    public event EventHandler<InputSubmittedEventArgs>? InputSubmitted;
+    public Task ShutdownTask => this._shutdownTcs.Task;
 
     /// <summary>
     /// Deactivates the component, resetting the scroll region and unsubscribing from events.
@@ -184,9 +102,6 @@ public class HarnessAppComponent : ConsoleReactiveComponent<HarnessAppComponentP
         this._agentStatus.Dispose();
         KeyEventListener.Instance.KeyPressed -= this.OnKeyPressed;
         ConsoleResizeListener.Instance.ConsoleResized -= this.OnConsoleResized;
-        System.Console.Write(AnsiEscapes.ResetScrollRegion);
-        System.Console.Write(AnsiEscapes.MoveCursor(System.Console.WindowHeight, 1));
-        System.Console.WriteLine();
     }
 
     /// <inheritdoc/>
@@ -205,20 +120,23 @@ public class HarnessAppComponent : ConsoleReactiveComponent<HarnessAppComponentP
         if (disposing)
         {
             this.Deactivate();
+            this._followUpGate.Dispose();
+            this.Runner.Dispose();
         }
     }
 
     private void OnKeyPressed(object? sender, KeyPressEventArgs e)
     {
-        if (this.Props!.Mode == BottomPanelMode.TextInput)
+        BottomPanelMode mode = this.State!.Mode;
+        if (mode == BottomPanelMode.TextInput)
         {
             this.HandleTextInputKey(e);
         }
-        else if (this.Props.Mode == BottomPanelMode.ListSelection)
+        else if (mode == BottomPanelMode.ListSelection)
         {
             this.HandleListSelectionKey(e);
         }
-        else if (this.Props.Mode == BottomPanelMode.Streaming && this.Props.InputEnabled)
+        else if (mode == BottomPanelMode.Streaming && this.State.InputEnabled)
         {
             this.HandleStreamingInputKey(e);
         }
@@ -235,7 +153,7 @@ public class HarnessAppComponent : ConsoleReactiveComponent<HarnessAppComponentP
             }
 
             this.SetState(this.State with { InputText = "" });
-            this.InputSubmitted?.Invoke(this, new InputSubmittedEventArgs(text, BottomPanelMode.TextInput));
+            this.DispatchTextInputSubmission(text);
         }
         else if (e.KeyInfo.Key == ConsoleKey.Backspace)
         {
@@ -252,51 +170,50 @@ public class HarnessAppComponent : ConsoleReactiveComponent<HarnessAppComponentP
 
     private void HandleListSelectionKey(KeyPressEventArgs e)
     {
-        int maxIndex = this.Props!.Items.Count - 1;
-        if (this.Props.ListCustomTextPlaceholder != null)
+        int maxIndex = this.State!.ListSelectionOptions.Count - 1;
+        if (this.State.ListSelectionCustomTextPlaceholder != null)
         {
-            maxIndex = this.Props.Items.Count;
+            maxIndex = this.State.ListSelectionOptions.Count;
         }
 
-        bool isOnCustomTextOption = this.Props.ListCustomTextPlaceholder != null
-            && this.State!.SelectedIndex == this.Props.Items.Count;
+        bool isOnCustomTextOption = this.State.ListSelectionCustomTextPlaceholder != null
+            && this.State.ListSelectionIndex == this.State.ListSelectionOptions.Count;
 
         if (e.KeyInfo.Key == ConsoleKey.UpArrow)
         {
-            this.SetState(this.State! with { SelectedIndex = Math.Max(0, this.State.SelectedIndex - 1) });
+            this.SetState(this.State with { ListSelectionIndex = Math.Max(0, this.State.ListSelectionIndex - 1) });
         }
         else if (e.KeyInfo.Key == ConsoleKey.DownArrow)
         {
-            this.SetState(this.State! with { SelectedIndex = Math.Min(maxIndex, this.State.SelectedIndex + 1) });
+            this.SetState(this.State with { ListSelectionIndex = Math.Min(maxIndex, this.State.ListSelectionIndex + 1) });
         }
         else if (e.KeyInfo.Key == ConsoleKey.Enter)
         {
             string result = isOnCustomTextOption
-                ? this.State!.ListInputText
-                : this.Props.Items[this.State!.SelectedIndex];
+                ? this.State.ListSelectionCustomInputText
+                : this.State.ListSelectionOptions[this.State.ListSelectionIndex];
 
-            this.SetState(this.State with { ListInputText = "", SelectedIndex = 0 });
-            this.InputSubmitted?.Invoke(this, new InputSubmittedEventArgs(result, BottomPanelMode.ListSelection));
+            this.SetState(this.State with { ListSelectionCustomInputText = "", ListSelectionIndex = 0 });
+            this.DispatchListSelectionSubmission(result);
         }
         else if (isOnCustomTextOption)
         {
             if (e.KeyInfo.Key == ConsoleKey.Backspace)
             {
-                if (this.State!.ListInputText.Length > 0)
+                if (this.State.ListSelectionCustomInputText.Length > 0)
                 {
-                    this.SetState(this.State with { ListInputText = this.State.ListInputText[..^1] });
+                    this.SetState(this.State with { ListSelectionCustomInputText = this.State.ListSelectionCustomInputText[..^1] });
                 }
             }
             else if (e.KeyInfo.KeyChar != '\0' && !char.IsControl(e.KeyInfo.KeyChar))
             {
-                this.SetState(this.State! with { ListInputText = this.State.ListInputText + e.KeyInfo.KeyChar });
+                this.SetState(this.State with { ListSelectionCustomInputText = this.State.ListSelectionCustomInputText + e.KeyInfo.KeyChar });
             }
         }
     }
 
     private void HandleStreamingInputKey(KeyPressEventArgs e)
     {
-        // During streaming with input enabled, capture text for message injection
         if (e.KeyInfo.Key == ConsoleKey.Enter)
         {
             string text = this.State!.InputText;
@@ -306,7 +223,7 @@ public class HarnessAppComponent : ConsoleReactiveComponent<HarnessAppComponentP
             }
 
             this.SetState(this.State with { InputText = "" });
-            this.InputSubmitted?.Invoke(this, new InputSubmittedEventArgs(text, BottomPanelMode.Streaming));
+            _ = this.Runner.OnStreamingInputAsync(text);
         }
         else if (e.KeyInfo.Key == ConsoleKey.Backspace)
         {
@@ -321,6 +238,90 @@ public class HarnessAppComponent : ConsoleReactiveComponent<HarnessAppComponentP
         }
     }
 
+    private void DispatchTextInputSubmission(string text)
+    {
+        if (this.State!.PendingQuestions.Count > 0)
+        {
+            _ = this.HandleFollowUpAnswerAsync(text);
+        }
+        else
+        {
+            _ = this.Runner.OnUserInputAsync(text);
+        }
+    }
+
+    private void DispatchListSelectionSubmission(string text)
+    {
+        // List selection is only used to answer FollowUpQuestions.
+        _ = this.HandleFollowUpAnswerAsync(text);
+    }
+
+    /// <summary>
+    /// Handles a user answer to the head of the pending follow-up question queue:
+    /// awaits the question's continuation (which is responsible for echoing both the
+    /// question and answer to the scroll area as it sees fit), appends any returned
+    /// chat message to the response accumulator, advances the queue, and — when the
+    /// queue empties — drains the accumulator and resumes the runner.
+    /// </summary>
+    private async Task HandleFollowUpAnswerAsync(string text)
+    {
+        IReadOnlyList<ChatMessage>? messagesToSend = null;
+
+        await this._followUpGate.WaitAsync().ConfigureAwait(false);
+        try
+        {
+            HarnessConsoleUXStateDriver ux = this._uxDriver;
+            IReadOnlyList<FollowUpQuestion> queue = this.State!.PendingQuestions;
+            if (queue.Count == 0)
+            {
+                return;
+            }
+
+            FollowUpQuestion head = queue[0];
+
+            ChatMessage? response;
+            try
+            {
+                response = await head.Continuation(text, ux).ConfigureAwait(false);
+            }
+            catch (Exception ex)
+            {
+                await ux.WriteInfoLineAsync($"❌ Follow-up handler error: {ex.GetType().Name}: {ex.Message}", ConsoleColor.Red).ConfigureAwait(false);
+                response = null;
+            }
+
+            if (response is not null)
+            {
+                ux.AddFollowUpResponse(response);
+            }
+
+            ux.AdvanceFollowUpQuestion();
+
+            if (this.State!.PendingQuestions.Count == 0)
+            {
+                messagesToSend = ux.TakeFollowUpResponses();
+            }
+        }
+        finally
+        {
+            this._followUpGate.Release();
+        }
+
+        // Resume the agent outside the gate — StartAgentTurnAsync runs the full agent
+        // loop which may queue new follow-up questions (re-entering this method).
+        if (messagesToSend is not null)
+        {
+            try
+            {
+                await this.Runner.StartAgentTurnAsync([.. messagesToSend]).ConfigureAwait(false);
+            }
+            catch (Exception ex)
+            {
+                await this._uxDriver.WriteInfoLineAsync($"❌ Agent error: {ex.GetType().Name}: {ex.Message}", ConsoleColor.Red).ConfigureAwait(false);
+            }
+        }
+    }
+
     private void OnConsoleResized(object? sender, ConsoleResizeEventArgs e)
     {
         this._resizedSinceLastRender = true;
@@ -332,35 +333,40 @@ public class HarnessAppComponent : ConsoleReactiveComponent<HarnessAppComponentP
     }
 
     /// <inheritdoc />
-    public override void RenderCore(HarnessAppComponentProps props, HarnessAppComponentState state)
+    public override void RenderCore(ConsoleReactiveProps props, HarnessAppComponentState state)
     {
+        if (this._deactivated)
+        {
+            return;
+        }
+
         // Determine the text panel height for the last scroll item
-        IReadOnlyList<object> lastItems = props.ScrollItems.Count > 0
-            ? [props.ScrollItems[^1]]
+        IReadOnlyList<string> lastItems = state.ScrollAreaContentItems.Count > 0
+            ? [state.ScrollAreaContentItems[^1]]
             : [];
-        int textPanelHeight = TextPanel.CalculateHeight(lastItems, this._renderItem);
+        int textPanelHeight = TextPanel.CalculateHeight(lastItems);
         if (textPanelHeight > 0)
         {
             textPanelHeight++; // Extra line for spacing between text panel and rule
         }
 
         // Calculate queued items panel height
-        int queuedPanelHeight = TextPanel.CalculateHeight(props.QueuedItems, this._renderItem);
+        int queuedPanelHeight = TextPanel.CalculateHeight(state.QueuedItems);
 
         // Build the bottom panel child based on mode
         ConsoleReactiveComponent bottomChild;
         int bottomChildHeight;
 
-        if (props.Mode == BottomPanelMode.ListSelection)
+        if (state.Mode == BottomPanelMode.ListSelection)
         {
             var listProps = new ListSelectionProps
             {
-                Title = props.ListTitle,
-                Items = props.Items,
-                SelectedIndex = state.SelectedIndex,
-                HighlightColor = props.ListHighlightColor,
-                CustomTextPlaceholder = props.ListCustomTextPlaceholder,
-                CustomText = state.ListInputText,
+                Title = state.ListSelectionTitle,
+                Items = state.ListSelectionOptions,
+                SelectedIndex = state.ListSelectionIndex,
+                HighlightColor = state.ListHighlightColor,
+                CustomTextPlaceholder = state.ListSelectionCustomTextPlaceholder,
+                CustomText = state.ListSelectionCustomInputText,
             };
 
             bottomChildHeight = ListSelection.CalculateHeight(listProps);
@@ -368,25 +374,25 @@ public class HarnessAppComponent : ConsoleReactiveComponent<HarnessAppComponentP
             this._listSelection.Props = listProps;
             bottomChild = this._listSelection;
         }
-        else if (props.Mode == BottomPanelMode.Streaming)
+        else if (state.Mode == BottomPanelMode.Streaming)
         {
             TextInputProps textInputProps;
-            if (props.InputEnabled)
+            if (state.InputEnabled)
             {
                 textInputProps = new TextInputProps
                 {
-                    Prompt = props.Prompt,
+                    Prompt = state.Prompt,
                     Text = state.InputText,
-                    Placeholder = props.Placeholder,
+                    Placeholder = state.Placeholder,
                 };
             }
             else
             {
                 textInputProps = new TextInputProps
                 {
-                    Prompt = props.Prompt,
+                    Prompt = state.Prompt,
                     Text = "",
-                    Placeholder = props.StreamingPrompt,
+                    Placeholder = state.StreamingPrompt,
                 };
             }
 
@@ -400,9 +406,9 @@ public class HarnessAppComponent : ConsoleReactiveComponent<HarnessAppComponentP
         {
             var textInputProps = new TextInputProps
             {
-                Prompt = props.Prompt,
+                Prompt = state.Prompt,
                 Text = state.InputText,
-                Placeholder = props.Placeholder,
+                Placeholder = state.Placeholder,
             };
 
             bottomChildHeight = TextInput.CalculateHeight(textInputProps, state.ConsoleWidth);
@@ -415,46 +421,52 @@ public class HarnessAppComponent : ConsoleReactiveComponent<HarnessAppComponentP
         var ruleProps = new TopBottomRuleProps
         {
             Width = state.ConsoleWidth,
-            Color = props.ModeColor,
+            Color = state.ModeColor,
             Children = [bottomChild],
         };
 
-        // Calculate the agent status height
         var agentStatusProps = new AgentStatusProps
         {
-            ShowSpinner = props.ShowSpinner,
-            UsageText = props.UsageText,
+            ShowSpinner = state.ShowSpinner,
+            UsageText = state.UsageText,
         };
-        int agentStatusHeight = AgentStatus.CalculateHeight(agentStatusProps);
 
-        // Calculate the mode-and-help height
         var modeAndHelpProps = new AgentModeAndHelpProps
         {
-            Mode = props.ModeText,
-            ModeColor = props.ModeColor,
-            HelpText = props.HelpText,
+            Mode = state.ModeText,
+            ModeColor = state.ModeColor,
+            HelpText = state.HelpText,
         };
-        int modeAndHelpHeight = AgentModeAndHelp.CalculateHeight(modeAndHelpProps);
+
+        // Hide agent status and mode/help during follow-up questions (ListSelection mode)
+        // as they clutter the UI and aren't relevant.
+        bool showStatusAndHelp = state.Mode != BottomPanelMode.ListSelection;
+        int agentStatusHeight = showStatusAndHelp ? AgentStatus.CalculateHeight(agentStatusProps) : 0;
+        int modeAndHelpHeight = showStatusAndHelp ? AgentModeAndHelp.CalculateHeight(modeAndHelpProps) : 0;
 
         int ruleHeight = TopBottomRule.CalculateHeight(ruleProps);
-        int scrollBottom = Math.Max(1, state.ConsoleHeight - ruleHeight - textPanelHeight - agentStatusHeight - queuedPanelHeight - modeAndHelpHeight);
+        int nonScrollHeight = ruleHeight + textPanelHeight + agentStatusHeight + queuedPanelHeight + modeAndHelpHeight + 1; // +1 for bottom padding
+        int scrollBottom = Math.Max(1, state.ConsoleHeight - nonScrollHeight);
 
         // If scroll region changed or a clear is needed, reset everything
-        if (this._resizedSinceLastRender || (this.ScrollRegionBottom != 0 && scrollBottom != this.ScrollRegionBottom))
+        if (this._resizedSinceLastRender || (this._scrollRegionBottom != 0 && scrollBottom != this._scrollRegionBottom))
         {
+            // Reset scroll region to full screen before erasing so the erase covers all rows —
+            // some terminals only erase within the active DECSTBM region.
+            System.Console.Write(AnsiEscapes.ResetScrollRegion);
             System.Console.Write(AnsiEscapes.EraseEntireScreen);
             System.Console.Write(AnsiEscapes.EraseScrollbackBuffer);
             this._textScrollPanel.Reset();
             this._resizedSinceLastRender = false;
         }
 
-        this.ScrollRegionBottom = scrollBottom;
+        this._scrollRegionBottom = scrollBottom;
 
         System.Console.Write(AnsiEscapes.SetScrollRegion(scrollBottom));
 
         // Render text scroll panel in the scroll area (all items except the last)
-        IReadOnlyList<object> scrollItems = props.ScrollItems.Count > 1
-            ? props.ScrollItems.Take(props.ScrollItems.Count - 1).ToList()
+        IReadOnlyList<string> scrollItems = state.ScrollAreaContentItems.Count > 1
+            ? state.ScrollAreaContentItems.Take(state.ScrollAreaContentItems.Count - 1).ToList()
             : [];
 
         this._textScrollPanel.X = 1;
@@ -486,18 +498,21 @@ public class HarnessAppComponent : ConsoleReactiveComponent<HarnessAppComponentP
         this._queuedPanel.Height = queuedPanelHeight;
         this._queuedPanel.Props = new TextPanelProps
         {
-            Items = props.QueuedItems,
+            Items = state.QueuedItems,
         };
         this._queuedPanel.Render();
 
         // Render the agent status line between queued items and rule
         int agentStatusY = queuedPanelY + queuedPanelHeight;
-        this._agentStatus.X = 1;
-        this._agentStatus.Y = agentStatusY;
-        this._agentStatus.Width = state.ConsoleWidth;
-        this._agentStatus.Height = agentStatusHeight;
-        this._agentStatus.Props = agentStatusProps;
-        this._agentStatus.Render();
+        if (showStatusAndHelp)
+        {
+            this._agentStatus.X = 1;
+            this._agentStatus.Y = agentStatusY;
+            this._agentStatus.Width = state.ConsoleWidth;
+            this._agentStatus.Height = agentStatusHeight;
+            this._agentStatus.Props = agentStatusProps;
+            this._agentStatus.Render();
+        }
 
         // Render the bottom rule + child below the agent status
         this._rule.X = 1;
@@ -506,24 +521,27 @@ public class HarnessAppComponent : ConsoleReactiveComponent<HarnessAppComponentP
         this._rule.Render();
 
         // Render the mode-and-help line below the bottom rule
-        int modeAndHelpY = this._rule.Y + ruleHeight;
-        this._modeAndHelp.X = 1;
-        this._modeAndHelp.Y = modeAndHelpY;
-        this._modeAndHelp.Width = state.ConsoleWidth;
-        this._modeAndHelp.Height = modeAndHelpHeight;
-        this._modeAndHelp.Props = modeAndHelpProps;
-        this._modeAndHelp.Render();
+        if (showStatusAndHelp)
+        {
+            int modeAndHelpY = this._rule.Y + ruleHeight;
+            this._modeAndHelp.X = 1;
+            this._modeAndHelp.Y = modeAndHelpY;
+            this._modeAndHelp.Width = state.ConsoleWidth;
+            this._modeAndHelp.Height = modeAndHelpHeight;
+            this._modeAndHelp.Props = modeAndHelpProps;
+            this._modeAndHelp.Render();
+        }
 
         // Position cursor for natural typing appearance
-        this.PositionCursor(props, state);
+        this.PositionCursor(state);
     }
 
-    private void PositionCursor(HarnessAppComponentProps props, HarnessAppComponentState state)
+    private void PositionCursor(HarnessAppComponentState state)
     {
-        if (props.Mode == BottomPanelMode.TextInput
-            || (props.Mode == BottomPanelMode.Streaming && props.InputEnabled))
+        if (state.Mode == BottomPanelMode.TextInput
+            || (state.Mode == BottomPanelMode.Streaming && state.InputEnabled))
         {
-            int promptLength = props.Prompt.Length;
+            int promptLength = state.Prompt.Length;
             int textWidth = state.ConsoleWidth - promptLength;
             int textLength = state.InputText.Length;
 
@@ -540,13 +558,13 @@ public class HarnessAppComponent : ConsoleReactiveComponent<HarnessAppComponentP
                 System.Console.Write(AnsiEscapes.MoveCursor(textInputY + cursorRow, promptLength + cursorCol + 1));
             }
         }
-        else if (props.Mode == BottomPanelMode.ListSelection
-            && props.ListCustomTextPlaceholder != null
-            && state.SelectedIndex == props.Items.Count)
+        else if (state.Mode == BottomPanelMode.ListSelection
+            && state.ListSelectionCustomTextPlaceholder != null
+            && state.ListSelectionIndex == state.ListSelectionOptions.Count)
         {
-            int titleLines = props.ListTitle?.Split('\n').Length ?? 0;
-            int customOptionY = this._rule.Y + 1 + titleLines + props.Items.Count;
-            int cursorCol = 2 + state.ListInputText.Length + 1;
+            int titleLines = state.ListSelectionTitle?.Split('\n').Length ?? 0;
+            int customOptionY = this._rule.Y + 1 + titleLines + state.ListSelectionOptions.Count;
+            int cursorCol = 2 + state.ListSelectionCustomInputText.Length + 1;
             System.Console.Write(AnsiEscapes.MoveCursor(customOptionY, cursorCol));
         }
     }

dotnet/samples/02-agents/Harness/Harness_Shared_Console/HarnessAppComponentState.cs

@@ -0,0 +1,125 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Harness.ConsoleReactiveFramework;
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console;
+
+/// <summary>
+/// Determines which component is shown in the bottom panel.
+/// </summary>
+public enum BottomPanelMode
+{
+    /// <summary>Show the text input component for user input.</summary>
+    TextInput,
+
+    /// <summary>Show the list selection component for interactive prompts.</summary>
+    ListSelection,
+
+    /// <summary>Show a disabled input indicator during agent streaming.</summary>
+    Streaming,
+}
+
+/// <summary>
+/// Internal state for <see cref="HarnessAppComponent"/>. All UI fields that may
+/// change after construction live here; they are mutated exclusively via
+/// <see cref="ConsoleReactiveComponent{TProps,TState}.SetState"/> by the
+/// owning <see cref="HarnessConsoleUXStateDriver"/>.
+/// </summary>
+public record HarnessAppComponentState : ConsoleReactiveState
+{
+    // --- Console dimensions ---
+
+    /// <summary>Gets the current console width in columns.</summary>
+    public int ConsoleWidth { get; init; }
+
+    /// <summary>Gets the current console height in rows.</summary>
+    public int ConsoleHeight { get; init; }
+
+    // --- Bottom panel mode ---
+
+    /// <summary>Gets the bottom panel mode.</summary>
+    public BottomPanelMode Mode { get; init; } = BottomPanelMode.TextInput;
+
+    /// <summary>
+    /// Gets the queue of follow-up questions waiting for user answers. The head
+    /// (<c>[0]</c>) is the question currently being displayed; subsequent items
+    /// are dispatched in order as each is answered. While this queue is non-empty,
+    /// the next user submission is treated as the answer to the head question
+    /// instead of going to the agent runner's normal input handler.
+    /// </summary>
+    public IReadOnlyList<FollowUpQuestion> PendingQuestions { get; init; } = [];
+
+    /// <summary>
+    /// Gets the accumulated follow-up response messages collected during the
+    /// current agent turn — both direct <see cref="FollowUpMessage"/>s emitted
+    /// by observers and continuation results from answered questions. Consumed
+    /// by the runner via <see cref="IUXStateDriver.TakeFollowUpResponses"/>
+    /// before the next agent invocation.
+    /// </summary>
+    public IReadOnlyList<ChatMessage> AccumulatedFollowUpResponses { get; init; } = [];
+
+    // --- Text input (active in TextInput / Streaming modes) ---
+
+    /// <summary>Gets the prompt string for text input mode.</summary>
+    public string Prompt { get; init; } = "> ";
+
+    /// <summary>Gets the placeholder text shown when the input is empty.</summary>
+    public string Placeholder { get; init; } = "";
+
+    /// <summary>Gets the current input text being typed.</summary>
+    public string InputText { get; init; } = "";
+
+    /// <summary>Gets a value indicating whether input is enabled during streaming.</summary>
+    public bool InputEnabled { get; init; }
+
+    /// <summary>Gets the prompt to show during streaming when input is disabled.</summary>
+    public string StreamingPrompt { get; init; } = "(agent is running...)";
+
+    // --- List selection (active in ListSelection mode) ---
+
+    /// <summary>Gets the title text displayed above the list selection (for interactive prompts).</summary>
+    public string? ListSelectionTitle { get; init; }
+
+    /// <summary>Gets the list selection options.</summary>
+    public IReadOnlyList<string> ListSelectionOptions { get; init; } = [];
+
+    /// <summary>Gets the highlighted option index in list selection mode.</summary>
+    public int ListSelectionIndex { get; init; }
+
+    /// <summary>Gets the placeholder text for the custom text input option in the list.</summary>
+    public string? ListSelectionCustomTextPlaceholder { get; init; }
+
+    /// <summary>Gets the current text being typed into the list's custom text option.</summary>
+    public string ListSelectionCustomInputText { get; init; } = "";
+
+    /// <summary>Gets the highlight color for the active list item.</summary>
+    public ConsoleColor ListHighlightColor { get; init; } = ConsoleColor.Cyan;
+
+    // --- Scroll / output area ---
+
+    /// <summary>Gets the items rendered in the scroll-area. Each item is a pre-rendered
+    /// console string (may include ANSI escape sequences and newlines).</summary>
+    public IReadOnlyList<string> ScrollAreaContentItems { get; init; } = [];
+
+    /// <summary>Gets the queued input items to display above the rule. Each item is a
+    /// pre-rendered console string (may include ANSI escape sequences and newlines).</summary>
+    public IReadOnlyList<string> QueuedItems { get; init; } = [];
+
+    // --- Agent mode + status display ---
+
+    /// <summary>Gets the foreground color for the rule borders and mode label.</summary>
+    public ConsoleColor? ModeColor { get; init; }
+
+    /// <summary>Gets the current mode name displayed below the bottom rule (e.g. "plan").</summary>
+    public string? ModeText { get; init; }
+
+    /// <summary>Gets the help text displayed below the bottom rule (available commands).</summary>
+    public string? HelpText { get; init; }
+
+    /// <summary>Gets a value indicating whether the agent status spinner is visible.</summary>
+    public bool ShowSpinner { get; init; }
+
+    /// <summary>Gets the formatted token usage text to display in the status bar.</summary>
+    public string? UsageText { get; init; }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/HarnessConsole.cs

@@ -1,9 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-using Harness.Shared.Console.Commands;
-using Harness.Shared.Console.Observers;
+using Harness.ConsoleReactiveComponents;
 using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
 
 namespace Harness.Shared.Console;
 
@@ -15,244 +13,58 @@ public static class HarnessConsole
 {
     /// <summary>
     /// Runs an interactive console session with the specified agent.
-    /// Supports streaming output, tool call display, spinner animation,
-    /// optional planning UX with structured output, and the <c>/todos</c> command.
+    /// Constructs the reactive UI component and the <see cref="HarnessAgentRunner"/>,
+    /// wires them together, and awaits the component's <see cref="HarnessAppComponent.ShutdownTask"/>
+    /// (which completes when the user types <c>/exit</c>).
     /// </summary>
     /// <param name="agent">The agent to interact with.</param>
-    /// <param name="title">The title displayed in the console header.</param>
-    /// <param name="userPrompt">A short prompt to the user, displayed below the title.</param>
+    /// <param name="userPrompt">A short prompt to the user, displayed as a placeholder in the input area.</param>
     /// <param name="options">Optional configuration options for the console session.</param>
-    public static async Task RunAgentAsync(AIAgent agent, string title, string userPrompt, HarnessConsoleOptions? options = null)
+    public static async Task RunAgentAsync(AIAgent agent, string userPrompt, HarnessConsoleOptions? options = null)
     {
         options ??= new();
 
-        if (options.EnablePlanningUx
-            && (string.IsNullOrWhiteSpace(options.PlanningModeName) || string.IsNullOrWhiteSpace(options.ExecutionModeName)))
-        {
-            throw new ArgumentException(
-                "When EnablePlanningUx is true, both PlanningModeName and ExecutionModeName must be configured.",
-                nameof(options));
-        }
+        // Null means use defaults; an explicit (possibly empty) list means use exactly what was provided.
+        var observers = options.Observers
+            ?? HarnessConsoleOptions.BuildDefaultObservers();
+        var commandHandlers = options.CommandHandlers
+            ?? HarnessConsoleOptions.BuildDefaultCommandHandlers(agent, options.ModeColors);
 
-        var todoProvider = agent.GetService<TodoProvider>();
         var modeProvider = agent.GetService<AgentModeProvider>();
         var messageInjector = agent.GetService<MessageInjectingChatClient>();
 
-        var commandHandlers = new List<CommandHandler>
-        {
-            new TodoCommandHandler(todoProvider),
-            new ModeCommandHandler(modeProvider, options.ModeColors),
-        };
-
         AgentSession session = await agent.CreateSessionAsync();
 
-        using var ux = new HarnessUXContainer(
+        using var component = new HarnessAppComponent(
             placeholder: userPrompt,
             initialMode: modeProvider?.GetMode(session),
             inputEnabled: messageInjector is not null,
+            runnerFactory: ux => new HarnessAgentRunner(
+                agent: agent,
+                session: session,
+                modeProvider: modeProvider,
+                messageInjector: messageInjector,
+                commandHandlers: commandHandlers,
+                observers: observers,
+                ux: ux),
             modeColors: options.ModeColors);
 
-        // Streaming-mode submissions are enqueued for injection; the queued display
-        // is then refreshed from the injector's current pending list.
-        ux.StreamingInputReceived += (sender, e) =>
+        // Trigger the initial render of the component now that state is seeded.
+        component.Render();
+
+        try
         {
-            if (messageInjector is null)
-            {
-                return;
-            }
-
-            messageInjector.EnqueueMessages(session, [new ChatMessage(ChatRole.User, e.Text)]);
-            ux.ShowQueuedMessages(messageInjector.GetPendingMessages(session));
-        };
-
-        var commandHelp = commandHandlers
-            .Select(h => h.GetHelpText())
-            .Where(t => t is not null)
-            .Append("exit (quit)")!;
-
-        ux.Initialize(title, commandHelp!, messageInjector is not null);
-
-        string userInput = await ux.WaitForInputAsync();
-
-        while (!string.IsNullOrWhiteSpace(userInput) && !userInput.Equals("exit", StringComparison.OrdinalIgnoreCase))
+            await component.ShutdownTask.ConfigureAwait(false);
+        }
+        finally
         {
-            ux.WriteUserInputEcho(userInput);
-
-            // Check command handlers first — first one to handle wins.
-            bool handled = false;
-            foreach (var handler in commandHandlers)
-            {
-                if (await handler.TryHandleAsync(userInput, session, ux).ConfigureAwait(false))
-                {
-                    handled = true;
-                    break;
-                }
-            }
-
-            if (!handled)
-            {
-                await RunAgentTurnAsync(agent, session, modeProvider, messageInjector, options, ux, userInput);
-            }
-
-            ux.CurrentMode = modeProvider?.GetMode(session);
-            userInput = await ux.WaitForInputAsync();
+            component.Deactivate();
         }
 
-        ux.Deactivate();
         System.Console.ResetColor();
+        System.Console.Write(AnsiEscapes.ResetScrollRegion);
+        System.Console.Write(AnsiEscapes.EraseEntireScreen);
+        System.Console.Write(AnsiEscapes.MoveCursor(1, 1));
         System.Console.WriteLine("Goodbye!");
     }
-
-    /// <summary>
-    /// Runs one or more agent invocations for a single user turn, using the current
-    /// observers. Re-invokes automatically for tool approvals and mode-driven follow-ups
-    /// (e.g., planning clarification loops).
-    /// </summary>
-    private static async Task RunAgentTurnAsync(
-        AIAgent agent,
-        AgentSession session,
-        AgentModeProvider? modeProvider,
-        MessageInjectingChatClient? messageInjector,
-        HarnessConsoleOptions options,
-        HarnessUXContainer ux,
-        string userInput)
-    {
-        IList<ChatMessage>? nextMessages = [new ChatMessage(ChatRole.User, userInput)];
-        IReadOnlyList<ChatMessage> lastPendingMessages = messageInjector?.GetPendingMessages(session) ?? [];
-
-        while (nextMessages is not null)
-        {
-            var observers = CreateObservers(options, modeProvider, session);
-
-            var runOptions = new AgentRunOptions();
-            foreach (var observer in observers)
-            {
-                observer.ConfigureRunOptions(runOptions);
-            }
-
-            ux.CurrentMode = modeProvider?.GetMode(session);
-            ux.BeginStreaming();
-            ux.BeginStreamingOutput();
-
-            try
-            {
-                await foreach (var update in agent.RunStreamingAsync(nextMessages, session, runOptions))
-                {
-                    // Update mode color if the mode changed during streaming.
-                    if (modeProvider is not null)
-                    {
-                        string currentMode = modeProvider.GetMode(session);
-                        if (currentMode != ux.CurrentMode)
-                        {
-                            ux.CurrentMode = currentMode;
-                        }
-                    }
-
-                    foreach (var content in update.Contents)
-                    {
-                        foreach (var observer in observers)
-                        {
-                            await observer.OnContentAsync(ux, content);
-                        }
-                    }
-
-                    if (!string.IsNullOrEmpty(update.Text))
-                    {
-                        foreach (var observer in observers)
-                        {
-                            await observer.OnTextAsync(ux, update.Text);
-                        }
-                    }
-
-                    SyncQueuedMessageDisplay(messageInjector, session, ux, ref lastPendingMessages);
-                }
-            }
-            catch (Exception ex)
-            {
-                await ux.WriteInfoLineAsync($"❌ Stream error: {ex.GetType().Name}:\n{ex}", ConsoleColor.Red);
-            }
-
-            // Final sync after streaming — messages may have been consumed during the last iteration.
-            SyncQueuedMessageDisplay(messageInjector, session, ux, ref lastPendingMessages);
-
-            // Stop spinner before observer completions (which may prompt for input).
-            ux.StopSpinner();
-
-            // Close the streaming output to provide visual separation from observer output.
-            await ux.EndStreamingOutputAsync();
-
-            var combinedMessages = new List<ChatMessage>();
-            bool hasObserverMessages = false;
-            foreach (var observer in observers)
-            {
-                var messages = await observer.OnStreamCompleteAsync(ux, agent, session, options);
-                if (messages is { Count: > 0 })
-                {
-                    combinedMessages.AddRange(messages);
-                    hasObserverMessages = true;
-                }
-            }
-
-            await ux.WriteNoTextWarningAsync(hasFollowUpMessages: hasObserverMessages);
-
-            ux.EndStreaming();
-
-            nextMessages = combinedMessages.Count > 0 ? combinedMessages : null;
-        }
-    }
-
-    /// <summary>
-    /// Synchronizes the queued items display with the message injector's pending messages.
-    /// Messages that have been consumed (drained by the service) are echoed to the output
-    /// area as regular user-input entries.
-    /// </summary>
-    private static void SyncQueuedMessageDisplay(
-        MessageInjectingChatClient? messageInjector,
-        AgentSession session,
-        HarnessUXContainer ux,
-        ref IReadOnlyList<ChatMessage> lastPendingMessages)
-    {
-        if (messageInjector is null)
-        {
-            return;
-        }
-
-        var pending = messageInjector.GetPendingMessages(session);
-
-        // If previously pending messages exceed current pending count, some were consumed.
-        int consumedCount = lastPendingMessages.Count - pending.Count;
-        for (int i = 0; i < consumedCount && i < lastPendingMessages.Count; i++)
-        {
-            string text = lastPendingMessages[i].Text ?? string.Empty;
-            ux.WriteUserInputEcho(text);
-        }
-
-        lastPendingMessages = pending;
-        ux.ShowQueuedMessages(pending);
-    }
-
-    private static List<ConsoleObserver> CreateObservers(HarnessConsoleOptions options, AgentModeProvider? modeProvider, AgentSession session)
-    {
-        var observers = new List<ConsoleObserver>
-        {
-            new ToolCallDisplayObserver(),
-            new ToolApprovalObserver(),
-            new ErrorDisplayObserver(),
-            new ReasoningDisplayObserver(),
-            new UsageDisplayObserver(options.MaxContextWindowTokens, options.MaxOutputTokens),
-        };
-
-        if (options.EnablePlanningUx
-            && modeProvider is not null
-            && string.Equals(modeProvider.GetMode(session), options.PlanningModeName, StringComparison.OrdinalIgnoreCase))
-        {
-            observers.Add(new PlanningOutputObserver(modeProvider));
-        }
-        else
-        {
-            observers.Add(new TextOutputObserver());
-        }
-
-        return observers;
-    }
 }

dotnet/samples/02-agents/Harness/Harness_Shared_Console/HarnessConsoleOptions.cs

@@ -1,5 +1,11 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using System.Collections.ObjectModel;
+using Harness.Shared.Console.Commands;
+using Harness.Shared.Console.Observers;
+using Harness.Shared.Console.ToolFormatters;
+using Microsoft.Agents.AI;
+
 namespace Harness.Shared.Console;
 
 /// <summary>
@@ -8,45 +14,120 @@ namespace Harness.Shared.Console;
 public class HarnessConsoleOptions
 {
     /// <summary>
-    /// Gets or sets the optional maximum context window size in tokens.
-    /// When set, token usage is displayed as a percentage of the budget.
+    /// Gets or sets the list of console observers that participate in the agent response
+    /// streaming lifecycle. Use the factory methods on this class to create common observer sets.
+    /// When <see langword="null"/> (the default), a default set of observers is used.
+    /// Set to an empty list to disable all observers.
     /// </summary>
-    public int? MaxContextWindowTokens { get; set; }
+    public IReadOnlyList<ConsoleObserver>? Observers { get; set; }
 
     /// <summary>
-    /// Gets or sets the optional maximum output tokens.
-    /// Used with <see cref="MaxContextWindowTokens"/> to show input/output budget breakdown.
+    /// Gets or sets the list of command handlers to check before sending user input to the agent.
+    /// Use <see cref="BuildDefaultCommandHandlers"/> to create the default set.
+    /// When <see langword="null"/> (the default), a default set of handlers is used.
+    /// Set to an empty list to disable all command handlers.
     /// </summary>
-    public int? MaxOutputTokens { get; set; }
+    public IReadOnlyList<CommandHandler>? CommandHandlers { get; set; }
 
     /// <summary>
-    /// Gets or sets a value indicating whether the planning UX is enabled.
-    /// When <see langword="true"/> and the agent is in the mode specified by <see cref="PlanningModeName"/>,
-    /// the console uses structured output to present clarification questions and approval requests
-    /// instead of streaming free-form text.
+    /// The default mode-to-color mapping used when no custom <see cref="ModeColors"/> are provided.
     /// </summary>
-    /// <value>Defaults to <see langword="false"/>.</value>
-    public bool EnablePlanningUx { get; set; }
-
-    /// <summary>
-    /// Gets or sets the name of the agent mode that activates the planning UX.
-    /// Must be set when <see cref="EnablePlanningUx"/> is <see langword="true"/>.
-    /// </summary>
-    public string? PlanningModeName { get; set; }
-
-    /// <summary>
-    /// Gets or sets the name of the agent mode to switch to when the user approves a plan.
-    /// Must be set when <see cref="EnablePlanningUx"/> is <see langword="true"/>.
-    /// </summary>
-    public string? ExecutionModeName { get; set; }
+    public static readonly IReadOnlyDictionary<string, ConsoleColor> DefaultModeColors = new ReadOnlyDictionary<string, ConsoleColor>(
+        new Dictionary<string, ConsoleColor>(StringComparer.OrdinalIgnoreCase)
+        {
+            ["plan"] = ConsoleColor.Cyan,
+            ["execute"] = ConsoleColor.Green,
+        });
 
     /// <summary>
     /// Gets or sets a mapping of agent mode names to console colors.
     /// When a mode is not found in this dictionary, the default color (<see cref="ConsoleColor.Gray"/>) is used.
     /// </summary>
-    public Dictionary<string, ConsoleColor> ModeColors { get; set; } = new(StringComparer.OrdinalIgnoreCase)
+    public Dictionary<string, ConsoleColor> ModeColors { get; set; } = new(DefaultModeColors, StringComparer.OrdinalIgnoreCase);
+
+    /// <summary>
+    /// Creates the default set of observers without planning support.
+    /// Includes tool call display, tool approval, error display, reasoning display,
+    /// usage display, and text output.
+    /// </summary>
+    /// <param name="maxContextWindowTokens">Optional maximum context window size in tokens for usage display.</param>
+    /// <param name="maxOutputTokens">Optional maximum output tokens for usage display.</param>
+    /// <param name="toolFormatters">Optional tool call formatters. When <see langword="null"/>,
+    /// each observer uses the default formatters from <see cref="ToolCallFormatter.BuildDefaultToolFormatters"/>.</param>
+    /// <returns>A list of observers for a standard (non-planning) console session.</returns>
+    public static List<ConsoleObserver> BuildDefaultObservers(
+        int? maxContextWindowTokens = null,
+        int? maxOutputTokens = null,
+        IReadOnlyList<ToolCallFormatter>? toolFormatters = null)
     {
-        ["plan"] = ConsoleColor.Cyan,
-        ["execute"] = ConsoleColor.Green,
-    };
+        return
+        [
+            new ToolCallDisplayObserver(toolFormatters),
+            new ToolApprovalObserver(toolFormatters),
+            new ErrorDisplayObserver(),
+            new ReasoningDisplayObserver(),
+            new UsageDisplayObserver(maxContextWindowTokens, maxOutputTokens),
+            new TextOutputObserver(),
+        ];
+    }
+
+    /// <summary>
+    /// Creates the default set of observers with planning support.
+    /// Includes a <see cref="PlanningOutputObserver"/> instead of <see cref="TextOutputObserver"/>.
+    /// </summary>
+    /// <param name="agent">The agent, used to resolve <see cref="AgentModeProvider"/>.</param>
+    /// <param name="planModeName">The mode name that represents the planning mode.</param>
+    /// <param name="executionModeName">The mode name to switch to when the user approves a plan.</param>
+    /// <param name="modeColors">Optional mode-to-color mapping for display.
+    /// Defaults to <see cref="DefaultModeColors"/> when <see langword="null"/>.</param>
+    /// <param name="maxContextWindowTokens">Optional maximum context window size in tokens for usage display.</param>
+    /// <param name="maxOutputTokens">Optional maximum output tokens for usage display.</param>
+    /// <param name="toolFormatters">Optional tool call formatters. When <see langword="null"/>,
+    /// each observer uses the default formatters from <see cref="ToolCallFormatter.BuildDefaultToolFormatters"/>.</param>
+    /// <returns>A list of observers for a planning-enabled console session.</returns>
+    public static List<ConsoleObserver> BuildObserversWithPlanning(
+        AIAgent agent,
+        string planModeName,
+        string executionModeName,
+        IReadOnlyDictionary<string, ConsoleColor>? modeColors = null,
+        int? maxContextWindowTokens = null,
+        int? maxOutputTokens = null,
+        IReadOnlyList<ToolCallFormatter>? toolFormatters = null)
+    {
+        var modeProvider = agent.GetService<AgentModeProvider>()
+            ?? throw new InvalidOperationException("Planning requires an AgentModeProvider service on the agent.");
+
+        return
+        [
+            new ToolCallDisplayObserver(toolFormatters),
+            new ToolApprovalObserver(toolFormatters),
+            new ErrorDisplayObserver(),
+            new ReasoningDisplayObserver(),
+            new UsageDisplayObserver(maxContextWindowTokens, maxOutputTokens),
+            new PlanningOutputObserver(modeProvider, planModeName, executionModeName, modeColors ?? DefaultModeColors),
+        ];
+    }
+
+    /// <summary>
+    /// Creates the default set of command handlers.
+    /// Includes exit, todo, and mode command handlers.
+    /// </summary>
+    /// <param name="agent">The agent, used to resolve <see cref="TodoProvider"/> and <see cref="AgentModeProvider"/>.</param>
+    /// <param name="modeColors">Optional mode-to-color mapping for the mode command display.
+    /// Defaults to <see cref="DefaultModeColors"/> when <see langword="null"/>.</param>
+    /// <returns>A list of command handlers for a standard console session.</returns>
+    public static List<CommandHandler> BuildDefaultCommandHandlers(
+        AIAgent agent,
+        IReadOnlyDictionary<string, ConsoleColor>? modeColors = null)
+    {
+        var todoProvider = agent.GetService<TodoProvider>();
+        var modeProvider = agent.GetService<AgentModeProvider>();
+
+        return
+        [
+            new ExitCommandHandler(),
+            new TodoCommandHandler(todoProvider),
+            new ModeCommandHandler(modeProvider, modeColors ?? DefaultModeColors),
+        ];
+    }
 }

dotnet/samples/02-agents/Harness/Harness_Shared_Console/HarnessConsoleUXStateDriver.cs

@@ -0,0 +1,408 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Harness.ConsoleReactiveComponents;
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console;
+
+/// <summary>
+/// Default <see cref="IUXStateDriver"/> implementation. Owned by
+/// <see cref="HarnessAppComponent"/>; mutates the component's state via a
+/// <c>SetState</c>-style callback. Each public operation updates state and lets
+/// the component's render-skip optimization handle the actual draw.
+/// </summary>
+internal sealed class HarnessConsoleUXStateDriver : IUXStateDriver
+{
+    private readonly Func<HarnessAppComponentState> _getState;
+    private readonly Action<HarnessAppComponentState> _setState;
+    private readonly Action _requestShutdown;
+    private readonly IReadOnlyDictionary<string, ConsoleColor>? _modeColors;
+    private readonly List<string> _outputItems = [];
+    private readonly object _stateLock = new();
+
+    private OutputEntryType? _lastEntryType;
+    private bool _hasReceivedAnyText;
+    private OutputEntry? _currentStreamingEntry;
+    private int _currentStreamingEntryIndex = -1;
+    private string? _currentMode;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="HarnessConsoleUXStateDriver"/> class.
+    /// </summary>
+    /// <param name="getState">Returns the component's current state.</param>
+    /// <param name="setState">Replaces the component's state and triggers a re-render.</param>
+    /// <param name="requestShutdown">Callback invoked when a command handler requests application shutdown.</param>
+    /// <param name="modeColors">Optional mapping of mode names to console colors.</param>
+    public HarnessConsoleUXStateDriver(
+        Func<HarnessAppComponentState> getState,
+        Action<HarnessAppComponentState> setState,
+        Action requestShutdown,
+        IReadOnlyDictionary<string, ConsoleColor>? modeColors = null)
+    {
+        this._getState = getState;
+        this._setState = setState;
+        this._requestShutdown = requestShutdown;
+        this._modeColors = modeColors;
+        this._currentMode = getState().ModeText;
+    }
+
+    /// <inheritdoc/>
+    public string? CurrentMode
+    {
+        get => this._currentMode;
+        set
+        {
+            this.UpdateState(s =>
+            {
+                this._currentMode = value;
+                return s with
+                {
+                    ModeColor = ModeColors.Get(value, this._modeColors),
+                    ModeText = value,
+                };
+            });
+        }
+    }
+
+    /// <inheritdoc/>
+    public void BeginStreaming() =>
+        this.UpdateState(s => s with
+        {
+            Mode = BottomPanelMode.Streaming,
+            ShowSpinner = true,
+        });
+
+    /// <inheritdoc/>
+    public void StopSpinner() =>
+        this.UpdateState(s => s with { ShowSpinner = false });
+
+    /// <inheritdoc/>
+    public void EndStreaming() =>
+        this.UpdateState(s => s with
+        {
+            Mode = BottomPanelMode.TextInput,
+            ShowSpinner = false,
+        });
+
+    /// <inheritdoc/>
+    public void BeginStreamingOutput()
+    {
+        lock (this._stateLock)
+        {
+            this._hasReceivedAnyText = false;
+            this._currentStreamingEntry = null;
+            this._currentStreamingEntryIndex = -1;
+        }
+    }
+
+    /// <inheritdoc/>
+    public void SetUsageText(string usageText) =>
+        this.UpdateState(s => s with { UsageText = usageText });
+
+    /// <inheritdoc/>
+    public void SetQueuedMessages(IReadOnlyList<ChatMessage> pending)
+    {
+        var newQueued = new List<string>(pending.Count);
+        foreach (var msg in pending)
+        {
+            string text = msg.Text ?? string.Empty;
+            newQueued.Add(RenderEntry($"  💬 {text}\n", ConsoleColor.DarkGray));
+        }
+
+        this.UpdateState(s => s with { QueuedItems = newQueued });
+    }
+
+    /// <inheritdoc/>
+    public void QueueFollowUpQuestions(IReadOnlyList<FollowUpQuestion> questions)
+    {
+        if (questions.Count == 0)
+        {
+            return;
+        }
+
+        this.UpdateState(s =>
+        {
+            bool wasEmpty = s.PendingQuestions.Count == 0;
+
+            var combined = new List<FollowUpQuestion>(s.PendingQuestions.Count + questions.Count);
+            combined.AddRange(s.PendingQuestions);
+            combined.AddRange(questions);
+
+            HarnessAppComponentState next = s with { PendingQuestions = combined };
+
+            if (wasEmpty)
+            {
+                next = this.ConfigureForHeadQuestion(next, combined[0]);
+            }
+
+            return next;
+        });
+    }
+
+    /// <inheritdoc/>
+    public void AddFollowUpResponse(ChatMessage response)
+    {
+        this.UpdateState(s =>
+        {
+            var combined = new List<ChatMessage>(s.AccumulatedFollowUpResponses.Count + 1);
+            combined.AddRange(s.AccumulatedFollowUpResponses);
+            combined.Add(response);
+            return s with { AccumulatedFollowUpResponses = combined };
+        });
+    }
+
+    /// <inheritdoc/>
+    public void AdvanceFollowUpQuestion()
+    {
+        this.UpdateState(s =>
+        {
+            if (s.PendingQuestions.Count == 0)
+            {
+                return s;
+            }
+
+            var remaining = s.PendingQuestions.Skip(1).ToList();
+            HarnessAppComponentState next = s with { PendingQuestions = remaining };
+
+            if (remaining.Count > 0)
+            {
+                return this.ConfigureForHeadQuestion(next, remaining[0]);
+            }
+
+            return next with
+            {
+                Mode = BottomPanelMode.TextInput,
+                ListSelectionOptions = [],
+                ListSelectionTitle = null,
+                ListSelectionCustomTextPlaceholder = null,
+                ListSelectionIndex = 0,
+                ListSelectionCustomInputText = "",
+            };
+        });
+    }
+
+    /// <inheritdoc/>
+    public IReadOnlyList<ChatMessage> TakeFollowUpResponses()
+    {
+        return this.UpdateState(s =>
+        {
+            IReadOnlyList<ChatMessage> responses = s.AccumulatedFollowUpResponses;
+            if (responses.Count == 0)
+            {
+                return (s, responses);
+            }
+
+            return (s with { AccumulatedFollowUpResponses = [] }, responses);
+        });
+    }
+
+    /// <summary>
+    /// Configures the bottom-panel display fields on the supplied state for the
+    /// given head question. For text questions, also writes the prompt as an
+    /// info line above the input row as a side effect.
+    /// </summary>
+    private HarnessAppComponentState ConfigureForHeadQuestion(HarnessAppComponentState state, FollowUpQuestion question)
+    {
+        if (question is ChoiceFollowUpQuestion choice)
+        {
+            return state with
+            {
+                Mode = BottomPanelMode.ListSelection,
+                ListSelectionOptions = choice.Choices.ToList(),
+                ListSelectionTitle = choice.Prompt,
+                ListSelectionCustomTextPlaceholder = choice.AllowCustomText ? "✏️  Type a custom response..." : null,
+                ListSelectionIndex = 0,
+                ListSelectionCustomInputText = "",
+            };
+        }
+
+        // Text question — prompt is rendered as an info line above the input row.
+        // We append entries and capture the scroll snapshot inline so the caller's
+        // single _setState picks up both the new output and the UI mode change.
+        ConsoleColor ruleColor = ModeColors.Get(this._currentMode, this._modeColors);
+        List<string> scrollSnapshot = this.AppendOutputEntriesAndSnapshot(
+            new OutputEntry(OutputEntryType.InfoLine, "\n", ruleColor),
+            new OutputEntry(OutputEntryType.InfoLine, $"  {question.Prompt}", ruleColor));
+
+        return state with
+        {
+            Mode = BottomPanelMode.TextInput,
+            ListSelectionOptions = [],
+            ListSelectionTitle = null,
+            ListSelectionCustomTextPlaceholder = null,
+            ListSelectionIndex = 0,
+            ListSelectionCustomInputText = "",
+            ScrollAreaContentItems = scrollSnapshot,
+        };
+    }
+
+    /// <inheritdoc/>
+    public void WriteUserInputEcho(string text)
+    {
+        this.UpdateState(s =>
+        {
+            List<string> snapshot = this.AppendOutputEntriesAndSnapshot(new OutputEntry(
+                OutputEntryType.UserInput,
+                $"\nYou: {text}\n\n",
+                ConsoleColor.Green));
+            return s with { ScrollAreaContentItems = snapshot };
+        });
+    }
+
+    /// <inheritdoc/>
+    public Task WriteInfoAsync(string text, ConsoleColor? color = null) =>
+        this.WriteInfoCoreAsync(text, color, newLine: false);
+
+    /// <inheritdoc/>
+    public Task WriteInfoLineAsync(string text, ConsoleColor? color = null) =>
+        this.WriteInfoCoreAsync(text, color, newLine: true);
+
+    private Task WriteInfoCoreAsync(string text, ConsoleColor? color, bool newLine)
+    {
+        this.UpdateState(s =>
+        {
+            // Add a blank line separator when transitioning from streaming text or user input.
+            string prefix = this._lastEntryType is OutputEntryType.StreamingText or OutputEntryType.StreamFooter
+                ? "\n  "
+                : "  ";
+
+            string fullText = newLine ? prefix + text + "\n\n" : prefix + text;
+            List<string> snapshot = this.AppendOutputEntriesAndSnapshot(new OutputEntry(
+                OutputEntryType.InfoLine,
+                fullText,
+                color ?? ModeColors.Get(this._currentMode, this._modeColors)));
+            return s with { ScrollAreaContentItems = snapshot };
+        });
+        return Task.CompletedTask;
+    }
+
+    /// <inheritdoc/>
+    public Task WriteTextAsync(string text, ConsoleColor? color = null)
+    {
+        this.UpdateState(s =>
+        {
+            this._lastEntryType = OutputEntryType.StreamingText;
+            this._hasReceivedAnyText = true;
+
+            ConsoleColor effectiveColor = color ?? ModeColors.Get(this._currentMode, this._modeColors);
+
+            if (this._currentStreamingEntry is not null
+                && this._currentStreamingEntryIndex == this._outputItems.Count - 1)
+            {
+                // The streaming entry is still the last item — safe to replace in place.
+                this._currentStreamingEntry = this._currentStreamingEntry with
+                {
+                    Text = this._currentStreamingEntry.Text + text,
+                };
+                this._outputItems[^1] = RenderEntry(this._currentStreamingEntry.Text, this._currentStreamingEntry.Color);
+            }
+            else
+            {
+                // Either the first text delta or other entries (tool calls, info lines)
+                // were appended after the previous streaming entry — start a fresh one.
+                const string Prefix = "\n";
+                this._currentStreamingEntry = new OutputEntry(OutputEntryType.StreamingText, Prefix + text, effectiveColor);
+                this._outputItems.Add(RenderEntry(this._currentStreamingEntry.Text, this._currentStreamingEntry.Color));
+                this._currentStreamingEntryIndex = this._outputItems.Count - 1;
+            }
+
+            return s with { ScrollAreaContentItems = new List<string>(this._outputItems) };
+        });
+
+        return Task.CompletedTask;
+    }
+
+    /// <inheritdoc/>
+    public Task EndStreamingOutputAsync()
+    {
+        this.UpdateState(s =>
+        {
+            if (this._hasReceivedAnyText)
+            {
+                this._outputItems.Add(RenderEntry("\n", null));
+                this._currentStreamingEntry = null;
+                this._lastEntryType = OutputEntryType.StreamFooter;
+                return s with { ScrollAreaContentItems = new List<string>(this._outputItems) };
+            }
+
+            return s;
+        });
+
+        return Task.CompletedTask;
+    }
+
+    /// <inheritdoc/>
+    public Task WriteNoTextWarningAsync(bool hasFollowUpActions)
+    {
+        if (!this._hasReceivedAnyText && !hasFollowUpActions)
+        {
+            this.UpdateState(s =>
+            {
+                List<string> snapshot = this.AppendOutputEntriesAndSnapshot(new OutputEntry(
+                    OutputEntryType.StreamFooter,
+                    "  (no text response from agent)\n",
+                    ConsoleColor.DarkYellow));
+                return s with { ScrollAreaContentItems = snapshot };
+            });
+        }
+
+        return Task.CompletedTask;
+    }
+
+    /// <summary>
+    /// Wraps the supplied text with ANSI foreground color escape sequences (or returns
+    /// the text unchanged when no color is specified). Output is appended to
+    /// <see cref="_outputItems"/> and consumed verbatim by <see cref="TextScrollPanel"/>
+    /// and <see cref="TextPanel"/>.
+    /// </summary>
+    private static string RenderEntry(string text, ConsoleColor? color) =>
+        color.HasValue
+            ? $"{AnsiEscapes.SetForegroundColor(color.Value)}{text}{AnsiEscapes.ResetAttributes}"
+            : text;
+
+    private void UpdateState(Func<HarnessAppComponentState, HarnessAppComponentState> update)
+    {
+        lock (this._stateLock)
+        {
+            this._setState(update(this._getState()));
+        }
+    }
+
+    private T UpdateState<T>(Func<HarnessAppComponentState, (HarnessAppComponentState State, T Result)> update)
+    {
+        lock (this._stateLock)
+        {
+            var (newState, result) = update(this._getState());
+            this._setState(newState);
+            return result;
+        }
+    }
+
+    /// <summary>
+    /// Appends one or more output entries to the output list, updates
+    /// <see cref="_lastEntryType"/> to the last entry's type, and returns a
+    /// snapshot of <see cref="_outputItems"/>. Must be called inside a locked
+    /// context (e.g. within an <see cref="UpdateState"/> callback).
+    /// </summary>
+    private List<string> AppendOutputEntriesAndSnapshot(params OutputEntry[] entries)
+    {
+        this.AppendOutputEntriesCore(entries);
+        return new List<string>(this._outputItems);
+    }
+
+    private void AppendOutputEntriesCore(OutputEntry[] entries)
+    {
+        foreach (OutputEntry entry in entries)
+        {
+            this._outputItems.Add(RenderEntry(entry.Text, entry.Color));
+        }
+
+        if (entries.Length > 0)
+        {
+            this._lastEntryType = entries[^1].Type;
+        }
+    }
+
+    /// <inheritdoc/>
+    public void RequestShutdown() => this._requestShutdown();
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/HarnessUXContainer.cs

@@ -1,478 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using Harness.ConsoleReactiveComponents;
-using Microsoft.Extensions.AI;
-
-namespace Harness.Shared.Console;
-
-/// <summary>
-/// Event arguments raised when the user submits text while the bottom panel is in
-/// streaming mode (i.e. an agent turn is in progress).
-/// </summary>
-public sealed class StreamingInputReceivedEventArgs : EventArgs
-{
-    /// <summary>
-    /// Initializes a new instance of the <see cref="StreamingInputReceivedEventArgs"/> class.
-    /// </summary>
-    /// <param name="text">The submitted text.</param>
-    public StreamingInputReceivedEventArgs(string text)
-    {
-        this.Text = text;
-    }
-
-    /// <summary>
-    /// Gets the submitted text.
-    /// </summary>
-    public string Text { get; }
-}
-
-/// <summary>
-/// Façade over the harness UI: owns the <see cref="HarnessAppComponent"/>, manages
-/// its props, dispatches input submissions, and provides the high-level read/write
-/// operations used by observers, command handlers, and the harness loop.
-/// </summary>
-/// <remarks>
-/// All callers interact with the UI exclusively through this class. The underlying
-/// <see cref="HarnessAppComponent"/> and its props are an implementation detail and
-/// must not be exposed.
-/// </remarks>
-public sealed class HarnessUXContainer : IDisposable
-{
-    /// <summary>
-    /// The prompt displayed in the bottom-panel input area.
-    /// </summary>
-    private const string UserPrompt = "> ";
-
-    private readonly IReadOnlyDictionary<string, ConsoleColor>? _modeColors;
-    private readonly List<object> _outputItems = [];
-    private readonly HarnessAppComponent _appComponent;
-    private readonly object _outputLock = new();
-
-    private TaskCompletionSource<string>? _pendingInputTcs;
-    private OutputEntryType? _lastEntryType;
-    private bool _hasReceivedAnyText;
-    private OutputEntry? _currentStreamingEntry;
-    private string? _currentMode;
-
-    /// <summary>
-    /// Initializes a new instance of the <see cref="HarnessUXContainer"/> class.
-    /// </summary>
-    /// <param name="placeholder">Placeholder text shown when the input is empty.</param>
-    /// <param name="initialMode">The current agent mode, used to colour the rule and prompt.</param>
-    /// <param name="inputEnabled">Whether the bottom-panel input accepts keystrokes during streaming.</param>
-    /// <param name="modeColors">Optional mapping of mode names to console colors.</param>
-    public HarnessUXContainer(
-        string placeholder,
-        string? initialMode,
-        bool inputEnabled,
-        IReadOnlyDictionary<string, ConsoleColor>? modeColors = null)
-    {
-        this._modeColors = modeColors;
-        this._currentMode = initialMode;
-
-        this._appComponent = new HarnessAppComponent(RenderOutputEntry)
-        {
-            Props = new HarnessAppComponentProps
-            {
-                ScrollItems = this._outputItems,
-                Mode = BottomPanelMode.TextInput,
-                Prompt = UserPrompt,
-                Placeholder = placeholder,
-                ModeColor = ModeColors.Get(initialMode, modeColors),
-                ModeText = initialMode,
-                InputEnabled = inputEnabled,
-            },
-        };
-
-        this._appComponent.InputSubmitted += this.OnInputSubmitted;
-    }
-
-    /// <summary>
-    /// Raised when the user submits text while the bottom panel is in streaming mode.
-    /// Subscribers typically enqueue the text into a message-injecting chat client.
-    /// </summary>
-    public event EventHandler<StreamingInputReceivedEventArgs>? StreamingInputReceived;
-
-    /// <summary>
-    /// Gets or sets the current agent mode (e.g. "plan", "execute"). Updating this
-    /// also refreshes the rule colour and bottom-panel prompt to match the new mode.
-    /// </summary>
-    public string? CurrentMode
-    {
-        get => this._currentMode;
-        set
-        {
-            this._currentMode = value;
-            this._appComponent.Props = this._appComponent.Props! with
-            {
-                ModeColor = ModeColors.Get(value, this._modeColors),
-                ModeText = value,
-            };
-            this._appComponent.Render();
-        }
-    }
-
-    /// <summary>
-    /// Performs the initial screen clear, sets the help text in the mode-and-help bar,
-    /// and adds the title to the output area.
-    /// </summary>
-    /// <param name="title">The title displayed in the console header.</param>
-    /// <param name="commandHelpTexts">The command help strings displayed in the mode-and-help bar.</param>
-    /// <param name="messageInjectionActive">Whether streaming-time message injection is enabled.</param>
-    public void Initialize(string title, IEnumerable<string> commandHelpTexts, bool messageInjectionActive)
-    {
-        // Set the help text on the mode-and-help bar (persists below the rule).
-        this._appComponent.Props = this._appComponent.Props! with
-        {
-            HelpText = string.Join(", ", commandHelpTexts),
-            ModeText = this._currentMode,
-        };
-
-        System.Console.Write(AnsiEscapes.EraseEntireScreen);
-        System.Console.Write(AnsiEscapes.EraseScrollbackBuffer);
-        this._appComponent.Render();
-
-        this.AppendOutputEntries(
-            new OutputEntry(OutputEntryType.InfoLine, $"=== {title} ===\n", ConsoleColor.White),
-            new OutputEntry(OutputEntryType.InfoLine, "\n"));
-    }
-
-    /// <summary>
-    /// Restores the cursor and exits the alternate screen, ending the interactive UI.
-    /// </summary>
-    public void Deactivate() => this._appComponent.Deactivate();
-
-    /// <summary>
-    /// Switches the bottom panel to streaming mode and starts the spinner.
-    /// </summary>
-    public void BeginStreaming()
-    {
-        this._appComponent.Props = this._appComponent.Props! with
-        {
-            Mode = BottomPanelMode.Streaming,
-            ShowSpinner = true,
-        };
-        this._appComponent.Render();
-    }
-
-    /// <summary>
-    /// Stops the spinner without leaving streaming mode. Use between the end of the
-    /// stream and any observer-driven prompts (e.g. tool approvals).
-    /// </summary>
-    public void StopSpinner()
-    {
-        this._appComponent.Props = this._appComponent.Props! with { ShowSpinner = false };
-        this._appComponent.Render();
-    }
-
-    /// <summary>
-    /// Switches the bottom panel back to text-input mode and stops the spinner.
-    /// </summary>
-    public void EndStreaming()
-    {
-        this._appComponent.Props = this._appComponent.Props! with
-        {
-            Mode = BottomPanelMode.TextInput,
-            ShowSpinner = false,
-        };
-        this._appComponent.Render();
-    }
-
-    /// <summary>
-    /// Resets per-turn streaming bookkeeping in preparation for a new agent turn.
-    /// </summary>
-    public void BeginStreamingOutput()
-    {
-        this._hasReceivedAnyText = false;
-        this._currentStreamingEntry = null;
-    }
-
-    /// <summary>
-    /// Sets the formatted usage text shown on the agent status bar.
-    /// </summary>
-    public void SetUsageText(string usageText)
-    {
-        this._appComponent.Props = this._appComponent.Props! with { UsageText = usageText };
-        this._appComponent.Render();
-    }
-
-    /// <summary>
-    /// Clears the usage text from the agent status bar.
-    /// </summary>
-    public void ClearUsageText()
-    {
-        this._appComponent.Props = this._appComponent.Props! with { UsageText = null };
-        this._appComponent.Render();
-    }
-
-    /// <summary>
-    /// Replaces the queued-message display with one entry per pending message.
-    /// </summary>
-    public void ShowQueuedMessages(IReadOnlyList<ChatMessage> pending)
-    {
-        var newQueued = new List<object>(pending.Count);
-        foreach (var msg in pending)
-        {
-            string text = msg.Text ?? string.Empty;
-            newQueued.Add(new OutputEntry(OutputEntryType.UserInput, $"  💬 {text}\n", ConsoleColor.DarkGray));
-        }
-
-        this._appComponent.Props = this._appComponent.Props! with { QueuedItems = newQueued };
-        this._appComponent.Render();
-    }
-
-    /// <summary>
-    /// Echoes a submitted user input as a regular user-input entry in the output area,
-    /// using the current mode-aware prompt prefix.
-    /// </summary>
-    /// <param name="text">The user-entered text.</param>
-    public void WriteUserInputEcho(string text)
-    {
-        this.AppendOutputEntries(new OutputEntry(
-            OutputEntryType.UserInput,
-            $"\nYou: {text}\n",
-            ConsoleColor.Green));
-    }
-
-    /// <summary>
-    /// Writes informational output as an output entry, without a trailing newline.
-    /// </summary>
-    public Task WriteInfoAsync(string text, ConsoleColor? color = null) =>
-        this.WriteInfoCoreAsync(text, color, newLine: false);
-
-    /// <summary>
-    /// Writes informational output as an output entry, followed by a newline.
-    /// </summary>
-    public Task WriteInfoLineAsync(string text, ConsoleColor? color = null) =>
-        this.WriteInfoCoreAsync(text, color, newLine: true);
-
-    private Task WriteInfoCoreAsync(string text, ConsoleColor? color, bool newLine)
-    {
-        // Add a blank line separator when transitioning from streaming text or user input.
-        string prefix = this._lastEntryType is OutputEntryType.StreamingText or OutputEntryType.StreamFooter
-            ? "\n\n  "
-            : "  ";
-
-        string fullText = newLine ? prefix + text + "\n" : prefix + text;
-        this.AppendOutputEntries(new OutputEntry(
-            OutputEntryType.InfoLine,
-            fullText,
-            color ?? ModeColors.Get(this.CurrentMode, this._modeColors)));
-        return Task.CompletedTask;
-    }
-
-    /// <summary>
-    /// Writes streaming text output from the agent. Successive calls accumulate into a
-    /// single streaming entry that is re-rendered by the text panel.
-    /// </summary>
-    public Task WriteTextAsync(string text, ConsoleColor? color = null)
-    {
-        lock (this._outputLock)
-        {
-            this._lastEntryType = OutputEntryType.StreamingText;
-            this._hasReceivedAnyText = true;
-
-            ConsoleColor effectiveColor = color ?? ModeColors.Get(this.CurrentMode, this._modeColors);
-
-            if (this._currentStreamingEntry is not null)
-            {
-                this._currentStreamingEntry = this._currentStreamingEntry with
-                {
-                    Text = this._currentStreamingEntry.Text + text,
-                };
-                this._outputItems[^1] = this._currentStreamingEntry;
-            }
-            else
-            {
-                const string Prefix = "\n";
-                this._currentStreamingEntry = new OutputEntry(OutputEntryType.StreamingText, Prefix + text, effectiveColor);
-                this._outputItems.Add(this._currentStreamingEntry);
-            }
-
-            this._appComponent.Props = this._appComponent.Props! with
-            {
-                ScrollItems = new List<object>(this._outputItems),
-            };
-        }
-
-        this._appComponent.Render();
-        return Task.CompletedTask;
-    }
-
-    /// <summary>
-    /// Writes a blank-line separator to visually close the streaming output section.
-    /// Call before observer completions so their output is visually separated.
-    /// </summary>
-    public Task EndStreamingOutputAsync()
-    {
-        lock (this._outputLock)
-        {
-            this._outputItems.Add(new OutputEntry(OutputEntryType.StreamFooter, "\n"));
-            this._currentStreamingEntry = null;
-            this._lastEntryType = OutputEntryType.StreamFooter;
-            this._appComponent.Props = this._appComponent.Props! with
-            {
-                ScrollItems = new List<object>(this._outputItems),
-            };
-        }
-
-        this._appComponent.Render();
-        return Task.CompletedTask;
-    }
-
-    /// <summary>
-    /// Shows a "(no text response from agent)" warning if no text was received
-    /// and no observer produced follow-up messages. Call after observer completions.
-    /// </summary>
-    /// <param name="hasFollowUpMessages">Whether any observer produced follow-up messages.</param>
-    public Task WriteNoTextWarningAsync(bool hasFollowUpMessages)
-    {
-        if (!this._hasReceivedAnyText && !hasFollowUpMessages)
-        {
-            this.AppendOutputEntries(new OutputEntry(
-                OutputEntryType.StreamFooter,
-                "  (no text response from agent)\n",
-                ConsoleColor.DarkYellow));
-        }
-
-        return Task.CompletedTask;
-    }
-
-    /// <summary>
-    /// Reads a line of input from the user. If <paramref name="prompt"/> is supplied
-    /// it is rendered as an info line above the input row before reading.
-    /// </summary>
-    public async Task<string?> ReadLineAsync(string? prompt = null, ConsoleColor? promptColor = null)
-    {
-        if (prompt is not null)
-        {
-            ConsoleColor ruleColor = ModeColors.Get(this.CurrentMode, this._modeColors);
-            this.AppendOutputEntries(
-                new OutputEntry(OutputEntryType.InfoLine, "\n", ruleColor),
-                new OutputEntry(OutputEntryType.InfoLine, $"  {prompt}", promptColor ?? ruleColor));
-        }
-
-        this._appComponent.Props = this._appComponent.Props! with { Mode = BottomPanelMode.TextInput };
-        this._appComponent.Render();
-
-        string input = await this.WaitForInputAsync();
-
-        this.AppendOutputEntries(new OutputEntry(
-            OutputEntryType.UserInput,
-            $"\nYou: {input}\n",
-            ConsoleColor.Green));
-
-        return input;
-    }
-
-    /// <summary>
-    /// Presents a selection prompt with the given choices and waits for the user's
-    /// selection. The title is displayed above the list in the bottom panel. After
-    /// selection the bottom panel is restored to text-input mode and both the question
-    /// and selection are echoed in the output area.
-    /// </summary>
-    public async Task<string> ReadSelectionAsync(string title, IList<string> choices)
-    {
-        this._appComponent.Props = this._appComponent.Props! with
-        {
-            Mode = BottomPanelMode.ListSelection,
-            Items = choices.ToList(),
-            ListTitle = title,
-            ListCustomTextPlaceholder = "✏️  Type a custom response...",
-        };
-        this._appComponent.Render();
-
-        string selection = await this.WaitForInputAsync();
-
-        this._appComponent.Props = this._appComponent.Props with { Mode = BottomPanelMode.TextInput };
-
-        this.AppendOutputEntries(
-            new OutputEntry(
-                OutputEntryType.InfoLine,
-                $"\n  {title}\n",
-                ModeColors.Get(this.CurrentMode, this._modeColors)),
-            new OutputEntry(
-                OutputEntryType.UserInput,
-                $"\nYou: {selection}\n",
-                ConsoleColor.Green));
-
-        return selection;
-    }
-
-    /// <summary>
-    /// Awaits the next non-streaming user input submission.
-    /// </summary>
-    public Task<string> WaitForInputAsync()
-    {
-        this._pendingInputTcs = new TaskCompletionSource<string>(TaskCreationOptions.RunContinuationsAsynchronously);
-        return this._pendingInputTcs.Task;
-    }
-
-    private void OnInputSubmitted(object? sender, InputSubmittedEventArgs e)
-    {
-        if (e.Mode == BottomPanelMode.Streaming)
-        {
-            this.StreamingInputReceived?.Invoke(this, new StreamingInputReceivedEventArgs(e.Text));
-        }
-        else
-        {
-            var waiter = this._pendingInputTcs;
-            this._pendingInputTcs = null;
-            waiter?.TrySetResult(e.Text);
-        }
-    }
-
-    /// <inheritdoc/>
-    public void Dispose()
-    {
-        this._appComponent.InputSubmitted -= this.OnInputSubmitted;
-        this._appComponent.Deactivate();
-        this._appComponent.Dispose();
-    }
-
-    /// <summary>
-    /// Renders an <see cref="OutputEntry"/> to a string with ANSI color codes.
-    /// Used as the render delegate for the <see cref="HarnessAppComponent"/>.
-    /// </summary>
-    private static string RenderOutputEntry(object item)
-    {
-        if (item is not OutputEntry entry)
-        {
-            return item?.ToString() ?? string.Empty;
-        }
-
-        if (entry.Color.HasValue)
-        {
-            return $"{AnsiEscapes.SetForegroundColor(entry.Color.Value)}{entry.Text}{AnsiEscapes.ResetAttributes}";
-        }
-
-        return entry.Text;
-    }
-
-    /// <summary>
-    /// Appends one or more output entries to the output list under lock,
-    /// updates <see cref="_lastEntryType"/> to the last entry's type, and renders.
-    /// </summary>
-    private void AppendOutputEntries(params OutputEntry[] entries)
-    {
-        lock (this._outputLock)
-        {
-            foreach (OutputEntry entry in entries)
-            {
-                this._outputItems.Add(entry);
-            }
-
-            if (entries.Length > 0)
-            {
-                this._lastEntryType = entries[^1].Type;
-            }
-
-            this._appComponent.Props = this._appComponent.Props! with
-            {
-                ScrollItems = new List<object>(this._outputItems),
-            };
-        }
-
-        this._appComponent.Render();
-    }
-}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/IUXStateDriver.cs

@@ -0,0 +1,120 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console;
+
+/// <summary>
+/// Abstraction over the harness UI state. All callers (observers, command handlers,
+/// the agent runner) interact with the UI exclusively through this interface, which
+/// internally translates each operation into a <c>SetState</c> call on the underlying
+/// reactive component.
+/// </summary>
+/// <remarks>
+/// This interface is intentionally narrow: it does not expose blocking input methods.
+/// The agent runner orchestrates input flow via <see cref="FollowUpQuestion"/>
+/// objects returned from observers.
+/// </remarks>
+public interface IUXStateDriver
+{
+    /// <summary>
+    /// Gets or sets the current agent mode (e.g. "plan", "execute"). Setting also
+    /// refreshes the rule colour and bottom-panel prompt to match the new mode.
+    /// </summary>
+    string? CurrentMode { get; set; }
+
+    /// <summary>
+    /// Echoes a submitted user input as a regular user-input entry in the output area.
+    /// </summary>
+    void WriteUserInputEcho(string text);
+
+    /// <summary>
+    /// Writes informational output as an output entry, without a trailing newline.
+    /// </summary>
+    Task WriteInfoAsync(string text, ConsoleColor? color = null);
+
+    /// <summary>
+    /// Writes informational output as an output entry, followed by a newline.
+    /// </summary>
+    Task WriteInfoLineAsync(string text, ConsoleColor? color = null);
+
+    /// <summary>
+    /// Writes streaming text output from the agent. Successive calls accumulate into a
+    /// single streaming entry that is re-rendered by the text panel.
+    /// </summary>
+    Task WriteTextAsync(string text, ConsoleColor? color = null);
+
+    /// <summary>
+    /// Writes a blank-line separator to visually close the streaming output section.
+    /// </summary>
+    Task EndStreamingOutputAsync();
+
+    /// <summary>
+    /// Shows a "(no text response from agent)" warning if no text was received
+    /// and no observer produced follow-up actions.
+    /// </summary>
+    Task WriteNoTextWarningAsync(bool hasFollowUpActions);
+
+    /// <summary>
+    /// Switches the bottom panel to streaming mode and starts the spinner.
+    /// </summary>
+    void BeginStreaming();
+
+    /// <summary>
+    /// Stops the spinner without leaving streaming mode.
+    /// </summary>
+    void StopSpinner();
+
+    /// <summary>
+    /// Switches the bottom panel back to text-input mode and stops the spinner.
+    /// </summary>
+    void EndStreaming();
+
+    /// <summary>
+    /// Resets per-turn streaming bookkeeping in preparation for a new agent turn.
+    /// </summary>
+    void BeginStreamingOutput();
+
+    /// <summary>
+    /// Sets the formatted usage text shown on the agent status bar.
+    /// </summary>
+    void SetUsageText(string usageText);
+
+    /// <summary>
+    /// Replaces the queued-message display with one entry per pending message.
+    /// </summary>
+    void SetQueuedMessages(IReadOnlyList<ChatMessage> pending);
+
+    /// <summary>
+    /// Appends the supplied questions to the pending follow-up question queue in
+    /// component state. If the queue was empty, the bottom-panel display is
+    /// reconfigured to present the new head question.
+    /// </summary>
+    void QueueFollowUpQuestions(IReadOnlyList<FollowUpQuestion> questions);
+
+    /// <summary>
+    /// Appends a message to the accumulated follow-up response list in component state.
+    /// Called by the runner for direct <see cref="FollowUpMessage"/> outputs and by
+    /// the component when a question's continuation produces a response.
+    /// </summary>
+    void AddFollowUpResponse(ChatMessage response);
+
+    /// <summary>
+    /// Pops the head of the pending follow-up question queue. Reconfigures the
+    /// bottom-panel display for the new head, or restores the default text-input
+    /// mode if the queue is now empty.
+    /// </summary>
+    void AdvanceFollowUpQuestion();
+
+    /// <summary>
+    /// Returns the current accumulated follow-up responses and clears them in state.
+    /// Called by the runner immediately before invoking the next agent turn.
+    /// </summary>
+    IReadOnlyList<ChatMessage> TakeFollowUpResponses();
+
+    /// <summary>
+    /// Signals that the application should shut down. Completes the shutdown task
+    /// on the owning component.
+    /// </summary>
+    void RequestShutdown();
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/ConsoleObserver.cs

@@ -18,36 +18,41 @@ public abstract class ConsoleObserver
     /// Override to set options such as <see cref="AgentRunOptions.ResponseFormat"/>.
     /// </summary>
     /// <param name="options">The run options to configure.</param>
-    public virtual void ConfigureRunOptions(AgentRunOptions options)
+    /// <param name="agent">The agent being interacted with.</param>
+    /// <param name="session">The current agent session.</param>
+    public virtual void ConfigureRunOptions(AgentRunOptions options, AIAgent agent, AgentSession session)
     {
     }
 
     /// <summary>
     /// Called for each <see cref="AIContent"/> item in the response stream.
     /// </summary>
-    /// <param name="ux">The harness UX container, used for rendering output and interacting with the user.</param>
+    /// <param name="ux">The UX state driver, used for rendering output.</param>
     /// <param name="content">The content item from the stream.</param>
-    public virtual Task OnContentAsync(HarnessUXContainer ux, AIContent content) => Task.CompletedTask;
+    /// <param name="agent">The agent being interacted with.</param>
+    /// <param name="session">The current agent session.</param>
+    public virtual Task OnContentAsync(IUXStateDriver ux, AIContent content, AIAgent agent, AgentSession session) => Task.CompletedTask;
 
     /// <summary>
     /// Called for each text update in the response stream.
     /// </summary>
-    /// <param name="ux">The harness UX container, used for rendering output and interacting with the user.</param>
+    /// <param name="ux">The UX state driver, used for rendering output.</param>
     /// <param name="text">The text from the update.</param>
-    public virtual Task OnTextAsync(HarnessUXContainer ux, string text) => Task.CompletedTask;
-
-    /// <summary>
-    /// Called after the response stream completes. Returns messages to include in the
-    /// next agent invocation, or <see langword="null"/> if no re-invocation is needed.
-    /// </summary>
-    /// <param name="ux">The harness UX container, used for rendering output and interacting with the user.</param>
     /// <param name="agent">The agent being interacted with.</param>
     /// <param name="session">The current agent session.</param>
-    /// <param name="options">The console options.</param>
-    /// <returns>Messages to send to the agent, or <see langword="null"/> if no action is needed.</returns>
-    public virtual Task<IList<ChatMessage>?> OnStreamCompleteAsync(
-        HarnessUXContainer ux,
+    public virtual Task OnTextAsync(IUXStateDriver ux, string text, AIAgent agent, AgentSession session) => Task.CompletedTask;
+
+    /// <summary>
+    /// Called after the response stream completes. Returns a heterogeneous list of
+    /// follow-up actions (questions to ask the user, and/or messages to add directly to
+    /// the next agent invocation), or <see langword="null"/> if no follow-up is needed.
+    /// </summary>
+    /// <param name="ux">The UX state driver, used for rendering output.</param>
+    /// <param name="agent">The agent being interacted with.</param>
+    /// <param name="session">The current agent session.</param>
+    /// <returns>Follow-up actions to process after the stream completes, or <see langword="null"/>.</returns>
+    public virtual Task<IList<FollowUpAction>?> OnStreamCompleteAsync(
+        IUXStateDriver ux,
         AIAgent agent,
-        AgentSession session,
-        HarnessConsoleOptions options) => Task.FromResult<IList<ChatMessage>?>(null);
+        AgentSession session) => Task.FromResult<IList<FollowUpAction>?>(null);
 }

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/ErrorDisplayObserver.cs

@@ -1,5 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 
 namespace Harness.Shared.Console.Observers;
@@ -7,10 +8,10 @@ namespace Harness.Shared.Console.Observers;
 /// <summary>
 /// Displays error content (❌) from the response stream.
 /// </summary>
-internal sealed class ErrorDisplayObserver : ConsoleObserver
+public sealed class ErrorDisplayObserver : ConsoleObserver
 {
     /// <inheritdoc/>
-    public override async Task OnContentAsync(HarnessUXContainer ux, AIContent content)
+    public override async Task OnContentAsync(IUXStateDriver ux, AIContent content, AIAgent agent, AgentSession session)
     {
         if (content is ErrorContent errorContent)
         {

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/PlanningOutputObserver.cs

@@ -2,51 +2,77 @@
 
 using System.Text;
 using System.Text.Json;
+using Harness.ConsoleReactiveComponents;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 
 namespace Harness.Shared.Console.Observers;
 
 /// <summary>
-/// Planning observer that configures structured output, collects streamed text,
-/// and deserializes it as a <see cref="PlanningResponse"/>. Renders clarification
-/// questions and approval prompts, and manages mode switching when the user approves a plan.
+/// Planning observer that is mode-aware: in planning mode it configures structured
+/// JSON output, collects streamed text, and deserializes it as a <see cref="PlanningResponse"/>;
+/// in execution mode it passes text straight through to <see cref="IUXStateDriver.WriteTextAsync"/>
+/// for live streaming display.
 /// </summary>
-internal sealed class PlanningOutputObserver : ConsoleObserver
+public sealed class PlanningOutputObserver : ConsoleObserver
 {
     private readonly StringBuilder _textCollector = new();
     private readonly AgentModeProvider _modeProvider;
+    private readonly string _planModeName;
+    private readonly string _executionModeName;
+    private readonly IReadOnlyDictionary<string, ConsoleColor>? _modeColors;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="PlanningOutputObserver"/> class.
     /// </summary>
     /// <param name="modeProvider">The mode provider for switching modes on approval.</param>
-    public PlanningOutputObserver(AgentModeProvider modeProvider)
+    /// <param name="planModeName">The mode name that represents the planning mode.</param>
+    /// <param name="executionModeName">The mode name to switch to when the user approves a plan.</param>
+    /// <param name="modeColors">Optional mode-to-color mapping for display.</param>
+    public PlanningOutputObserver(AgentModeProvider modeProvider, string planModeName, string executionModeName, IReadOnlyDictionary<string, ConsoleColor>? modeColors = null)
     {
         this._modeProvider = modeProvider;
+        this._planModeName = planModeName;
+        this._executionModeName = executionModeName;
+        this._modeColors = modeColors;
     }
 
     /// <inheritdoc/>
-    public override void ConfigureRunOptions(AgentRunOptions options)
+    public override void ConfigureRunOptions(AgentRunOptions options, AIAgent agent, AgentSession session)
     {
-        options.ResponseFormat = ChatResponseFormat.ForJsonSchema<PlanningResponse>();
+        if (this.IsPlanningMode(this._modeProvider.GetMode(session)))
+        {
+            options.ResponseFormat = ChatResponseFormat.ForJsonSchema<PlanningResponse>();
+        }
     }
 
     /// <inheritdoc/>
-    public override Task OnTextAsync(HarnessUXContainer ux, string text)
+    public override Task OnTextAsync(IUXStateDriver ux, string text, AIAgent agent, AgentSession session)
     {
-        // Collect text silently instead of displaying it.
-        this._textCollector.Append(text);
-        return Task.CompletedTask;
+        if (this.IsPlanningMode(ux.CurrentMode))
+        {
+            // Planning mode: collect text silently for JSON parsing after the stream.
+            this._textCollector.Append(text);
+            return Task.CompletedTask;
+        }
+
+        // Execution mode: stream text directly to the console.
+        return ux.WriteTextAsync(text);
     }
 
     /// <inheritdoc/>
-    public override async Task<IList<ChatMessage>?> OnStreamCompleteAsync(
-        HarnessUXContainer ux,
+    public override async Task<IList<FollowUpAction>?> OnStreamCompleteAsync(
+        IUXStateDriver ux,
         AIAgent agent,
-        AgentSession session,
-        HarnessConsoleOptions options)
+        AgentSession session)
     {
+        if (!this.IsPlanningMode(ux.CurrentMode))
+        {
+            // Execution mode: text was already streamed live; nothing to parse.
+            this._textCollector.Clear();
+            return null;
+        }
+
         // Read collected text from our stream observation.
         string collectedText = this._textCollector.ToString();
         this._textCollector.Clear();
@@ -75,10 +101,9 @@ internal sealed class PlanningOutputObserver : ConsoleObserver
             return null;
         }
 
-        // Render based on response type.
         if (planningResponse.Type == PlanningResponseType.Clarification)
         {
-            return AsUserMessages(await this.RenderClarificationsAndCollectResponsesAsync(ux, planningResponse));
+            return BuildClarificationActions(planningResponse);
         }
 
         if (planningResponse.Type == PlanningResponseType.Approval)
@@ -90,67 +115,87 @@ internal sealed class PlanningOutputObserver : ConsoleObserver
                 return null;
             }
 
-            string response = await this.RenderApprovalAndCollectResponseAsync(ux, question, options);
-            if (response == "Approved")
-            {
-                this._modeProvider.SetMode(session, options.ExecutionModeName!);
-
-                await ux.WriteInfoLineAsync($"✅ Switched to {options.ExecutionModeName} mode.",
-                    ModeColors.Get(options.ExecutionModeName, options.ModeColors));
-            }
-
-            return AsUserMessages(response);
+            return new List<FollowUpAction> { this.BuildApprovalAction(question, session) };
         }
 
         await ux.WriteInfoLineAsync($"(unexpected response type: {planningResponse.Type})", ConsoleColor.DarkYellow);
         return null;
     }
 
-    private static IList<ChatMessage>? AsUserMessages(string? text) =>
-        text is not null ? [new ChatMessage(ChatRole.User, text)] : null;
-
-    private async Task<string?> RenderClarificationsAndCollectResponsesAsync(HarnessUXContainer ux, PlanningResponse response)
+    private static List<FollowUpAction> BuildClarificationActions(PlanningResponse response)
     {
-        var answers = new List<string>();
+        var actions = new List<FollowUpAction>(response.Questions.Count);
 
         foreach (var question in response.Questions)
         {
-            string? answer;
+            string prompt = question.Message;
+
+            async Task<ChatMessage?> Continuation(string answer, IUXStateDriver ux)
+            {
+                if (string.IsNullOrWhiteSpace(answer))
+                {
+                    string noAnswer = $"🔹 {prompt}\n   └─ {AnsiEscapes.SetForegroundColor(ConsoleColor.DarkGray)}(no answer){AnsiEscapes.ResetAttributes}";
+                    await ux.WriteInfoLineAsync(noAnswer, ConsoleColor.Gray).ConfigureAwait(false);
+                    return null;
+                }
+
+                string formatted = $"🔹 {prompt}\n   └─ {AnsiEscapes.SetForegroundColor(ConsoleColor.Green)}{answer}{AnsiEscapes.ResetAttributes}";
+                await ux.WriteInfoLineAsync(formatted, ConsoleColor.Gray).ConfigureAwait(false);
+
+                return new ChatMessage(ChatRole.User, $"Q: {prompt}\nA: {answer}");
+            }
+
             if (question.Choices is { Count: > 0 })
             {
-                answer = await ux.ReadSelectionAsync(
-                    question.Message,
-                    question.Choices);
+                actions.Add(new ChoiceFollowUpQuestion(
+                    Prompt: prompt,
+                    Choices: question.Choices,
+                    AllowCustomText: true,
+                    Continuation: Continuation));
             }
             else
             {
-                answer = (await ux.ReadLineAsync(question.Message))?.Trim();
-            }
-
-            if (!string.IsNullOrWhiteSpace(answer))
-            {
-                answers.Add($"Q: {question.Message}\nA: {answer}");
+                actions.Add(new TextFollowUpQuestion(
+                    Prompt: prompt,
+                    Continuation: Continuation));
             }
         }
 
-        return answers.Count > 0 ? string.Join("\n\n", answers) : null;
+        return actions;
     }
 
-    private async Task<string> RenderApprovalAndCollectResponseAsync(HarnessUXContainer ux, PlanningQuestion question, HarnessConsoleOptions options)
+    private ChoiceFollowUpQuestion BuildApprovalAction(PlanningQuestion question, AgentSession session)
     {
-        var choices = new List<string>
-        {
-            "Approve and switch to execute mode",
-        };
+        const string ApproveOption = "Approve and switch to execute mode";
+        var choices = new List<string> { ApproveOption };
 
-        string selection = await ux.ReadSelectionAsync(question.Message, choices);
+        return new ChoiceFollowUpQuestion(
+            Prompt: question.Message,
+            Choices: choices,
+            AllowCustomText: true,
+            Continuation: async (selection, ux) =>
+            {
+                string formatted = $"🔹 {question.Message}\n   └─ {AnsiEscapes.SetForegroundColor(ConsoleColor.Green)}{selection}{AnsiEscapes.ResetAttributes}";
+                await ux.WriteInfoLineAsync(formatted, ConsoleColor.Gray).ConfigureAwait(false);
 
-        if (selection == choices[0])
-        {
-            return "Approved";
-        }
+                if (selection == ApproveOption)
+                {
+                    this._modeProvider.SetMode(session, this._executionModeName);
+                    await ux.WriteInfoLineAsync(
+                        $"✅ Switched to {this._executionModeName} mode.",
+                        ModeColors.Get(this._executionModeName, this._modeColors)).ConfigureAwait(false);
+                    return new ChatMessage(ChatRole.User, "Approved");
+                }
 
-        // Custom freeform input — treat as suggested changes.
-        return selection;
+                // Custom freeform input — treat as suggested changes.
+                return new ChatMessage(ChatRole.User, selection);
+            });
     }
+
+    /// <summary>
+    /// Returns <see langword="true"/> when the current mode matches the configured plan mode name.
+    /// A <see langword="null"/> mode (no mode provider) is also treated as planning mode.
+    /// </summary>
+    private bool IsPlanningMode(string? currentMode) =>
+        currentMode is null || string.Equals(currentMode, this._planModeName, StringComparison.OrdinalIgnoreCase);
 }

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/ReasoningDisplayObserver.cs

@@ -1,5 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 
 namespace Harness.Shared.Console.Observers;
@@ -7,10 +8,10 @@ namespace Harness.Shared.Console.Observers;
 /// <summary>
 /// Displays reasoning content in dark magenta from the response stream.
 /// </summary>
-internal sealed class ReasoningDisplayObserver : ConsoleObserver
+public sealed class ReasoningDisplayObserver : ConsoleObserver
 {
     /// <inheritdoc/>
-    public override async Task OnContentAsync(HarnessUXContainer ux, AIContent content)
+    public override async Task OnContentAsync(IUXStateDriver ux, AIContent content, AIAgent agent, AgentSession session)
     {
         if (content is TextReasoningContent reasoning && !string.IsNullOrEmpty(reasoning.Text))
         {

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/TextOutputObserver.cs

@@ -1,15 +1,17 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using Microsoft.Agents.AI;
+
 namespace Harness.Shared.Console.Observers;
 
 /// <summary>
 /// Streams agent text output directly to the console.
 /// Used in normal (non-planning) mode.
 /// </summary>
-internal sealed class TextOutputObserver : ConsoleObserver
+public sealed class TextOutputObserver : ConsoleObserver
 {
     /// <inheritdoc/>
-    public override async Task OnTextAsync(HarnessUXContainer ux, string text)
+    public override async Task OnTextAsync(IUXStateDriver ux, string text, AIAgent agent, AgentSession session)
     {
         await ux.WriteTextAsync(text);
     }

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/ToolApprovalObserver.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using Harness.ConsoleReactiveComponents;
+using Harness.Shared.Console.ToolFormatters;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 
@@ -7,86 +9,103 @@ namespace Harness.Shared.Console.Observers;
 
 /// <summary>
 /// Collects <see cref="ToolApprovalRequestContent"/> items during the response stream,
-/// displays approval-needed notifications inline, and prompts the user for approval
-/// decisions after the stream completes.
+/// displays approval-needed notifications inline, and after the stream completes returns
+/// one <see cref="ChoiceFollowUpQuestion"/> per pending approval request. Each question's
+/// continuation produces a separate <see cref="ChatMessage"/> carrying the approval
+/// response content.
 /// </summary>
-internal sealed class ToolApprovalObserver : ConsoleObserver
+public sealed class ToolApprovalObserver : ConsoleObserver
 {
     private readonly List<ToolApprovalRequestContent> _approvalRequests = [];
+    private readonly IReadOnlyList<ToolCallFormatter> _formatters;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ToolApprovalObserver"/> class.
+    /// </summary>
+    /// <param name="formatters">Optional list of tool formatters. When <see langword="null"/>,
+    /// the default formatters from <see cref="ToolCallFormatter.BuildDefaultToolFormatters"/> are used.</param>
+    public ToolApprovalObserver(IReadOnlyList<ToolCallFormatter>? formatters = null)
+    {
+        this._formatters = formatters ?? ToolCallFormatter.BuildDefaultToolFormatters();
+    }
 
     /// <inheritdoc/>
-    public override async Task OnContentAsync(HarnessUXContainer ux, AIContent content)
+    public override async Task OnContentAsync(IUXStateDriver ux, AIContent content, AIAgent agent, AgentSession session)
     {
         if (content is ToolApprovalRequestContent approvalRequest)
         {
             this._approvalRequests.Add(approvalRequest);
             string toolName = approvalRequest.ToolCall is FunctionCallContent fc
-                ? ToolCallFormatter.Format(fc)
+                ? ToolCallFormatter.Format(this._formatters, fc)
                 : approvalRequest.ToolCall?.ToString() ?? "unknown";
             await ux.WriteInfoLineAsync($"⚠️ Approval needed: {toolName}", ConsoleColor.Yellow);
         }
     }
 
     /// <inheritdoc/>
-    public override async Task<IList<ChatMessage>?> OnStreamCompleteAsync(
-        HarnessUXContainer ux,
+    public override Task<IList<FollowUpAction>?> OnStreamCompleteAsync(
+        IUXStateDriver ux,
         AIAgent agent,
-        AgentSession session,
-        HarnessConsoleOptions options)
+        AgentSession session)
     {
         if (this._approvalRequests.Count == 0)
         {
-            return null;
+            return Task.FromResult<IList<FollowUpAction>?>(null);
+        }
+
+        var actions = new List<FollowUpAction>(this._approvalRequests.Count);
+        foreach (var request in this._approvalRequests)
+        {
+            actions.Add(this.BuildApprovalQuestion(request));
         }
 
-        var messages = await PromptForApprovalsAsync(ux, this._approvalRequests);
         this._approvalRequests.Clear();
-        return messages;
+        return Task.FromResult<IList<FollowUpAction>?>(actions);
     }
 
-    private static async Task<List<ChatMessage>?> PromptForApprovalsAsync(HarnessUXContainer ux, List<ToolApprovalRequestContent> approvalRequests)
+    private ChoiceFollowUpQuestion BuildApprovalQuestion(ToolApprovalRequestContent request)
     {
-        if (approvalRequests.Count == 0)
+        string toolName = request.ToolCall is FunctionCallContent fc
+            ? ToolCallFormatter.Format(this._formatters, fc)
+            : request.ToolCall?.ToString() ?? "unknown";
+
+        var choices = new List<string>
         {
-            return null;
-        }
+            "Approve this call",
+            "Always approve this tool (any arguments)",
+            "Always approve this tool with these arguments",
+            "Deny",
+        };
 
-        var responses = new List<AIContent>();
-        foreach (var request in approvalRequests)
-        {
-            string toolName = request.ToolCall is FunctionCallContent fc
-                ? ToolCallFormatter.Format(fc)
-                : request.ToolCall?.ToString() ?? "unknown";
+        string prompt = $"🔐 Tool approval: {toolName}";
 
-            var choices = new List<string>
+        return new ChoiceFollowUpQuestion(
+            Prompt: prompt,
+            Choices: choices,
+            AllowCustomText: false,
+            Continuation: async (selection, ux) =>
             {
-                "Approve this call",
-                "Always approve this tool (any arguments)",
-                "Always approve this tool with these arguments",
-                "Deny",
-            };
+                AIContent response = selection switch
+                {
+                    "Always approve this tool (any arguments)" => request.CreateAlwaysApproveToolResponse("User chose to always approve this tool"),
+                    "Always approve this tool with these arguments" => request.CreateAlwaysApproveToolWithArgumentsResponse("User chose to always approve this tool with these arguments"),
+                    "Deny" => request.CreateResponse(approved: false, reason: "User denied"),
+                    _ => request.CreateResponse(approved: true, reason: "User approved"),
+                };
 
-            string selection = await ux.ReadSelectionAsync($"🔐 Tool approval: {toolName}", choices);
-            AIContent response = selection switch
-            {
-                "Always approve this tool (any arguments)" => request.CreateAlwaysApproveToolResponse("User chose to always approve this tool"),
-                "Always approve this tool with these arguments" => request.CreateAlwaysApproveToolWithArgumentsResponse("User chose to always approve this tool with these arguments"),
-                "Deny" => request.CreateResponse(approved: false, reason: "User denied"),
-                _ => request.CreateResponse(approved: true, reason: "User approved"),
-            };
+                string action = selection switch
+                {
+                    "Always approve this tool (any arguments)" => "✅ Always approved (any args)",
+                    "Always approve this tool with these arguments" => "✅ Always approved (these args)",
+                    "Deny" => "❌ Denied",
+                    _ => "✅ Approved",
+                };
 
-            string action = selection switch
-            {
-                "Always approve this tool (any arguments)" => "✅ Always approved (any args)",
-                "Always approve this tool with these arguments" => "✅ Always approved (these args)",
-                "Deny" => "❌ Denied",
-                _ => "✅ Approved",
-            };
-            await ux.WriteInfoLineAsync($"   {action}", ConsoleColor.DarkGray);
+                ConsoleColor answerColor = selection == "Deny" ? ConsoleColor.Red : ConsoleColor.Green;
+                string formatted = $"🔹 {prompt}\n   └─ {AnsiEscapes.SetForegroundColor(answerColor)}{action}{AnsiEscapes.ResetAttributes}";
+                await ux.WriteInfoLineAsync(formatted, ConsoleColor.Gray).ConfigureAwait(false);
 
-            responses.Add(response);
-        }
-
-        return [new ChatMessage(ChatRole.User, responses)];
+                return new ChatMessage(ChatRole.User, [response]);
+            });
     }
 }

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/ToolCallDisplayObserver.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using Harness.Shared.Console.ToolFormatters;
+using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 
 namespace Harness.Shared.Console.Observers;
@@ -8,14 +10,26 @@ namespace Harness.Shared.Console.Observers;
 /// Displays tool call notifications (🔧) for <see cref="FunctionCallContent"/>
 /// and <see cref="ToolCallContent"/> items in the response stream.
 /// </summary>
-internal sealed class ToolCallDisplayObserver : ConsoleObserver
+public sealed class ToolCallDisplayObserver : ConsoleObserver
 {
+    private readonly IReadOnlyList<ToolCallFormatter> _formatters;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ToolCallDisplayObserver"/> class.
+    /// </summary>
+    /// <param name="formatters">Optional list of tool formatters. When <see langword="null"/>,
+    /// the default formatters from <see cref="ToolCallFormatter.BuildDefaultToolFormatters"/> are used.</param>
+    public ToolCallDisplayObserver(IReadOnlyList<ToolCallFormatter>? formatters = null)
+    {
+        this._formatters = formatters ?? ToolCallFormatter.BuildDefaultToolFormatters();
+    }
+
     /// <inheritdoc/>
-    public override async Task OnContentAsync(HarnessUXContainer ux, AIContent content)
+    public override async Task OnContentAsync(IUXStateDriver ux, AIContent content, AIAgent agent, AgentSession session)
     {
         if (content is FunctionCallContent functionCall)
         {
-            await ux.WriteInfoLineAsync($"🔧 Calling tool: {ToolCallFormatter.Format(functionCall)}...", ConsoleColor.DarkYellow);
+            await ux.WriteInfoLineAsync($"🔧 Calling tool: {ToolCallFormatter.Format(this._formatters, functionCall)}...", ConsoleColor.DarkYellow);
         }
         else if (content is ToolCallContent toolCall)
         {

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/ToolCallFormatter.cs

@@ -1,288 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System.Text;
-using System.Text.Json;
-using Microsoft.Extensions.AI;
-
-namespace Harness.Shared.Console.Observers;
-
-/// <summary>
-/// Formats <see cref="FunctionCallContent"/> instances into human-readable strings
-/// for console display.
-/// </summary>
-public static class ToolCallFormatter
-{
-    /// <summary>
-    /// Returns a formatted string for the given tool call, with human-readable
-    /// details for known tools (todos, mode, sub-agents, web tools).
-    /// </summary>
-    /// <param name="call">The function call content to format.</param>
-    /// <returns>A formatted string describing the tool call.</returns>
-    public static string Format(FunctionCallContent call)
-    {
-        string? detail = call.Name switch
-        {
-            // Todo tools
-            "TodoList_Add" => FormatAddTodos(call),
-            "TodoList_Complete" => FormatIdList(call, "ids", "Complete"),
-            "TodoList_Remove" => FormatIdList(call, "ids", "Remove"),
-            "TodoList_GetRemaining" => null,
-            "TodoList_GetAll" => null,
-
-            // Mode tools
-            "AgentMode_Set" => FormatStringArg(call, "mode"),
-            "AgentMode_Get" => null,
-
-            // Sub-agent tools
-            "SubAgents_StartTask" => FormatStartSubTask(call),
-            "SubAgents_WaitForFirstCompletion" => FormatIdList(call, "taskIds", "Wait for"),
-            "SubAgents_GetTaskResults" => FormatSingleId(call, "taskId"),
-            "SubAgents_GetAllTasks" => null,
-            "SubAgents_ContinueTask" => FormatContinueTask(call),
-            "SubAgents_ClearCompletedTask" => FormatSingleId(call, "taskId"),
-
-            // File memory tools
-            "FileMemory_SaveFile" => FormatSaveFile(call),
-            "FileMemory_ReadFile" => FormatStringArg(call, "fileName"),
-            "FileMemory_DeleteFile" => FormatStringArg(call, "fileName"),
-            "FileMemory_ListFiles" => null,
-            "FileMemory_SearchFiles" => FormatSearchFiles(call),
-
-            // External tools
-            "web_search" => FormatStringArg(call, "query"),
-            "DownloadUri" => FormatStringArg(call, "uri"),
-
-            _ => FormatFallback(call),
-        };
-
-        return detail is not null ? $"{call.Name} {detail}" : call.Name;
-    }
-
-    private static string? FormatAddTodos(FunctionCallContent call)
-    {
-        if (call.Arguments?.TryGetValue("todos", out object? todosObj) != true || todosObj is null)
-        {
-            return null;
-        }
-
-        var titles = new List<string>();
-
-        if (todosObj is JsonElement jsonArray && jsonArray.ValueKind == JsonValueKind.Array)
-        {
-            foreach (JsonElement item in jsonArray.EnumerateArray())
-            {
-                string? title = item.TryGetProperty("title", out JsonElement titleElement)
-                    ? titleElement.GetString()
-                    : null;
-
-                if (!string.IsNullOrEmpty(title))
-                {
-                    titles.Add(title);
-                }
-            }
-        }
-
-        if (titles.Count == 0)
-        {
-            return null;
-        }
-
-        var sb = new StringBuilder();
-        sb.Append($"({titles.Count} item{(titles.Count == 1 ? "" : "s")})");
-        foreach (string title in titles)
-        {
-            sb.Append($"\n    • {title}");
-        }
-
-        return sb.ToString();
-    }
-
-    private static string? FormatIdList(FunctionCallContent call, string paramName, string verb)
-    {
-        List<int>? ids = GetIntList(call, paramName);
-        if (ids is null || ids.Count == 0)
-        {
-            return null;
-        }
-
-        return $"({verb} #{string.Join(", #", ids)})";
-    }
-
-    private static string? FormatSingleId(FunctionCallContent call, string paramName)
-    {
-        int? id = GetInt(call, paramName);
-        return id.HasValue ? $"(task #{id.Value})" : null;
-    }
-
-    private static string? FormatStartSubTask(FunctionCallContent call)
-    {
-        string? agentName = GetString(call, "agentName");
-        string? description = GetString(call, "description");
-
-        if (agentName is null && description is null)
-        {
-            return null;
-        }
-
-        var sb = new StringBuilder("(");
-        if (agentName is not null)
-        {
-            sb.Append($"agent: {agentName}");
-        }
-
-        if (description is not null)
-        {
-            if (agentName is not null)
-            {
-                sb.Append(", ");
-            }
-
-            sb.Append($"\"{Truncate(description, 60)}\"");
-        }
-
-        sb.Append(')');
-        return sb.ToString();
-    }
-
-    private static string? FormatContinueTask(FunctionCallContent call)
-    {
-        int? taskId = GetInt(call, "taskId");
-        string? text = GetString(call, "text");
-
-        if (!taskId.HasValue)
-        {
-            return null;
-        }
-
-        return text is not null
-            ? $"(task #{taskId.Value}, \"{Truncate(text, 50)}\")"
-            : $"(task #{taskId.Value})";
-    }
-
-    private static string? FormatSaveFile(FunctionCallContent call)
-    {
-        string? fileName = GetString(call, "fileName");
-        string? description = GetString(call, "description");
-
-        if (fileName is null)
-        {
-            return null;
-        }
-
-        return string.IsNullOrEmpty(description)
-            ? $"({fileName})"
-            : $"({fileName}, with description)";
-    }
-
-    private static string? FormatSearchFiles(FunctionCallContent call)
-    {
-        string? pattern = GetString(call, "regexPattern");
-        string? filePattern = GetString(call, "filePattern");
-
-        if (pattern is null)
-        {
-            return null;
-        }
-
-        return string.IsNullOrEmpty(filePattern)
-            ? $"(/{pattern}/)"
-            : $"(/{pattern}/ in {filePattern})";
-    }
-
-    private static string? FormatStringArg(FunctionCallContent call, string paramName)
-    {
-        string? value = GetString(call, paramName);
-        return value is not null ? $"({value})" : null;
-    }
-
-    private static string? FormatFallback(FunctionCallContent call)
-    {
-        if (call.Arguments is null || call.Arguments.Count == 0)
-        {
-            return null;
-        }
-
-        var parts = new List<string>();
-        foreach (var kvp in call.Arguments)
-        {
-            string? stringValue = kvp.Value switch
-            {
-                JsonElement je => je.ValueKind switch
-                {
-                    JsonValueKind.String => je.GetString(),
-                    JsonValueKind.Number => je.GetRawText(),
-                    JsonValueKind.True => "true",
-                    JsonValueKind.False => "false",
-                    _ => null,
-                },
-                not null => kvp.Value.ToString(),
-                _ => null,
-            };
-
-            if (stringValue is not null)
-            {
-                parts.Add($"{kvp.Key}: {Truncate(stringValue, 40)}");
-            }
-        }
-
-        return parts.Count > 0 ? $"({string.Join(", ", parts)})" : null;
-    }
-
-    private static string? GetString(FunctionCallContent call, string paramName)
-    {
-        if (call.Arguments?.TryGetValue(paramName, out object? value) != true || value is null)
-        {
-            return null;
-        }
-
-        return value switch
-        {
-            JsonElement je when je.ValueKind == JsonValueKind.String => je.GetString(),
-            string s => s,
-            _ => value.ToString(),
-        };
-    }
-
-    private static int? GetInt(FunctionCallContent call, string paramName)
-    {
-        if (call.Arguments?.TryGetValue(paramName, out object? value) != true || value is null)
-        {
-            return null;
-        }
-
-        return value switch
-        {
-            JsonElement je when je.ValueKind == JsonValueKind.Number => je.GetInt32(),
-            int i => i,
-            _ => int.TryParse(value.ToString(), out int parsed) ? parsed : null,
-        };
-    }
-
-    private static List<int>? GetIntList(FunctionCallContent call, string paramName)
-    {
-        if (call.Arguments?.TryGetValue(paramName, out object? value) != true || value is null)
-        {
-            return null;
-        }
-
-        var result = new List<int>();
-
-        if (value is JsonElement je && je.ValueKind == JsonValueKind.Array)
-        {
-            foreach (JsonElement item in je.EnumerateArray())
-            {
-                if (item.ValueKind == JsonValueKind.Number)
-                {
-                    result.Add(item.GetInt32());
-                }
-            }
-        }
-
-        return result.Count > 0 ? result : null;
-    }
-
-    private static string Truncate(string text, int maxLength)
-    {
-        return text.Length <= maxLength ? text : string.Concat(text.AsSpan(0, maxLength), "…");
-    }
-}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/UsageDisplayObserver.cs

@@ -1,5 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 
 namespace Harness.Shared.Console.Observers;
@@ -7,7 +8,7 @@ namespace Harness.Shared.Console.Observers;
 /// <summary>
 /// Displays token usage statistics (📊) from the response stream.
 /// </summary>
-internal sealed class UsageDisplayObserver : ConsoleObserver
+public sealed class UsageDisplayObserver : ConsoleObserver
 {
     private readonly int? _maxContextWindowTokens;
     private readonly int? _maxOutputTokens;
@@ -24,7 +25,7 @@ internal sealed class UsageDisplayObserver : ConsoleObserver
     }
 
     /// <inheritdoc/>
-    public override Task OnContentAsync(HarnessUXContainer ux, AIContent content)
+    public override Task OnContentAsync(IUXStateDriver ux, AIContent content, AIAgent agent, AgentSession session)
     {
         if (content is UsageContent usage)
         {

dotnet/samples/02-agents/Harness/Harness_Shared_Console/OutputEntry.cs

@@ -5,7 +5,7 @@ namespace Harness.Shared.Console;
 /// <summary>
 /// Represents the type of an output entry in the console conversation.
 /// </summary>
-public enum OutputEntryType
+internal enum OutputEntryType
 {
     /// <summary>User input echo (e.g. "You: hello").</summary>
     UserInput,
@@ -25,9 +25,10 @@ public enum OutputEntryType
 
 /// <summary>
 /// Represents a single output entry in the console conversation history.
-/// These entries are rendered by the <see cref="HarnessAppComponent"/> via its render delegate.
+/// Used internally by <see cref="HarnessConsoleUXStateDriver"/> to track
+/// the in-progress streaming entry and last-entry type for spacing decisions.
 /// </summary>
 /// <param name="Type">The type of output entry.</param>
 /// <param name="Text">The text content of the entry.</param>
 /// <param name="Color">Optional foreground color for rendering.</param>
-public record OutputEntry(OutputEntryType Type, string Text, ConsoleColor? Color = null);
+internal sealed record OutputEntry(OutputEntryType Type, string Text, ConsoleColor? Color = null);

dotnet/samples/02-agents/Harness/Harness_Shared_Console/ToolFormatters/FallbackToolFormatter.cs

@@ -0,0 +1,51 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.ToolFormatters;
+
+/// <summary>
+/// Catch-all formatter that handles any tool not matched by a more specific formatter.
+/// Displays a generic summary of the tool's arguments. This formatter should always be
+/// placed last in the formatter list.
+/// </summary>
+public sealed class FallbackToolFormatter : ToolCallFormatter
+{
+    /// <inheritdoc/>
+    public override bool CanFormat(FunctionCallContent call) => true;
+
+    /// <inheritdoc/>
+    public override string? FormatDetail(FunctionCallContent call)
+    {
+        if (call.Arguments is null || call.Arguments.Count == 0)
+        {
+            return null;
+        }
+
+        var parts = new List<string>();
+        foreach (var kvp in call.Arguments)
+        {
+            string? stringValue = kvp.Value switch
+            {
+                JsonElement je => je.ValueKind switch
+                {
+                    JsonValueKind.String => je.GetString(),
+                    JsonValueKind.Number => je.GetRawText(),
+                    JsonValueKind.True => "true",
+                    JsonValueKind.False => "false",
+                    _ => null,
+                },
+                not null => kvp.Value.ToString(),
+                _ => null,
+            };
+
+            if (stringValue is not null)
+            {
+                parts.Add($"{kvp.Key}: {Truncate(stringValue, 40)}");
+            }
+        }
+
+        return parts.Count > 0 ? $"({string.Join(", ", parts)})" : null;
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/ToolFormatters/FileMemoryToolFormatter.cs

@@ -0,0 +1,61 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.ToolFormatters;
+
+/// <summary>
+/// Formats <c>FileMemory_*</c> tool calls, showing file names and search patterns
+/// with tree-view corners for save operations.
+/// </summary>
+public sealed class FileMemoryToolFormatter : ToolCallFormatter
+{
+    /// <inheritdoc/>
+    public override bool CanFormat(FunctionCallContent call) => call.Name.StartsWith("FileMemory_", StringComparison.Ordinal);
+
+    /// <inheritdoc/>
+    public override string? FormatDetail(FunctionCallContent call) => call.Name switch
+    {
+        "FileMemory_SaveFile" => FormatSaveFile(call),
+        "FileMemory_ReadFile" => FormatStringArg(call, "fileName"),
+        "FileMemory_DeleteFile" => FormatStringArg(call, "fileName"),
+        "FileMemory_SearchFiles" => FormatSearchFiles(call),
+        _ => null,
+    };
+
+    private static string? FormatSaveFile(FunctionCallContent call)
+    {
+        string? fileName = GetStringArgumentValue(call, "fileName");
+        string? description = GetStringArgumentValue(call, "description");
+
+        if (fileName is null)
+        {
+            return null;
+        }
+
+        return string.IsNullOrEmpty(description)
+            ? $"\n   └─ {fileName}"
+            : $"\n   └─ {fileName} (with description)";
+    }
+
+    private static string? FormatSearchFiles(FunctionCallContent call)
+    {
+        string? pattern = GetStringArgumentValue(call, "regexPattern");
+        string? filePattern = GetStringArgumentValue(call, "filePattern");
+
+        if (pattern is null)
+        {
+            return null;
+        }
+
+        return string.IsNullOrEmpty(filePattern)
+            ? $"(/{pattern}/)"
+            : $"(/{pattern}/ in {filePattern})";
+    }
+
+    private static string? FormatStringArg(FunctionCallContent call, string paramName)
+    {
+        string? value = GetStringArgumentValue(call, paramName);
+        return value is not null ? $"({value})" : null;
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/ToolFormatters/ModeToolFormatter.cs

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.ToolFormatters;
+
+/// <summary>
+/// Formats <c>AgentMode_*</c> tool calls, showing the target mode for Set operations.
+/// </summary>
+public sealed class ModeToolFormatter : ToolCallFormatter
+{
+    /// <inheritdoc/>
+    public override bool CanFormat(FunctionCallContent call) => call.Name.StartsWith("AgentMode_", StringComparison.Ordinal);
+
+    /// <inheritdoc/>
+    public override string? FormatDetail(FunctionCallContent call) => call.Name switch
+    {
+        "AgentMode_Set" => FormatStringArg(call, "mode"),
+        _ => null,
+    };
+
+    private static string? FormatStringArg(FunctionCallContent call, string paramName)
+    {
+        string? value = GetStringArgumentValue(call, paramName);
+        return value is not null ? $"({value})" : null;
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/ToolFormatters/SubAgentToolFormatter.cs

@@ -0,0 +1,101 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text;
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.ToolFormatters;
+
+/// <summary>
+/// Formats <c>SubAgents_*</c> tool calls with human-readable details
+/// for task start, continue, wait, and result retrieval operations.
+/// </summary>
+public sealed class SubAgentToolFormatter : ToolCallFormatter
+{
+    /// <inheritdoc/>
+    public override bool CanFormat(FunctionCallContent call) => call.Name.StartsWith("SubAgents_", StringComparison.Ordinal);
+
+    /// <inheritdoc/>
+    public override string? FormatDetail(FunctionCallContent call) => call.Name switch
+    {
+        "SubAgents_StartTask" => FormatStartSubTask(call),
+        "SubAgents_WaitForFirstCompletion" => FormatIdList(call, "taskIds", "Wait for"),
+        "SubAgents_GetTaskResults" => FormatSingleId(call, "taskId"),
+        "SubAgents_ContinueTask" => FormatContinueTask(call),
+        "SubAgents_ClearCompletedTask" => FormatSingleId(call, "taskId"),
+        _ => null,
+    };
+
+    private static string? FormatStartSubTask(FunctionCallContent call)
+    {
+        string? agentName = GetStringArgumentValue(call, "agentName");
+        string? description = GetStringArgumentValue(call, "description");
+
+        if (agentName is null && description is null)
+        {
+            return null;
+        }
+
+        var sb = new StringBuilder();
+
+        if (agentName is not null && description is not null)
+        {
+            sb.Append($"\n   ├─ Agent: {agentName}");
+            sb.Append($"\n   └─ \"{Truncate(description, 80)}\"");
+        }
+        else if (agentName is not null)
+        {
+            sb.Append($"\n   └─ Agent: {agentName}");
+        }
+        else
+        {
+            sb.Append($"\n   └─ \"{Truncate(description!, 80)}\"");
+        }
+
+        return sb.ToString();
+    }
+
+    private static string? FormatIdList(FunctionCallContent call, string paramName, string verb)
+    {
+        List<int>? ids = GetIntListArgumentValue(call, paramName);
+        if (ids is null || ids.Count == 0)
+        {
+            return null;
+        }
+
+        var sb = new StringBuilder();
+        for (int i = 0; i < ids.Count; i++)
+        {
+            string connector = i < ids.Count - 1 ? "├─" : "└─";
+            sb.Append($"\n   {connector} {verb} #{ids[i]}");
+        }
+
+        return sb.ToString();
+    }
+
+    private static string? FormatSingleId(FunctionCallContent call, string paramName)
+    {
+        int? id = GetIntArgumentValue(call, paramName);
+        return id.HasValue ? $"(task #{id.Value})" : null;
+    }
+
+    private static string? FormatContinueTask(FunctionCallContent call)
+    {
+        int? taskId = GetIntArgumentValue(call, "taskId");
+        string? text = GetStringArgumentValue(call, "text");
+
+        if (!taskId.HasValue)
+        {
+            return null;
+        }
+
+        if (text is not null)
+        {
+            var sb = new StringBuilder();
+            sb.Append($"\n   ├─ Task #{taskId.Value}");
+            sb.Append($"\n   └─ \"{Truncate(text, 80)}\"");
+            return sb.ToString();
+        }
+
+        return $"\n   └─ Task #{taskId.Value}";
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/ToolFormatters/TodoToolFormatter.cs

@@ -0,0 +1,84 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text;
+using System.Text.Json;
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.ToolFormatters;
+
+/// <summary>
+/// Formats <c>TodoList_*</c> tool calls with tree-view output for added items
+/// and structured output for complete/remove operations.
+/// </summary>
+public sealed class TodoToolFormatter : ToolCallFormatter
+{
+    /// <inheritdoc/>
+    public override bool CanFormat(FunctionCallContent call) => call.Name.StartsWith("TodoList_", StringComparison.Ordinal);
+
+    /// <inheritdoc/>
+    public override string? FormatDetail(FunctionCallContent call) => call.Name switch
+    {
+        "TodoList_Add" => FormatAddTodos(call),
+        "TodoList_Complete" => FormatIdList(call, "ids", "Complete"),
+        "TodoList_Remove" => FormatIdList(call, "ids", "Remove"),
+        _ => null,
+    };
+
+    private static string? FormatAddTodos(FunctionCallContent call)
+    {
+        if (call.Arguments?.TryGetValue("todos", out object? todosObj) != true || todosObj is null)
+        {
+            return null;
+        }
+
+        var titles = new List<string>();
+
+        if (todosObj is JsonElement jsonArray && jsonArray.ValueKind == JsonValueKind.Array)
+        {
+            foreach (JsonElement item in jsonArray.EnumerateArray())
+            {
+                string? title = item.TryGetProperty("title", out JsonElement titleElement)
+                    ? titleElement.GetString()
+                    : null;
+
+                if (!string.IsNullOrEmpty(title))
+                {
+                    titles.Add(title);
+                }
+            }
+        }
+
+        if (titles.Count == 0)
+        {
+            return null;
+        }
+
+        var sb = new StringBuilder();
+        sb.Append($"({titles.Count} item{(titles.Count == 1 ? "" : "s")})");
+        for (int i = 0; i < titles.Count; i++)
+        {
+            string connector = i < titles.Count - 1 ? "├─" : "└─";
+            sb.Append($"\n   {connector} {titles[i]}");
+        }
+
+        return sb.ToString();
+    }
+
+    private static string? FormatIdList(FunctionCallContent call, string paramName, string verb)
+    {
+        List<int>? ids = GetIntListArgumentValue(call, paramName);
+        if (ids is null || ids.Count == 0)
+        {
+            return null;
+        }
+
+        var sb = new StringBuilder();
+        for (int i = 0; i < ids.Count; i++)
+        {
+            string connector = i < ids.Count - 1 ? "├─" : "└─";
+            sb.Append($"\n   {connector} {verb} #{ids[i]}");
+        }
+
+        return sb.ToString();
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/ToolFormatters/ToolCallFormatter.cs

@@ -0,0 +1,135 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.ToolFormatters;
+
+/// <summary>
+/// Base class for tool call formatters that produce human-readable display strings
+/// for <see cref="FunctionCallContent"/> items shown in the console.
+/// </summary>
+public abstract class ToolCallFormatter
+{
+    /// <summary>
+    /// Returns <see langword="true"/> if this formatter can handle the given function call.
+    /// </summary>
+    /// <param name="call">The function call content to check.</param>
+    /// <returns><see langword="true"/> if this formatter should be used; otherwise <see langword="false"/>.</returns>
+    public abstract bool CanFormat(FunctionCallContent call);
+
+    /// <summary>
+    /// Returns the detail portion of the formatted output for the given tool call,
+    /// or <see langword="null"/> if only the tool name should be displayed.
+    /// </summary>
+    /// <param name="call">The function call content to format.</param>
+    /// <returns>A detail string to append after the tool name, or <see langword="null"/>.</returns>
+    public abstract string? FormatDetail(FunctionCallContent call);
+
+    /// <summary>
+    /// Formats a tool call using the first matching formatter from the provided list.
+    /// Returns <c>"{toolName} {detail}"</c> when a formatter produces detail,
+    /// or just <c>"{toolName}"</c> otherwise.
+    /// </summary>
+    internal static string Format(IReadOnlyList<ToolCallFormatter> formatters, FunctionCallContent call)
+    {
+        foreach (var formatter in formatters)
+        {
+            if (formatter.CanFormat(call))
+            {
+                string? detail = formatter.FormatDetail(call);
+                return detail is not null ? $"{call.Name} {detail}" : call.Name;
+            }
+        }
+
+        return call.Name;
+    }
+
+    /// <summary>
+    /// Creates the default list of tool call formatters. The <see cref="FallbackToolFormatter"/>
+    /// is always last. Users can call this method and combine the result with their own formatters.
+    /// </summary>
+    /// <returns>A list of all built-in tool call formatters.</returns>
+    public static List<ToolCallFormatter> BuildDefaultToolFormatters()
+    {
+        return
+        [
+            new TodoToolFormatter(),
+            new ModeToolFormatter(),
+            new SubAgentToolFormatter(),
+            new FileMemoryToolFormatter(),
+            new WebSearchToolFormatter(),
+            new FallbackToolFormatter(),
+        ];
+    }
+
+    /// <summary>
+    /// Extracts a string argument value from a function call.
+    /// </summary>
+    protected static string? GetStringArgumentValue(FunctionCallContent call, string paramName)
+    {
+        if (call.Arguments?.TryGetValue(paramName, out object? value) != true || value is null)
+        {
+            return null;
+        }
+
+        return value switch
+        {
+            JsonElement je when je.ValueKind == JsonValueKind.String => je.GetString(),
+            string s => s,
+            _ => value.ToString(),
+        };
+    }
+
+    /// <summary>
+    /// Extracts an integer argument value from a function call.
+    /// </summary>
+    protected static int? GetIntArgumentValue(FunctionCallContent call, string paramName)
+    {
+        if (call.Arguments?.TryGetValue(paramName, out object? value) != true || value is null)
+        {
+            return null;
+        }
+
+        return value switch
+        {
+            JsonElement je when je.ValueKind == JsonValueKind.Number => je.GetInt32(),
+            int i => i,
+            _ => int.TryParse(value.ToString(), out int parsed) ? parsed : null,
+        };
+    }
+
+    /// <summary>
+    /// Extracts a list of integer argument values from a function call.
+    /// </summary>
+    protected static List<int>? GetIntListArgumentValue(FunctionCallContent call, string paramName)
+    {
+        if (call.Arguments?.TryGetValue(paramName, out object? value) != true || value is null)
+        {
+            return null;
+        }
+
+        var result = new List<int>();
+
+        if (value is JsonElement je && je.ValueKind == JsonValueKind.Array)
+        {
+            foreach (JsonElement item in je.EnumerateArray())
+            {
+                if (item.ValueKind == JsonValueKind.Number)
+                {
+                    result.Add(item.GetInt32());
+                }
+            }
+        }
+
+        return result.Count > 0 ? result : null;
+    }
+
+    /// <summary>
+    /// Truncates a string to the specified maximum length, appending an ellipsis if truncated.
+    /// </summary>
+    protected static string Truncate(string text, int maxLength)
+    {
+        return text.Length <= maxLength ? text : string.Concat(text.AsSpan(0, maxLength), "…");
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/ToolFormatters/WebSearchToolFormatter.cs

@@ -0,0 +1,22 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.ToolFormatters;
+
+/// <summary>
+/// Formats <c>web_search</c> tool calls, showing the search query.
+/// </summary>
+public sealed class WebSearchToolFormatter : ToolCallFormatter
+{
+    /// <inheritdoc/>
+    public override bool CanFormat(FunctionCallContent call) =>
+        call.Name is "web_search";
+
+    /// <inheritdoc/>
+    public override string? FormatDetail(FunctionCallContent call)
+    {
+        string? value = GetStringArgumentValue(call, "query");
+        return value is not null ? $"({value})" : null;
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Step01_Research/DownloadUriToolFormatter.cs

@@ -0,0 +1,23 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Harness.Shared.Console.ToolFormatters;
+using Microsoft.Extensions.AI;
+
+namespace SampleApp;
+
+/// <summary>
+/// Formats <c>DownloadUri</c> tool calls, showing the target URI.
+/// </summary>
+public sealed class DownloadUriToolFormatter : ToolCallFormatter
+{
+    /// <inheritdoc/>
+    public override bool CanFormat(FunctionCallContent call) =>
+        call.Name is "DownloadUri";
+
+    /// <inheritdoc/>
+    public override string? FormatDetail(FunctionCallContent call)
+    {
+        string? value = GetStringArgumentValue(call, "uri");
+        return value is not null ? $"({value})" : null;
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Step01_Research/Harness_Step01_Research.csproj

@@ -13,6 +13,7 @@
   </ItemGroup>
 
   <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Harness\Microsoft.Agents.AI.Harness.csproj" />
     <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
     <ProjectReference Include="..\Harness_Shared_Console\Harness_Shared_Console.csproj" />
   </ItemGroup>

dotnet/samples/02-agents/Harness/Harness_Step01_Research/Program.cs

@@ -1,6 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-// This sample demonstrates how to use a ChatClientAgent with the Harness AIContextProviders
+// This sample demonstrates how to use a HarnessAgent with the Harness AIContextProviders
 // (TodoProvider and AgentModeProvider) for interactive research tasks with web search
 // capabilities powered by Azure AI Foundry.
 // The agent plans research tasks, creates a todo list, gets user approval,
@@ -8,7 +8,8 @@
 //
 // Special commands:
 //   /todos  — Display the current todo list without invoking the agent.
-//   exit    — End the session.
+//   /mode   — Get or set the current agent mode.
+//   /exit   — End the session.
 
 #pragma warning disable OPENAI001 // Suppress experimental API warnings for Responses API usage.
 #pragma warning disable MAAI001  // Suppress experimental API warnings for Agents AI experiments.
@@ -16,8 +17,8 @@
 using System.ClientModel.Primitives;
 using Azure.Identity;
 using Harness.Shared.Console;
+using Harness.Shared.Console.ToolFormatters;
 using Microsoft.Agents.AI;
-using Microsoft.Agents.AI.Compaction;
 using Microsoft.Extensions.AI;
 using OpenAI;
 using OpenAI.Responses;
@@ -29,7 +30,7 @@ var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYME
 const int MaxContextWindowTokens = 1_050_000;
 const int MaxOutputTokens = 128_000;
 
-// Create a ChatClientAgent with the Harness providers (TodoProvider and AgentModeProvider)
+// Create a HarnessAgent with the Harness providers (TodoProvider and AgentModeProvider)
 // and research-focused instructions including the mandatory planning workflow.
 var instructions =
     """
@@ -110,13 +111,9 @@ var instructions =
     - Check for relevant previously downloaded data / findings before starting new research.
     """;
 
-// Create a compaction strategy based on the model's context window.
-// gpt-5.4: 1,050,000 token context window, 128,000 max output tokens.
-// Defaults: tool result eviction at 50% of input budget, truncation at 80%.
-var compactionStrategy = new ContextWindowCompactionStrategy(
-    maxContextWindowTokens: MaxContextWindowTokens,
-    maxOutputTokens: MaxOutputTokens);
-
+// Create the agent using AsHarnessAgent, which pre-configures function invocation,
+// per-service-call chat history persistence, and in-loop compaction.
+// Then wrap with UseToolApproval to allow auto-approving tools once confirmed.
 AIAgent agent =
     // Create an OpenAIClient that communicates with the Foundry responses service.
     new OpenAIClient(
@@ -130,49 +127,32 @@ AIAgent agent =
             RetryPolicy = new ClientRetryPolicy(3)          // Enable retries to improve resiliency.
         })
     .GetResponsesClient()
-    .AsIChatClientWithStoredOutputDisabled(deploymentName)  // We want to manage chat history locally (not stored in the responses service), so that we can manage compaction ourselves.
-
-    // Build a ChatClient Pipeline
-    .AsBuilder()
-    .UseFunctionInvocation()                                // We are building our own stack from scratch so we need to include Function Invocation ourselves.
-    .UseMessageInjection()                                  // Allow message injection during the function call loop.
-    .UsePerServiceCallChatHistoryPersistence()              // Save chat history updates to the session after each service call, rather than only at the end of the run.
-    .UseAIContextProviders(new CompactionProvider(compactionStrategy))  // Add Compaction before each service call to responses so that long function invocation loops don't overflow the context.
-
-    // Build our agent on top of the ChatClient Pipeline
-    .BuildAIAgent(
-        new ChatClientAgentOptions
+    .AsIChatClientWithStoredOutputDisabled(deploymentName)   // We want to manage chat history locally (not stored in the responses service), so that we can manage compaction ourselves.
+    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
+    {
+        Name = "ResearchAgent",
+        Description = "A research assistant that plans and executes research tasks.",
+        AIContextProviders =
+        [
+            new TodoProvider(),         // Add an AIContextProvider to allow the agent to create a TODO list, which is stored in the session.
+            new AgentModeProvider(),    // Add an AIContextProvider that tracks the agent mode and allows switching mode. Current mode is stored in the session.
+            new FileMemoryProvider(     // Add an AIContextProvider that can store memories in files under a session specific working folder.
+                new FileSystemAgentFileStore(Path.Combine(AppContext.BaseDirectory, "agent-files")),
+                (_) => new FileMemoryState() { WorkingFolder = DateTime.UtcNow.ToString("yyyyMMdd_HHmmss") + "_" + Guid.NewGuid().ToString() })
+        ],
+        ChatOptions = new ChatOptions
         {
-            Name = "ResearchAgent",
-            Description = "A research assistant that plans and executes research tasks.",
-            UseProvidedChatClientAsIs = true,                           // Since we built our own stack from scratch we need to tell the agent not to also add defaults like Function Invocation.
-            RequirePerServiceCallChatHistoryPersistence = true,         // Since we are added the per service call persistence ChatClient, we need to tell the agent to not also store chat history at the end of the run.
-            ChatHistoryProvider = new InMemoryChatHistoryProvider(      // Store chat history in memory in the session object. Will persist if the session is persisted.
-                new InMemoryChatHistoryProviderOptions
-                {
-                    ChatReducer = compactionStrategy.AsChatReducer(),   // Run compaction on the InMemory chat history when it gets too large.
-                }),
-            AIContextProviders =
+            Instructions = instructions,
+            Tools =
             [
-                new TodoProvider(),         // Add an AIContextProvider to allow the agent to create a TODO list, which is stored in the session.
-                new AgentModeProvider(),    // Add an AIContextProvider that tracks the agent mode and allows switching mode. Current mode is stored in the session.
-                new FileMemoryProvider(     // Add an AIContextProvider that can store memories in files under a session specific working folder.
-                    new FileSystemAgentFileStore(Path.Combine(AppContext.BaseDirectory, "agent-files")),
-                    (_) => new FileMemoryState() { WorkingFolder = DateTime.UtcNow.ToString("yyyyMMdd_HHmmss") + "_" + Guid.NewGuid().ToString() })
+                ResponseTool.CreateWebSearchTool().AsAITool(),          // Add the foundry hosted web search tool that runs in the service.
+                new WebBrowsingTool(                                    // Add a local web browsing tool that converts html to markdown.
+                    new WebBrowsingToolOptions { AllowPublicNetworks = true }),
             ],
-            ChatOptions = new ChatOptions
-            {
-                Instructions = instructions,
-                Tools =
-                [
-                    ResponseTool.CreateWebSearchTool().AsAITool(),          // Add the foundry hosted web search tool that runs in the service.
-                    new WebBrowsingTool(                                    // Add a local web browsing tool that converts html to markdown.
-                        new WebBrowsingToolOptions { AllowPublicNetworks = true }),
-                ],
-                MaxOutputTokens = MaxOutputTokens,                          // Set a high token limit for long research tasks with many tool calls and long outputs.
-                Reasoning = new() { Effort = ReasoningEffort.Medium },
-            },
-        })
+            MaxOutputTokens = MaxOutputTokens,                          // Set a high token limit for long research tasks with many tool calls and long outputs.
+            Reasoning = new() { Effort = ReasoningEffort.Medium },
+        },
+    })
     .AsBuilder()
     .UseToolApproval()                                                      // Add the ability to auto approve tools once a user has said they don't want to be asked again. Approval rules are tied to the session.
     .Build();
@@ -180,13 +160,15 @@ AIAgent agent =
 // Run the interactive console session using the shared HarnessConsole helper.
 await HarnessConsole.RunAgentAsync(
     agent,
-    title: "Research Assistant",
     userPrompt: "Enter a research topic to get started.",
     new HarnessConsoleOptions
     {
-        MaxContextWindowTokens = MaxContextWindowTokens,
-        MaxOutputTokens = MaxOutputTokens,
-        EnablePlanningUx = true,
-        PlanningModeName = "plan",
-        ExecutionModeName = "execute"
+        Observers = HarnessConsoleOptions.BuildObserversWithPlanning(
+            agent,
+            planModeName: "plan",
+            executionModeName: "execute",
+            maxContextWindowTokens: MaxContextWindowTokens,
+            maxOutputTokens: MaxOutputTokens,
+            toolFormatters: [new DownloadUriToolFormatter(), .. ToolCallFormatter.BuildDefaultToolFormatters()]),
+        CommandHandlers = HarnessConsoleOptions.BuildDefaultCommandHandlers(agent),
     });

dotnet/samples/02-agents/Harness/Harness_Step01_Research/README.md

@@ -1,10 +1,11 @@
 # What this sample demonstrates
 
-This sample demonstrates how to use a `ChatClientAgent` with the Harness `AIContextProviders` (`TodoProvider` and `AgentModeProvider`) for interactive research tasks with web search capabilities powered by Azure AI Foundry.
+This sample demonstrates how to use a `HarnessAgent` with the Harness `AIContextProviders` (`TodoProvider` and `AgentModeProvider`) for interactive research tasks with web search capabilities powered by Azure AI Foundry. The `HarnessAgent` pre-configures function invocation, per-service-call chat history persistence, and context-window compaction.
 
 Key features showcased:
 
-- **ChatClientAgent** — configured directly with Harness providers for planning and task management
+- **HarnessAgent** — a pre-configured agent that wraps a `ChatClientAgent` with function invocation, per-service-call persistence, and context-window compaction
+- **ToolApproval** — the agent is wrapped with `UseToolApproval()` to allow auto-approving tools once confirmed
 - **Web Search** — the agent can search the web for current information via `ResponseTool.CreateWebSearchTool()`
 - **TodoProvider** — the agent creates and manages a todo list to track research questions
 - **AgentModeProvider** — the agent switches between "plan" mode (breaking down the topic) and "execute" mode (answering each research question)

dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithSubAgents/Harness_Step02_Research_WithSubAgents.csproj

@@ -13,6 +13,7 @@
   </ItemGroup>
 
   <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Harness\Microsoft.Agents.AI.Harness.csproj" />
     <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
     <ProjectReference Include="..\Harness_Shared_Console\Harness_Shared_Console.csproj" />
   </ItemGroup>

dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithSubAgents/Program.cs

@@ -6,7 +6,7 @@
 // equipped with Foundry's hosted web search tool.
 //
 // Special commands:
-//   exit    — End the session.
+//   /exit    — End the session.
 
 #pragma warning disable OPENAI001 // Suppress experimental API warnings for Responses API usage.
 #pragma warning disable MAAI001  // Suppress experimental API warnings for Agents AI experiments.
@@ -22,6 +22,9 @@ using OpenAI.Responses;
 var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_OPENAI_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4";
 
+const int MaxContextWindowTokens = 1_050_000;
+const int MaxOutputTokens = 128_000;
+
 // --- Sub-agent: Web Search Agent ---
 // This agent can search the web and is used by the parent agent to look up stock prices.
 AIAgent webSearchAgent =
@@ -34,20 +37,19 @@ AIAgent webSearchAgent =
         })
     .GetResponsesClient()
     .AsIChatClientWithStoredOutputDisabled(deploymentName)
-    .AsAIAgent(
-        new ChatClientAgentOptions
+    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
+    {
+        Name = "WebSearchAgent",
+        Description = "An agent that can search the web to find information.",
+        ChatOptions = new ChatOptions
         {
-            Name = "WebSearchAgent",
-            Description = "An agent that can search the web to find information.",
-            ChatOptions = new ChatOptions
-            {
-                Instructions = "You are a web search assistant. When asked to find information, use the web search tool to look it up and return a concise, factual answer.",
-                Tools =
-                [
-                    ResponseTool.CreateWebSearchTool().AsAITool(),
-                ],
-            },
-        });
+            Instructions = "You are a web search assistant. When asked to find information, use the web search tool to look it up and return a concise, factual answer.",
+            Tools =
+            [
+                ResponseTool.CreateWebSearchTool().AsAITool(),
+            ],
+        },
+    });
 
 // --- Parent agent: Stock Price Researcher ---
 // This agent orchestrates the sub-agent to look up stock prices in parallel.
@@ -83,24 +85,22 @@ AIAgent parentAgent =
         })
     .GetResponsesClient()
     .AsIChatClientWithStoredOutputDisabled(deploymentName)
-    .AsAIAgent(
-        new ChatClientAgentOptions
+    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
+    {
+        Name = "StockPriceResearcher",
+        Description = "An agent that researches stock prices using sub-agents.",
+        AIContextProviders =
+        [
+            new SubAgentsProvider([webSearchAgent]),
+        ],
+        ChatOptions = new ChatOptions
         {
-            Name = "StockPriceResearcher",
-            Description = "An agent that researches stock prices using sub-agents.",
-            AIContextProviders =
-            [
-                new SubAgentsProvider([webSearchAgent]),
-            ],
-            ChatOptions = new ChatOptions
-            {
-                Instructions = parentInstructions,
-                MaxOutputTokens = 16_000,
-            },
-        });
+            Instructions = parentInstructions,
+            MaxOutputTokens = 16_000,
+        },
+    });
 
 // Run the interactive console session.
 await HarnessConsole.RunAgentAsync(
     parentAgent,
-    title: "Stock Price Researcher (SubAgents Demo)",
     userPrompt: "Enter a list of stock tickers (e.g., BAC, MSFT, BA):");

dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithSubAgents/README.md

@@ -1,6 +1,6 @@
 # Harness Step 02 — SubAgents (Stock Price Research)
 
-This sample demonstrates how to use the **SubAgentsProvider** to delegate work from a parent agent to sub-agents.
+This sample demonstrates how to use the **SubAgentsProvider** to delegate work from a parent agent to sub-agents. Both agents use `HarnessAgent` for pre-configured function invocation, per-service-call persistence, and context-window compaction.
 
 ## What It Does
 

dotnet/samples/02-agents/Harness/Harness_Step03_DataProcessing/Harness_Step03_DataProcessing.csproj

@@ -13,6 +13,7 @@
   </ItemGroup>
 
   <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Harness\Microsoft.Agents.AI.Harness.csproj" />
     <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
     <ProjectReference Include="..\Harness_Shared_Console\Harness_Shared_Console.csproj" />
   </ItemGroup>

dotnet/samples/02-agents/Harness/Harness_Step03_DataProcessing/Program.cs

@@ -1,6 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-// This sample demonstrates how to use a ChatClientAgent with the FileAccessProvider
+// This sample demonstrates how to use a HarnessAgent with the FileAccessProvider
 // to give an agent access to a folder of CSV data files. The agent can read, analyze,
 // and extract information from the data, then write results back as new files.
 //
@@ -8,7 +8,7 @@
 // Ask the agent to analyze the data, produce summaries, or create new output files.
 //
 // Special commands:
-//   exit — End the session.
+//   /exit — End the session.
 
 #pragma warning disable OPENAI001 // Suppress experimental API warnings for Responses API usage.
 #pragma warning disable MAAI001  // Suppress experimental API warnings for Agents AI experiments.
@@ -17,7 +17,6 @@ using System.ClientModel.Primitives;
 using Azure.Identity;
 using Harness.Shared.Console;
 using Microsoft.Agents.AI;
-using Microsoft.Agents.AI.Compaction;
 using Microsoft.Extensions.AI;
 using OpenAI;
 using OpenAI.Responses;
@@ -57,11 +56,7 @@ var instructions =
     - Always explain what you learned and what you are going to do next between tool calls, so the user can follow along with your thought process.
     """;
 
-// Create a compaction strategy based on the model's context window.
-var compactionStrategy = new ContextWindowCompactionStrategy(
-    maxContextWindowTokens: MaxContextWindowTokens,
-    maxOutputTokens: MaxOutputTokens);
-
+// Create the chat client from the OpenAI provider.
 AIAgent agent =
     new OpenAIClient(
         new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"),
@@ -72,39 +67,22 @@ AIAgent agent =
         })
     .GetResponsesClient()
     .AsIChatClientWithStoredOutputDisabled(deploymentName)
-
-    .AsBuilder()
-    .UseFunctionInvocation()
-    .UsePerServiceCallChatHistoryPersistence()
-    .UseAIContextProviders(new CompactionProvider(compactionStrategy))
-
-    .BuildAIAgent(
-        new ChatClientAgentOptions
+    .AsHarnessAgent(MaxContextWindowTokens, MaxOutputTokens, new HarnessAgentOptions
+    {
+        Name = "DataAnalyst",
+        Description = "A data analyst assistant that reads, analyzes, and processes data files.",
+        AIContextProviders =
+        [
+            new FileAccessProvider(fileStore),
+        ],
+        ChatOptions = new ChatOptions
         {
-            Name = "DataAnalyst",
-            Description = "A data analyst assistant that reads, analyzes, and processes data files.",
-            UseProvidedChatClientAsIs = true,
-            RequirePerServiceCallChatHistoryPersistence = true,
-            ChatHistoryProvider = new InMemoryChatHistoryProvider(
-                new InMemoryChatHistoryProviderOptions
-                {
-                    ChatReducer = compactionStrategy.AsChatReducer(),
-                }),
-            AIContextProviders =
-            [
-                new FileAccessProvider(fileStore),
-            ],
-            ChatOptions = new ChatOptions
-            {
-                Instructions = instructions,
-                MaxOutputTokens = MaxOutputTokens,
-            },
-        })
-    .AsBuilder()
-    .Build();
+            Instructions = instructions,
+            MaxOutputTokens = MaxOutputTokens,
+        },
+    });
 
 // Run the interactive console session.
 await HarnessConsole.RunAgentAsync(
     agent,
-    title: "Data Processing Assistant",
     userPrompt: "Ask me to analyze the data files, produce summaries, or create output files.");

dotnet/samples/02-agents/Harness/Harness_Step03_DataProcessing/README.md

@@ -1,9 +1,10 @@
 # What this sample demonstrates
 
-This sample demonstrates how to use a `ChatClientAgent` with the `FileAccessProvider` to give an agent access to a folder of data files for reading, analyzing, and writing results.
+This sample demonstrates how to use a `HarnessAgent` with the `FileAccessProvider` to give an agent access to a folder of data files for reading, analyzing, and writing results. The `HarnessAgent` pre-configures function invocation, per-service-call chat history persistence, and in-loop compaction — so the sample only needs to supply the chat client, token limits, and application-specific options.
 
 Key features showcased:
 
+- **HarnessAgent** — a pre-configured agent that wraps a `ChatClientAgent` with function invocation, per-service-call persistence, and context-window compaction
 - **FileAccessProvider** — gives the agent tools to read, write, list, search, and delete files in a shared data folder
 - **CSV data processing** — the agent reads sales transaction data and performs analysis on demand
 - **Output file creation** — the agent can write summaries, filtered data, or reports back to the data folder

dotnet/samples/03-workflows/Declarative/InvokeFoundryToolboxMcp/InvokeFoundryToolboxMcp.csproj

@@ -0,0 +1,42 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
+    <InjectSharedFoundryAgents>true</InjectSharedFoundryAgents>
+    <InjectSharedWorkflowsExecution>true</InjectSharedWorkflowsExecution>
+    <InjectSharedWorkflowsSettings>true</InjectSharedWorkflowsSettings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" />
+    <PackageReference Include="Microsoft.Extensions.Configuration" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
+    <PackageReference Include="Microsoft.Extensions.Logging" />
+    <PackageReference Include="OpenAI" />
+    <PackageReference Include="System.ClientModel" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative\Microsoft.Agents.AI.Workflows.Declarative.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.Foundry\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.Mcp\Microsoft.Agents.AI.Workflows.Declarative.Mcp.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="InvokeFoundryToolboxMcp.yaml">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Declarative/InvokeFoundryToolboxMcp/InvokeFoundryToolboxMcp.yaml

@@ -0,0 +1,87 @@
+#
+# This workflow demonstrates invoking MCP tools through a Foundry toolbox MCP proxy.
+#
+# The toolbox is provisioned with TWO different tool types:
+#   1. A Foundry built-in web_search tool
+#   2. A Microsoft Learn MCP server (microsoft_docs)
+# Both are surfaced through the same MCP-compatible toolbox endpoint.
+#
+# The workflow:
+# 1. Accepts a documentation/web search query as input
+# 2. Lists the tools exposed by the Foundry toolbox using reserved toolName: tools/list
+# 3. Invokes the microsoft_docs_search MCP tool
+# 4. Invokes the built-in web_search tool against the same toolbox endpoint
+# 5. Uses an agent to summarize and combine both result sets
+#
+# Example input:
+# How do I use Azure OpenAI with my data?
+#
+kind: Workflow
+trigger:
+
+  kind: OnConversationStart
+  id: workflow_invoke_foundry_toolbox_mcp
+  actions:
+
+    # Set the search query from user input.
+    - kind: SetVariable
+      id: set_search_query
+      variable: Local.SearchQuery
+      value: =System.LastMessage.Text
+
+    # List tools exposed by the Foundry toolbox MCP proxy.
+    - kind: InvokeMcpTool
+      id: list_toolbox_tools
+      serverUrl: =Env.FOUNDRY_TOOLBOX_MCP_SERVER_URL
+      serverLabel: foundry_toolbox
+      toolName: tools/list
+      conversationId: =System.ConversationId
+      headers:
+        Foundry-Features: Toolboxes=V1Preview
+      output:
+        autoSend: true
+        result: Local.ToolboxTools
+
+    # Invoke a specific tool exposed through the toolbox and add the result to the conversation.
+    - kind: InvokeMcpTool
+      id: search_docs_with_toolbox
+      serverUrl: =Env.FOUNDRY_TOOLBOX_MCP_SERVER_URL
+      serverLabel: foundry_toolbox
+      toolName: =Env.FOUNDRY_TOOLBOX_DOCS_SERVER_LABEL & "___microsoft_docs_search"
+      conversationId: =System.ConversationId
+      headers:
+        Foundry-Features: Toolboxes=V1Preview
+      arguments:
+        query: =Local.SearchQuery
+      output:
+        autoSend: true
+        result: Local.SearchResult
+
+    # Invoke the web_search built-in tool through the same toolbox proxy. The toolbox surfaces
+    # built-in Foundry tools (like web_search) alongside MCP tools through one MCP-compatible
+    # endpoint. Note that web_search expects argument 'search_query' (not 'query').
+    - kind: InvokeMcpTool
+      id: search_web_with_toolbox
+      serverUrl: =Env.FOUNDRY_TOOLBOX_MCP_SERVER_URL
+      serverLabel: foundry_toolbox
+      toolName: =Env.FOUNDRY_TOOLBOX_WEB_SEARCH_TOOL_NAME
+      conversationId: =System.ConversationId
+      headers:
+        Foundry-Features: Toolboxes=V1Preview
+      arguments:
+        search_query: =Local.SearchQuery
+      output:
+        autoSend: true
+        result: Local.WebSearchResult
+
+    # Use the agent to summarize what happened and answer from the toolbox result.
+    - kind: InvokeAzureAgent
+      id: summarize_toolbox_result
+      agent:
+        name: FoundryToolboxMcpAgent
+      conversationId: =System.ConversationId
+      input:
+        messages: =UserMessage("Combine the Microsoft Learn docs results and the Foundry web search results in the conversation to answer the query " & Local.SearchQuery)
+      output:
+        autoSend: true
+        messages: Local.Summary

dotnet/samples/03-workflows/Declarative/InvokeFoundryToolboxMcp/Program.cs

@@ -0,0 +1,218 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates using InvokeMcpTool to call MCP tools through a Foundry toolbox.
+// It creates a sample toolbox that exposes Microsoft Learn MCP tools, lists the toolbox tools
+// through the reserved tools/list operation, then calls microsoft_docs_search from the workflow.
+
+using System.ClientModel;
+using System.ClientModel.Primitives;
+using System.Collections.Concurrent;
+using System.Net.Http.Headers;
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Core;
+using Azure.Identity;
+using Microsoft.Agents.AI.Workflows.Declarative.Mcp;
+using Microsoft.Extensions.Configuration;
+using OpenAI.Responses;
+using Shared.Foundry;
+using Shared.Workflows;
+
+#pragma warning disable OPENAI001 // Experimental API
+#pragma warning disable AAIP001 // AgentToolboxes is experimental
+
+namespace Demo.Workflows.Declarative.InvokeFoundryToolboxMcp;
+
+/// <summary>
+/// Demonstrates a workflow that uses InvokeMcpTool to call MCP tools exposed through a Foundry toolbox.
+/// </summary>
+/// <remarks>
+/// This sample provisions a toolbox with Microsoft Learn MCP tools, uses the reserved
+/// <c>tools/list</c> tool name to list the toolbox tools, calls one specific toolbox tool,
+/// and has a Foundry agent summarize the results.
+/// </remarks>
+internal sealed class Program
+{
+    private const string ToolboxNameSetting = "FOUNDRY_TOOLBOX_NAME";
+    private const string ToolboxApiVersionSetting = "FOUNDRY_AGENT_TOOLSET_API_VERSION";
+    private const string ToolboxMcpServerUrlSetting = "FOUNDRY_TOOLBOX_MCP_SERVER_URL";
+    private const string DocsServerLabelSetting = "FOUNDRY_TOOLBOX_DOCS_SERVER_LABEL";
+    private const string WebSearchToolNameSetting = "FOUNDRY_TOOLBOX_WEB_SEARCH_TOOL_NAME";
+    private const string DefaultToolboxName = "declarative_foundry_toolbox_mcp";
+    private const string DefaultToolboxApiVersion = "v1";
+    private const string DefaultDocsServerLabel = "microsoft_docs";
+    private const string DefaultWebSearchToolName = "web_search";
+
+    public static async Task Main(string[] args)
+    {
+        // Initialize configuration
+        IConfiguration configuration = Application.InitializeConfig();
+        Uri foundryEndpoint = new(configuration.GetValue(Application.Settings.FoundryEndpoint));
+        string toolboxName = configuration[ToolboxNameSetting] ?? DefaultToolboxName;
+        string toolboxApiVersion = configuration[ToolboxApiVersionSetting] ?? DefaultToolboxApiVersion;
+        string docsServerLabel = configuration[DocsServerLabelSetting] ?? DefaultDocsServerLabel;
+        string webSearchToolName = configuration[WebSearchToolNameSetting] ?? DefaultWebSearchToolName;
+
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+        DefaultAzureCredential credential = new();
+
+        // Ensure sample toolbox and agent exist in Foundry
+        string toolboxEndpoint = await CreateSampleToolboxAsync(toolboxName, docsServerLabel, foundryEndpoint, credential);
+        string toolboxMcpServerUrl = BuildToolboxMcpServerUrl(toolboxEndpoint, toolboxName, toolboxApiVersion);
+        IConfiguration workflowConfiguration = new ConfigurationBuilder()
+            .AddConfiguration(configuration)
+            .AddInMemoryCollection(new Dictionary<string, string?>
+            {
+                [ToolboxMcpServerUrlSetting] = toolboxMcpServerUrl,
+                [DocsServerLabelSetting] = docsServerLabel,
+                [WebSearchToolNameSetting] = webSearchToolName,
+            })
+            .Build();
+
+        await CreateAgentAsync(foundryEndpoint, configuration, credential);
+
+        // Get input from command line or console
+        string workflowInput = Application.GetInput(args);
+
+        // Create the MCP tool handler for invoking the Foundry toolbox MCP proxy.
+        ConcurrentBag<HttpClient> createdHttpClients = [];
+        DefaultMcpToolHandler mcpToolHandler = new(
+            httpClientProvider: async (serverUrl, _) =>
+            {
+                await Task.CompletedTask.ConfigureAwait(false);
+
+                if (!string.Equals(serverUrl, toolboxMcpServerUrl, StringComparison.OrdinalIgnoreCase))
+                {
+                    return null;
+                }
+
+                FoundryToolboxBearerTokenHandler handler = new(credential)
+                {
+                    InnerHandler = new HttpClientHandler()
+                };
+                HttpClient httpClient = new(handler);
+                createdHttpClients.Add(httpClient);
+                return httpClient;
+            });
+
+        try
+        {
+            // Create the workflow factory with MCP tool provider
+            WorkflowFactory workflowFactory = new("InvokeFoundryToolboxMcp.yaml", foundryEndpoint)
+            {
+                Configuration = workflowConfiguration,
+                McpToolHandler = mcpToolHandler
+            };
+
+            // Execute the workflow
+            WorkflowRunner runner = new() { UseJsonCheckpoints = true };
+            await runner.ExecuteAsync(workflowFactory.CreateWorkflow, workflowInput);
+        }
+        finally
+        {
+            // Clean up connections and dispose created HttpClients
+            await mcpToolHandler.DisposeAsync();
+
+            foreach (HttpClient httpClient in createdHttpClients)
+            {
+                httpClient.Dispose();
+            }
+        }
+    }
+
+    private static async Task CreateAgentAsync(Uri foundryEndpoint, IConfiguration configuration, TokenCredential credential)
+    {
+        AIProjectClient aiProjectClient = new(foundryEndpoint, credential);
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "FoundryToolboxMcpAgent",
+            agentDefinition: DefineToolboxAgent(configuration),
+            agentDescription: "Summarizes Foundry toolbox MCP tool results");
+    }
+
+    private static DeclarativeAgentDefinition DefineToolboxAgent(IConfiguration configuration)
+    {
+        return new DeclarativeAgentDefinition(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                You are a helpful assistant that explains results produced by tools exposed through a Foundry toolbox.
+                The conversation history contains output from BOTH a Microsoft Learn documentation search (MCP) and a Foundry web search.
+                Synthesize an answer that draws on both sources, calls out where they agree or differ, and notes which toolbox tool produced each fact when it is relevant.
+                Be concise.
+                """
+        };
+    }
+
+    private static async Task<string> CreateSampleToolboxAsync(string name, string serverLabel, Uri foundryEndpoint, TokenCredential credential)
+    {
+        AgentAdministrationClientOptions options = new();
+        options.AddPolicy(new FoundryFeaturesPolicy("Toolboxes=V1Preview"), PipelinePosition.PerCall);
+        AgentAdministrationClient adminClient = new(foundryEndpoint, credential, options);
+        AgentToolboxes toolboxClient = adminClient.GetAgentToolboxes();
+
+        try
+        {
+            await toolboxClient.DeleteToolboxAsync(name);
+            Console.WriteLine($"Deleted existing toolbox '{name}'");
+        }
+        catch (ClientResultException ex) when (ex.Status == 404)
+        {
+            // Toolbox does not exist.
+        }
+
+        ProjectsAgentTool webTool = ProjectsAgentTool.AsProjectTool(ResponseTool.CreateWebSearchTool());
+
+        ProjectsAgentTool mcpTool = ProjectsAgentTool.AsProjectTool(ResponseTool.CreateMcpTool(
+            serverLabel: serverLabel,
+            serverUri: new Uri("https://learn.microsoft.com/api/mcp"),
+            toolCallApprovalPolicy: new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.NeverRequireApproval)));
+
+        ToolboxVersion created = (await toolboxClient.CreateToolboxVersionAsync(
+            name: name,
+            tools: [webTool, mcpTool],
+            description: "Sample toolbox combining Foundry web search with the Microsoft Learn MCP tools for the declarative InvokeFoundryToolboxMcp sample.")).Value;
+
+        Console.WriteLine($"Created toolbox '{created.Name}' v{created.Version} ({created.Tools.Count} tool(s))");
+
+        return $"{foundryEndpoint.ToString().TrimEnd('/')}/toolboxes";
+    }
+
+    private static string BuildToolboxMcpServerUrl(string toolboxEndpoint, string toolboxName, string apiVersion) =>
+        $"{toolboxEndpoint.TrimEnd('/')}/{toolboxName}/mcp?api-version={Uri.EscapeDataString(apiVersion)}";
+
+    private sealed class FoundryToolboxBearerTokenHandler(TokenCredential credential) : DelegatingHandler
+    {
+        private static readonly TokenRequestContext s_tokenContext =
+            new(["https://ai.azure.com/.default"]);
+
+        protected override async Task<HttpResponseMessage> SendAsync(
+            HttpRequestMessage request,
+            CancellationToken cancellationToken)
+        {
+            AccessToken token = await credential.GetTokenAsync(s_tokenContext, cancellationToken);
+            request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token.Token);
+
+            return await base.SendAsync(request, cancellationToken);
+        }
+    }
+
+    private sealed class FoundryFeaturesPolicy(string feature) : PipelinePolicy
+    {
+        private const string FeatureHeader = "Foundry-Features";
+
+        public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+        {
+            message.Request.Headers.Add(FeatureHeader, feature);
+            ProcessNext(message, pipeline, currentIndex);
+        }
+
+        public override ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+        {
+            message.Request.Headers.Add(FeatureHeader, feature);
+            return ProcessNextAsync(message, pipeline, currentIndex);
+        }
+    }
+}

dotnet/samples/03-workflows/Evaluation/Evaluation_WorkflowExpectedOutputs/Evaluation_WorkflowExpectedOutputs.csproj

@@ -0,0 +1,16 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Evaluation/Evaluation_WorkflowExpectedOutputs/Program.cs

@@ -0,0 +1,76 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates evaluating a multi-agent workflow against a
+// golden answer using Foundry's reference-based Similarity evaluator.
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+using FoundryEvals = Microsoft.Agents.AI.Foundry.FoundryEvals;
+
+string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
+
+// Build a two-agent workflow: a researcher writes a draft answer, then an
+// editor polishes it into the final response that we compare to ground truth.
+// EmitAgentResponseEvents is enabled so the workflow surfaces an AgentResponseEvent
+// for each agent — this is what EvaluateAsync uses to find the overall final answer.
+var hostOptions = new AIAgentHostOptions { EmitAgentResponseEvents = true };
+
+AIAgent researcher = projectClient.AsAIAgent(
+    model: deploymentName,
+    instructions: "You research questions and produce a short factual draft answer.",
+    name: "researcher");
+
+AIAgent editor = projectClient.AsAIAgent(
+    model: deploymentName,
+    instructions: "You take a draft answer and produce the final concise response.",
+    name: "editor");
+
+ExecutorBinding researcherExecutor = researcher.BindAsExecutor(hostOptions);
+ExecutorBinding editorExecutor = editor.BindAsExecutor(hostOptions);
+
+Workflow workflow = new WorkflowBuilder(researcherExecutor)
+    .AddEdge(researcherExecutor, editorExecutor)
+    .Build();
+
+// Run the workflow against the user question.
+const string Query = "What is the capital of France?";
+const string GroundTruth = "Paris";
+
+await using Run run = await InProcessExecution.RunAsync(
+    workflow,
+    new ChatMessage(ChatRole.User, Query));
+
+// Evaluate the overall workflow output against a golden answer using the
+// reference-based Similarity evaluator. The 'expectedOutput' value is stamped
+// onto the overall EvalItem.ExpectedOutput and is surfaced to Foundry as
+// `ground_truth` in the underlying JSONL payload.
+//
+// Per-agent breakdown is disabled here: ground truth applies to the workflow's
+// final answer, not to each sub-agent's intermediate output. Without
+// includePerAgent: false, the evaluator would be invoked for per-agent items
+// (which have no ExpectedOutput) and Similarity would fail validation.
+FoundryEvals similarity = new(projectClient, deploymentName, FoundryEvals.Similarity);
+
+AgentEvaluationResults results = await run.EvaluateAsync(
+    similarity,
+    includePerAgent: false,
+    expectedOutput: GroundTruth);
+
+Console.WriteLine($"Query: {Query}");
+Console.WriteLine($"Expected: {GroundTruth}");
+Console.WriteLine($"Provider: {results.ProviderName}");
+Console.WriteLine($"Passed: {results.Passed}/{results.Total}");
+if (results.ReportUrl is not null)
+{
+    Console.WriteLine($"Report: {results.ReportUrl}");
+}

dotnet/samples/03-workflows/Evaluation/Evaluation_WorkflowExpectedOutputs/README.md

@@ -0,0 +1,37 @@
+# Evaluation - Workflow Expected Outputs
+
+This sample demonstrates evaluating a multi-agent workflow's final answer
+against a golden expected output using Foundry's reference-based **Similarity**
+evaluator.
+
+## What this sample demonstrates
+
+- Building a small researcher → editor workflow
+- Running the workflow and obtaining a `Run`
+- Calling `run.EvaluateAsync(evaluator, expectedOutput: ...)` to attach a
+  ground-truth answer to the overall workflow item
+- Using `FoundryEvals.Similarity`, which requires a `ground_truth` value
+  per item
+
+The `expectedOutput` value is stamped onto the overall `EvalItem.ExpectedOutput`
+and is surfaced to Foundry as `ground_truth` in the JSONL payload sent to the
+Evals API.
+
+## Prerequisites
+
+- .NET 10 SDK or later
+- Azure CLI installed and authenticated (`az login`)
+
+Set the following environment variables:
+
+```powershell
+$env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project"
+$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"
+```
+
+## Run the sample
+
+```powershell
+cd dotnet/samples/03-workflows/Evaluation
+dotnet run --project .\Evaluation_WorkflowExpectedOutputs
+```

dotnet/samples/05-end-to-end/AgentWebChat/AgentWebChat.AgentHost/Program.cs

@@ -163,10 +163,22 @@ app.MapA2AHttpJson(knightsKnavesAgentBuilder, path: "/a2a/knights-and-knaves");
 app.MapDevUI();
 
 app.MapOpenAIResponses();
+app.MapOpenAIResponses(pirateAgentBuilder);
+app.MapOpenAIResponses(knightsKnavesAgentBuilder);
+app.MapOpenAIResponses(chemistryAgent);
+app.MapOpenAIResponses(mathsAgent);
+app.MapOpenAIResponses(literatureAgent);
+app.MapOpenAIResponses(scienceSequentialWorkflow);
+app.MapOpenAIResponses(scienceConcurrentWorkflow);
 app.MapOpenAIConversations();
 
 app.MapOpenAIChatCompletions(pirateAgentBuilder);
 app.MapOpenAIChatCompletions(knightsKnavesAgentBuilder);
+app.MapOpenAIChatCompletions(chemistryAgent);
+app.MapOpenAIChatCompletions(mathsAgent);
+app.MapOpenAIChatCompletions(literatureAgent);
+app.MapOpenAIChatCompletions(scienceSequentialWorkflow);
+app.MapOpenAIChatCompletions(scienceConcurrentWorkflow);
 
 // Map the agents HTTP endpoints
 app.MapAgentDiscovery("/agents");

dotnet/samples/05-end-to-end/AgentWebChat/AgentWebChat.Web/OpenAIChatCompletionsAgentClient.cs

@@ -24,7 +24,7 @@ internal sealed class OpenAIChatCompletionsAgentClient(HttpClient httpClient) :
     {
         OpenAIClientOptions options = new()
         {
-            Endpoint = new Uri(httpClient.BaseAddress!, $"/{agentName}/v1/"),
+            Endpoint = new Uri(httpClient.BaseAddress!, $"/{Uri.EscapeDataString(agentName)}/v1/"),
             Transport = new HttpClientPipelineTransport(httpClient)
         };
 

dotnet/samples/05-end-to-end/AgentWebChat/AgentWebChat.Web/OpenAIResponsesAgentClient.cs

@@ -23,7 +23,7 @@ internal sealed class OpenAIResponsesAgentClient(HttpClient httpClient) : AgentC
     {
         OpenAIClientOptions options = new()
         {
-            Endpoint = new Uri(httpClient.BaseAddress!, "/v1/"),
+            Endpoint = new Uri(httpClient.BaseAddress!, $"/{Uri.EscapeDataString(agentName)}/v1/"),
             Transport = new HttpClientPipelineTransport(httpClient)
         };
 

dotnet/src/Microsoft.Agents.AI.DevUI/DevUIAuthFilter.cs

@@ -51,9 +51,7 @@ internal sealed class DevUIAuthFilter : IEndpointFilter
 
         if (!isLoopback && !this._options.AllowRemoteAccess)
         {
-            this._logger.LogWarning(
-                "Rejected non-loopback DevUI request from {RemoteIp}. Set DevUIOptions.AllowRemoteAccess to permit remote callers.",
-                remoteIp);
+            DevUILog.RejectedNonLoopbackRequest(this._logger, remoteIp);
             return Results.Problem(
                 statusCode: StatusCodes.Status403Forbidden,
                 title: "DevUI access denied",

dotnet/src/Microsoft.Agents.AI.DevUI/DevUIExtensions.cs

@@ -100,10 +100,7 @@ public static class DevUIExtensions
 
         if (options.AllowRemoteAccess && !tokenConfigured && options.ConfigureEndpoints is null)
         {
-            logger.LogWarning(
-                "DevUI is configured with AllowRemoteAccess=true and no authentication. " +
-                "Set DevUIOptions.AuthToken, the {EnvVar} environment variable, or attach an authorization policy via ConfigureEndpoints.",
-                DevUIOptions.AuthTokenEnvironmentVariable);
+            DevUILog.InsecurelyExposed(logger, DevUIOptions.AuthTokenEnvironmentVariable);
         }
     }
 }

dotnet/src/Microsoft.Agents.AI.DevUI/DevUILog.cs

@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Net;
+
+namespace Microsoft.Agents.AI.DevUI;
+
+internal static partial class DevUILog
+{
+    [LoggerMessage(
+        EventId = 1,
+        Level = LogLevel.Warning,
+        Message = "Rejected non-loopback DevUI request from {RemoteIp}. Set DevUIOptions.AllowRemoteAccess to permit remote callers.")]
+    public static partial void RejectedNonLoopbackRequest(ILogger logger, IPAddress? remoteIp);
+
+    [LoggerMessage(
+        EventId = 2,
+        Level = LogLevel.Warning,
+        Message = "DevUI is configured with AllowRemoteAccess=true and no authentication. Set DevUIOptions.AuthToken, the {EnvVar} environment variable, or attach an authorization policy via ConfigureEndpoints.")]
+    public static partial void InsecurelyExposed(ILogger logger, string envVar);
+}

dotnet/src/Microsoft.Agents.AI.Foundry/Evaluation/FoundryEvalConverter.cs

@@ -130,6 +130,7 @@ internal static class FoundryEvalConverter
             QueryMessages = ConvertMessages(queryMessages),
             ResponseMessages = ConvertMessages(responseMessages),
             Context = item.Context,
+            GroundTruth = item.ExpectedOutput,
             ToolDefinitions = item.Tools is { Count: > 0 }
                 ? item.Tools
                     .OfType<AIFunction>()
@@ -185,6 +186,11 @@ internal static class FoundryEvalConverter
                     dataMapping["context"] = "{{item.context}}";
                 }
 
+                if (GroundTruthEvaluators.Contains(qualified))
+                {
+                    dataMapping["ground_truth"] = "{{item.ground_truth}}";
+                }
+
                 if (ToolEvaluators.Contains(qualified))
                 {
                     dataMapping["tool_definitions"] = "{{item.tool_definitions}}";
@@ -206,7 +212,7 @@ internal static class FoundryEvalConverter
     /// <summary>
     /// Builds the <c>item_schema</c> for custom JSONL eval definitions.
     /// </summary>
-    internal static WireItemSchema BuildItemSchema(bool hasContext = false, bool hasTools = false)
+    internal static WireItemSchema BuildItemSchema(bool hasContext = false, bool hasTools = false, bool hasGroundTruth = false)
     {
         var properties = new Dictionary<string, WireSchemaProperty>
         {
@@ -221,6 +227,11 @@ internal static class FoundryEvalConverter
             properties["context"] = new WireSchemaProperty { Type = "string" };
         }
 
+        if (hasGroundTruth)
+        {
+            properties["ground_truth"] = new WireSchemaProperty { Type = "string" };
+        }
+
         if (hasTools)
         {
             properties["tool_definitions"] = new WireSchemaProperty { Type = "array" };
@@ -233,6 +244,31 @@ internal static class FoundryEvalConverter
         };
     }
 
+    /// <summary>
+    /// Returns the subset of <paramref name="evaluators"/> that require a ground-truth
+    /// (reference) value but cannot be evaluated because no item provided one.
+    /// </summary>
+    internal static List<string> FindMissingGroundTruthEvaluators(
+        IEnumerable<string> evaluators,
+        bool hasGroundTruth)
+    {
+        if (hasGroundTruth)
+        {
+            return [];
+        }
+
+        var missing = new List<string>();
+        foreach (var name in evaluators)
+        {
+            if (GroundTruthEvaluators.Contains(ResolveEvaluator(name)))
+            {
+                missing.Add(name);
+            }
+        }
+
+        return missing;
+    }
+
     /// <summary>
     /// Resolves a short evaluator name to its fully-qualified <c>builtin.*</c> form.
     /// </summary>
@@ -277,6 +313,12 @@ internal static class FoundryEvalConverter
         "builtin.tool_call_success",
     };
 
+    // Evaluators that require a ground_truth (reference) value per item.
+    internal static readonly HashSet<string> GroundTruthEvaluators = new(StringComparer.OrdinalIgnoreCase)
+    {
+        "builtin.similarity",
+    };
+
     // Short name → fully-qualified name mapping.
     internal static readonly Dictionary<string, string> BuiltinEvaluators = new(StringComparer.OrdinalIgnoreCase)
     {

dotnet/src/Microsoft.Agents.AI.Foundry/Evaluation/FoundryEvalWireModels.cs

@@ -103,6 +103,9 @@ internal sealed class WireEvalItemPayload
     [JsonPropertyName("context")]
     public string? Context { get; init; }
 
+    [JsonPropertyName("ground_truth")]
+    public string? GroundTruth { get; init; }
+
     [JsonPropertyName("tool_definitions")]
     public List<WireToolDefinition>? ToolDefinitions { get; init; }
 }

dotnet/src/Microsoft.Agents.AI.Foundry/Evaluation/FoundryEvals.cs

@@ -145,6 +145,8 @@ public sealed class FoundryEvals : IAgentEvaluator
 
         bool hasContext = payloads.Any(p => p.Context is not null);
         bool hasTools = payloads.Any(p => p.ToolDefinitions is { Count: > 0 });
+        bool hasGroundTruth = payloads.Any(p => p.GroundTruth is not null);
+        bool allHaveGroundTruth = payloads.Count > 0 && payloads.All(p => p.GroundTruth is not null);
 
         // Filter out tool evaluators if no items have tools; auto-add ToolCallAccuracy if tools present
         var evaluators = FilterToolEvaluators(this._evaluatorNames, hasTools);
@@ -153,13 +155,27 @@ public sealed class FoundryEvals : IAgentEvaluator
             evaluators = [.. evaluators, ToolCallAccuracy];
         }
 
+        // Fail fast if a ground-truth evaluator (e.g. similarity) is requested but not
+        // every item carries an ExpectedOutput. Reference-based evaluators score each
+        // item against its own ground truth, so even one missing value will surface as
+        // a provider-side validation error. Catch it here with a clearer message.
+        var missingGroundTruth = FoundryEvalConverter.FindMissingGroundTruthEvaluators(evaluators, allHaveGroundTruth);
+        if (missingGroundTruth.Count > 0)
+        {
+            throw new InvalidOperationException(
+                "The following evaluator(s) require a ground-truth/expected output on every item but " +
+                $"at least one item is missing an {nameof(EvalItem.ExpectedOutput)}: {string.Join(", ", missingGroundTruth)}. " +
+                "Provide an expected output per item (for example via the 'expectedOutput' parameter on EvaluateAsync), " +
+                "or set 'includePerAgent: false' so the evaluator only runs on the overall item.");
+        }
+
         // 2. Create the evaluation definition
         var createEvalPayload = new WireCreateEvalRequest
         {
             Name = evalName,
             DataSourceConfig = new WireCustomDataSourceConfig
             {
-                ItemSchema = FoundryEvalConverter.BuildItemSchema(hasContext, hasTools),
+                ItemSchema = FoundryEvalConverter.BuildItemSchema(hasContext, hasTools, hasGroundTruth),
             },
             TestingCriteria = FoundryEvalConverter.BuildTestingCriteria(
                 evaluators, this._model, includeDataMapping: true),
@@ -822,15 +838,15 @@ public sealed class FoundryEvals : IAgentEvaluator
         var result = new EvalItemResult(itemId, status, scores);
 
         // Extract error info from sample
-        if (outputItem.TryGetProperty("sample", out var sample))
+        if (outputItem.TryGetProperty("sample", out var sample) && sample.ValueKind == JsonValueKind.Object)
         {
-            if (sample.TryGetProperty("error", out var errObj))
+            if (sample.TryGetProperty("error", out var errObj) && errObj.ValueKind == JsonValueKind.Object)
             {
                 result.ErrorCode = errObj.TryGetProperty("code", out var code) ? code.GetString() : null;
                 result.ErrorMessage = errObj.TryGetProperty("message", out var msg) ? msg.GetString() : null;
             }
 
-            if (sample.TryGetProperty("usage", out var usage) && usage.TryGetProperty("total_tokens", out var tt) && tt.ValueKind == JsonValueKind.Number)
+            if (sample.TryGetProperty("usage", out var usage) && usage.ValueKind == JsonValueKind.Object && usage.TryGetProperty("total_tokens", out var tt) && tt.ValueKind == JsonValueKind.Number)
             {
                 var tokenUsage = new Dictionary<string, int>();
                 if (usage.TryGetProperty("prompt_tokens", out var pt) && pt.ValueKind == JsonValueKind.Number)
@@ -886,7 +902,7 @@ public sealed class FoundryEvals : IAgentEvaluator
         }
 
         // Extract response_id from datasource_item
-        if (outputItem.TryGetProperty("datasource_item", out var dsItem))
+        if (outputItem.TryGetProperty("datasource_item", out var dsItem) && dsItem.ValueKind == JsonValueKind.Object)
         {
             if (dsItem.TryGetProperty("resp_id", out var respId))
             {

dotnet/src/Microsoft.Agents.AI.Harness/ChatClientHarnessExtensions.cs

@@ -0,0 +1,42 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Agents.AI;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Provides extension methods for creating a <see cref="HarnessAgent"/> from an <see cref="IChatClient"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public static class ChatClientHarnessExtensions
+{
+    /// <summary>
+    /// Creates a new <see cref="HarnessAgent"/> that wraps this <see cref="IChatClient"/> with a pre-configured
+    /// pipeline including function invocation, per-service-call chat history persistence, and in-loop compaction.
+    /// </summary>
+    /// <param name="chatClient">
+    /// The <see cref="IChatClient"/> that provides access to the underlying AI model.
+    /// </param>
+    /// <param name="maxContextWindowTokens">
+    /// The maximum number of tokens the model's context window supports (e.g., 1,050,000 for gpt-5.4).
+    /// Used to configure the compaction strategy.
+    /// </param>
+    /// <param name="maxOutputTokens">
+    /// The maximum number of output tokens the model can generate per response (e.g., 128,000 for gpt-5.4).
+    /// Used to configure the compaction strategy.
+    /// </param>
+    /// <param name="options">
+    /// Optional configuration options for the agent, including instructions override, tools,
+    /// additional context providers, and chat history provider.
+    /// When <see langword="null"/>, the agent uses built-in default settings.
+    /// </param>
+    /// <returns>A new <see cref="HarnessAgent"/> instance.</returns>
+    public static HarnessAgent AsHarnessAgent(
+        this IChatClient chatClient,
+        int maxContextWindowTokens,
+        int maxOutputTokens,
+        HarnessAgentOptions? options = null) =>
+        new(chatClient, maxContextWindowTokens, maxOutputTokens, options);
+}

dotnet/src/Microsoft.Agents.AI.Harness/HarnessAgent.cs

@@ -0,0 +1,137 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Agents.AI.Compaction;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// A pre-configured <see cref="DelegatingAIAgent"/> that wraps a <see cref="ChatClientAgent"/> with
+/// function invocation, per-service-call chat history persistence, and in-loop compaction.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <see cref="HarnessAgent"/> assembles the following pipeline from a caller-supplied <see cref="IChatClient"/>:
+/// <list type="number">
+/// <item><description><see cref="FunctionInvokingChatClient"/> — automatic function/tool invocation.</description></item>
+/// <item><description><see cref="MessageInjectingChatClient"/> — allows external code to inject messages into the conversation mid-stream.</description></item>
+/// <item><description><see cref="PerServiceCallChatHistoryPersistingChatClient"/> — persists chat history after every individual service call within a function-invocation loop.</description></item>
+/// <item><description><see cref="AIContextProviderChatClient"/> with a <see cref="CompactionProvider"/> — applies context-window compaction before each call so long function-invocation loops do not overflow the context window.</description></item>
+/// </list>
+/// </para>
+/// <para>
+/// The underlying <see cref="ChatClientAgent"/> is configured with
+/// <see cref="ChatClientAgentOptions.UseProvidedChatClientAsIs"/> and
+/// <see cref="ChatClientAgentOptions.RequirePerServiceCallChatHistoryPersistence"/> set to <see langword="true"/>
+/// to match the manually-assembled pipeline.
+/// </para>
+/// <para>
+/// When no <see cref="HarnessAgentOptions.ChatHistoryProvider"/> is supplied, the agent defaults to an
+/// <see cref="InMemoryChatHistoryProvider"/> whose chat reducer applies the same compaction strategy,
+/// keeping in-memory history from growing unboundedly across sessions.
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class HarnessAgent : DelegatingAIAgent
+{
+    /// <summary>
+    /// The built-in default system instructions used when <see cref="ChatOptions.Instructions"/> is not set.
+    /// </summary>
+    public const string DefaultInstructions =
+        """
+        You are a helpful AI assistant that uses tools to complete tasks.
+
+        ## General guidelines
+
+        - Think through the task before acting. Break complex work into clear steps.
+        - Use the tools available to you to gather information, perform actions, and verify results.
+        - Explain your reasoning between tool calls so the user can follow your progress.
+        - If a tool call fails or returns unexpected results, adapt your approach rather than repeating the same call.
+        - When you have completed the task, present a clear and concise summary of what you did and what you found.
+        """;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="HarnessAgent"/> class.
+    /// </summary>
+    /// <param name="chatClient">
+    /// The <see cref="IChatClient"/> that provides access to the underlying AI model.
+    /// The agent wraps this client in a function-invocation, per-service-call persistence,
+    /// and compaction pipeline automatically.
+    /// </param>
+    /// <param name="maxContextWindowTokens">
+    /// The maximum number of tokens the model's context window supports (e.g., 1,050,000 for gpt-5.4).
+    /// Used to configure the compaction strategy.
+    /// </param>
+    /// <param name="maxOutputTokens">
+    /// The maximum number of output tokens the model can generate per response (e.g., 128,000 for gpt-5.4).
+    /// Used to configure the compaction strategy and to limit the model's output.
+    /// </param>
+    /// <param name="options">
+    /// Optional configuration options for the agent, including instructions override, tools,
+    /// additional context providers, and chat history provider.
+    /// When <see langword="null"/>, the agent uses built-in default settings.
+    /// </param>
+    /// <exception cref="System.ArgumentNullException">
+    /// <paramref name="chatClient"/> is <see langword="null"/>.
+    /// </exception>
+    /// <exception cref="System.ArgumentOutOfRangeException">
+    /// <paramref name="maxContextWindowTokens"/> is not positive, or
+    /// <paramref name="maxOutputTokens"/> is negative or greater than or equal to <paramref name="maxContextWindowTokens"/>.
+    /// </exception>
+    public HarnessAgent(IChatClient chatClient, int maxContextWindowTokens, int maxOutputTokens, HarnessAgentOptions? options = null)
+        : base(BuildInnerAgent(
+            Throw.IfNull(chatClient),
+            maxContextWindowTokens,
+            maxOutputTokens,
+            options))
+    {
+    }
+
+    private static ChatClientAgent BuildInnerAgent(IChatClient chatClient, int maxContextWindowTokens, int maxOutputTokens, HarnessAgentOptions? options)
+    {
+        var compactionStrategy = new ContextWindowCompactionStrategy(
+            maxContextWindowTokens: maxContextWindowTokens,
+            maxOutputTokens: maxOutputTokens);
+
+        ChatHistoryProvider chatHistoryProvider = options?.ChatHistoryProvider
+            ?? new InMemoryChatHistoryProvider(new InMemoryChatHistoryProviderOptions
+            {
+                ChatReducer = compactionStrategy.AsChatReducer(),
+            });
+
+        string instructions = options?.ChatOptions?.Instructions ?? DefaultInstructions;
+
+        ChatOptions chatOptions = BuildChatOptions(options?.ChatOptions, instructions, maxOutputTokens);
+
+        var compactionProvider = new CompactionProvider(compactionStrategy);
+
+        return chatClient
+            .AsBuilder()
+            .UseFunctionInvocation()
+            .UseMessageInjection()
+            .UsePerServiceCallChatHistoryPersistence()
+            .UseAIContextProviders(compactionProvider)
+            .BuildAIAgent(new ChatClientAgentOptions
+            {
+                Id = options?.Id,
+                Name = options?.Name,
+                Description = options?.Description,
+                ChatOptions = chatOptions,
+                ChatHistoryProvider = chatHistoryProvider,
+                AIContextProviders = options?.AIContextProviders,
+                UseProvidedChatClientAsIs = true,
+                RequirePerServiceCallChatHistoryPersistence = true,
+            });
+    }
+
+    private static ChatOptions BuildChatOptions(ChatOptions? source, string instructions, int maxOutputTokens)
+    {
+        ChatOptions result = source?.Clone() ?? new ChatOptions();
+        result.Instructions = instructions;
+        result.MaxOutputTokens ??= maxOutputTokens;
+        return result;
+    }
+}

dotnet/src/Microsoft.Agents.AI.Harness/HarnessAgentOptions.cs

@@ -0,0 +1,64 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents configuration options for a <see cref="HarnessAgent"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class HarnessAgentOptions
+{
+    /// <summary>
+    /// Gets or sets the agent id.
+    /// </summary>
+    public string? Id { get; set; }
+
+    /// <summary>
+    /// Gets or sets the agent name.
+    /// </summary>
+    public string? Name { get; set; }
+
+    /// <summary>
+    /// Gets or sets the agent description.
+    /// </summary>
+    public string? Description { get; set; }
+
+    /// <summary>
+    /// Gets or sets additional chat options such as tools for the agent to use.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Use <see cref="ChatOptions.Tools"/> to supply additional tools the agent can invoke.
+    /// </para>
+    /// <para>
+    /// Use <see cref="ChatOptions.Instructions"/> to override the <see cref="HarnessAgent"/>'s built-in
+    /// default instructions. When <see cref="ChatOptions.Instructions"/> is <see langword="null"/> or not set,
+    /// the default instructions are used.
+    /// </para>
+    /// </remarks>
+    public ChatOptions? ChatOptions { get; set; }
+
+    /// <summary>
+    /// Gets or sets the <see cref="ChatHistoryProvider"/> to use for storing chat history.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="null"/>, the agent defaults to an <see cref="InMemoryChatHistoryProvider"/>
+    /// configured with a compaction-based chat reducer derived from the <c>maxContextWindowTokens</c>
+    /// and <c>maxOutputTokens</c> constructor parameters of <see cref="HarnessAgent"/>.
+    /// </remarks>
+    public ChatHistoryProvider? ChatHistoryProvider { get; set; }
+
+    /// <summary>
+    /// Gets or sets additional <see cref="AIContextProvider"/> instances to include in the agent pipeline.
+    /// </summary>
+    /// <remarks>
+    /// These providers are passed to the underlying <see cref="ChatClientAgent"/> via
+    /// <see cref="ChatClientAgentOptions.AIContextProviders"/>.
+    /// </remarks>
+    public IEnumerable<AIContextProvider>? AIContextProviders { get; set; }
+}

dotnet/src/Microsoft.Agents.AI.Harness/Microsoft.Agents.AI.Harness.csproj

@@ -0,0 +1,28 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <IsReleaseCandidate>false</IsReleaseCandidate>
+    <InjectSharedThrow>true</InjectSharedThrow>
+    <InjectSharedDiagnosticIds>true</InjectSharedDiagnosticIds>
+    <InjectExperimentalAttributeOnLegacy>true</InjectExperimentalAttributeOnLegacy>
+    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
+    <InjectTrimAttributesOnLegacy>true</InjectTrimAttributesOnLegacy>
+  </PropertyGroup>
+
+  <Import Project="$(RepoRoot)/dotnet/nuget/nuget-package.props" />
+
+  <ItemGroup>
+    <ProjectReference Include="..\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+  </ItemGroup>
+
+  <PropertyGroup>
+    <!-- NuGet Package Settings -->
+    <Title>Microsoft Agent Framework Harness</Title>
+    <Description>Provides the HarnessAgent, a pre-configured AI agent that can be used for long running tasks.</Description>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <InternalsVisibleTo Include="Microsoft.Agents.AI.Harness.UnitTests" />
+  </ItemGroup>
+
+</Project>

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative.Mcp/DefaultMcpToolHandler.cs

@@ -3,12 +3,15 @@
 using System;
 using System.Collections.Generic;
 using System.Globalization;
+using System.IO;
 using System.Linq;
 using System.Net.Http;
 using System.Text;
+using System.Text.Json;
 using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.Extensions.AI;
+using Microsoft.Shared.Diagnostics;
 using ModelContextProtocol.Client;
 using ModelContextProtocol.Protocol;
 
@@ -24,6 +27,14 @@ namespace Microsoft.Agents.AI.Workflows.Declarative.Mcp;
 /// </remarks>
 public sealed class DefaultMcpToolHandler : IMcpToolHandler, IAsyncDisposable
 {
+    /// <summary>
+    /// Reserved <c>toolName</c> value that maps an <see cref="IMcpToolHandler.InvokeToolAsync"/> request
+    /// to the MCP protocol <c>tools/list</c> discovery operation.
+    /// </summary>
+    public const string ListToolsToolName = "tools/list";
+
+    private static readonly JsonWriterOptions s_toolListJsonWriterOptions = new() { Indented = true };
+
     private readonly Func<string, CancellationToken, Task<HttpClient?>>? _httpClientProvider;
     private readonly Dictionary<string, McpClient> _clients = [];
     private readonly Dictionary<string, HttpClient> _ownedHttpClients = [];
@@ -53,9 +64,18 @@ public sealed class DefaultMcpToolHandler : IMcpToolHandler, IAsyncDisposable
         CancellationToken cancellationToken = default)
     {
         // TODO: Handle connectionName and server label appropriately when Hosted scenario supports them. For now, ignore
-        McpServerToolResultContent resultContent = new(Guid.NewGuid().ToString());
+        if (IsListToolsToolName(toolName))
+        {
+            ThrowIfListToolsArgumentsSpecified(arguments);
+            McpClient listToolsClient = await this.GetOrCreateClientAsync(serverUrl, serverLabel, headers, cancellationToken).ConfigureAwait(false);
+            IList<McpClientTool> tools = await listToolsClient.ListToolsAsync(cancellationToken: cancellationToken).ConfigureAwait(false);
+            return CreateListToolsResultContent(tools.Select(tool => tool.ProtocolTool));
+        }
+
         McpClient client = await this.GetOrCreateClientAsync(serverUrl, serverLabel, headers, cancellationToken).ConfigureAwait(false);
 
+        McpServerToolResultContent resultContent = new(Guid.NewGuid().ToString());
+
         // Convert IDictionary to IReadOnlyDictionary for CallToolAsync
         IReadOnlyDictionary<string, object?>? readOnlyArguments = arguments is null
             ? null
@@ -72,6 +92,23 @@ public sealed class DefaultMcpToolHandler : IMcpToolHandler, IAsyncDisposable
         return resultContent;
     }
 
+    internal static bool IsListToolsToolName(string toolName) =>
+        string.Equals(toolName, ListToolsToolName, StringComparison.Ordinal);
+
+    internal static McpServerToolResultContent CreateListToolsResultContent(IEnumerable<Tool> tools)
+    {
+        Throw.IfNull(tools);
+
+        McpServerToolResultContent resultContent = new(Guid.NewGuid().ToString())
+        {
+            Outputs = []
+        };
+
+        resultContent.Outputs.Add(new TextContent(SerializeToolsList(tools)));
+
+        return resultContent;
+    }
+
     /// <inheritdoc/>
     public async ValueTask DisposeAsync()
     {
@@ -183,6 +220,16 @@ public sealed class DefaultMcpToolHandler : IMcpToolHandler, IAsyncDisposable
         return hashCode.ToString(CultureInfo.InvariantCulture);
     }
 
+    private static void ThrowIfListToolsArgumentsSpecified(IDictionary<string, object?>? arguments)
+    {
+        if (arguments is { Count: > 0 })
+        {
+            throw new ArgumentException(
+                $"The reserved MCP '{ListToolsToolName}' operation does not accept tool arguments.",
+                nameof(arguments));
+        }
+    }
+
     private static void PopulateResultContent(McpServerToolResultContent resultContent, CallToolResult result)
     {
         // Ensure Outputs list is initialized
@@ -230,6 +277,17 @@ public sealed class DefaultMcpToolHandler : IMcpToolHandler, IAsyncDisposable
             TextContentBlock text => new TextContent(text.Text),
             ImageContentBlock image => CreateDataContent(image.Data, image.MimeType ?? "image/*"),
             AudioContentBlock audio => CreateDataContent(audio.Data, audio.MimeType ?? "audio/*"),
+            EmbeddedResourceBlock embedded => ConvertEmbeddedResource(embedded),
+            _ => new TextContent(block.ToString() ?? string.Empty),
+        };
+    }
+
+    private static AIContent ConvertEmbeddedResource(EmbeddedResourceBlock block)
+    {
+        return block.Resource switch
+        {
+            TextResourceContents text => new TextContent(text.Text),
+            BlobResourceContents blob => CreateDataContent(blob.Blob, blob.MimeType ?? "application/octet-stream"),
             _ => new TextContent(block.ToString() ?? string.Empty),
         };
     }
@@ -255,4 +313,39 @@ public sealed class DefaultMcpToolHandler : IMcpToolHandler, IAsyncDisposable
 
         return new DataContent($"data:{mediaType};base64,{base64}", mediaType);
     }
+
+    private static string SerializeToolsList(IEnumerable<Tool> tools)
+    {
+        using MemoryStream stream = new();
+        using (Utf8JsonWriter writer = new(stream, s_toolListJsonWriterOptions))
+        {
+            writer.WriteStartObject();
+            writer.WriteStartArray("tools");
+
+            foreach (Tool tool in tools)
+            {
+                writer.WriteStartObject();
+                writer.WriteString("name", tool.Name);
+                writer.WriteString("description", tool.Description);
+                writer.WritePropertyName("inputSchema");
+                tool.InputSchema.WriteTo(writer);
+                writer.WritePropertyName("outputSchema");
+                if (tool.OutputSchema is JsonElement outputSchema)
+                {
+                    outputSchema.WriteTo(writer);
+                }
+                else
+                {
+                    writer.WriteNullValue();
+                }
+
+                writer.WriteEndObject();
+            }
+
+            writer.WriteEndArray();
+            writer.WriteEndObject();
+        }
+
+        return Encoding.UTF8.GetString(stream.GetBuffer(), 0, (int)stream.Length);
+    }
 }

dotnet/src/Microsoft.Agents.AI.Workflows/AIAgentsAbstractionsExtensions.cs

@@ -32,38 +32,8 @@ internal static class AIAgentsAbstractionsExtensions
         return message;
     }
 
-    /// <summary>
-    /// Iterates through <paramref name="messages"/> looking for <see cref="ChatRole.Assistant"/> messages and swapping
-    /// any that have a different <see cref="ChatMessage.AuthorName"/> from <paramref name="targetAgentName"/> to
-    /// <see cref="ChatRole.User"/>.
-    /// </summary>
-    public static List<ChatMessage>? ChangeAssistantToUserForOtherParticipants(this IEnumerable<ChatMessage> messages, string targetAgentName)
-    {
-        List<ChatMessage>? roleChanged = null;
-        foreach (var m in messages)
-        {
-            m.ChatAssistantToUserIfNotFromNamed(targetAgentName, out bool changed);
-            if (changed)
-            {
-                (roleChanged ??= []).Add(m);
-            }
-        }
-
-        return roleChanged;
-    }
-
-    /// <summary>
-    /// Undoes changes made by <see cref="ChangeAssistantToUserForOtherParticipants"/> when passed the list of changes
-    /// made by that method.
-    /// </summary>
-    public static void ResetUserToAssistantForChangedRoles(this List<ChatMessage>? roleChanged)
-    {
-        if (roleChanged is not null)
-        {
-            foreach (var m in roleChanged)
-            {
-                m.Role = ChatRole.Assistant;
-            }
-        }
-    }
+    public static List<ChatMessage> CopyWithAssistantToUserForOtherParticipants(
+        this IEnumerable<ChatMessage> messages,
+        string targetAgentName)
+        => messages.Select(m => m.ChatAssistantToUserIfNotFromNamed(targetAgentName, out _, false)).ToList();
 }

dotnet/src/Microsoft.Agents.AI.Workflows/Evaluation/WorkflowEvaluationExtensions.cs

@@ -28,6 +28,17 @@ public static class WorkflowEvaluationExtensions
     /// Use <see cref="ConversationSplitters.LastTurn"/>, <see cref="ConversationSplitters.Full"/>,
     /// or a custom <see cref="IConversationSplitter"/> implementation.
     /// </param>
+    /// <param name="expectedOutput">
+    /// Optional ground-truth/expected output for the workflow's overall final answer.
+    /// When provided, it is stamped onto the overall <see cref="EvalItem.ExpectedOutput"/>
+    /// so reference-based evaluators (for example, similarity) can compare the
+    /// workflow's response against a golden answer. Ground truth is only applied
+    /// to the overall item; per-agent items are intentionally left without an
+    /// expected output, since ground truth is defined against the final response.
+    /// When using a reference-based evaluator that requires ground truth, set
+    /// <paramref name="includePerAgent"/> to <see langword="false"/> to avoid
+    /// invoking the evaluator on per-agent items that have no expected output.
+    /// </param>
     /// <param name="cancellationToken">Cancellation token.</param>
     /// <returns>Evaluation results with optional per-agent sub-results.</returns>
     public static async Task<AgentEvaluationResults> EvaluateAsync(
@@ -37,6 +48,7 @@ public static class WorkflowEvaluationExtensions
         bool includePerAgent = true,
         string evalName = "Workflow Eval",
         IConversationSplitter? splitter = null,
+        string? expectedOutput = null,
         CancellationToken cancellationToken = default)
     {
         var events = run.OutgoingEvents.ToList();
@@ -48,28 +60,26 @@ public static class WorkflowEvaluationExtensions
         var overallItems = new List<EvalItem>();
         if (includeOverall)
         {
-            var finalResponse = events.OfType<AgentResponseEvent>().LastOrDefault();
-            if (finalResponse is not null)
+            var overallItem = BuildOverallItem(events, splitter, expectedOutput);
+            if (overallItem is not null)
             {
-                var firstInvoked = events.OfType<ExecutorInvokedEvent>().FirstOrDefault();
-                var query = firstInvoked?.Data switch
-                {
-                    ChatMessage cm => cm.Text ?? string.Empty,
-                    IReadOnlyList<ChatMessage> msgs => msgs.LastOrDefault(m => m.Role == ChatRole.User)?.Text ?? string.Empty,
-                    string s => s,
-                    _ => firstInvoked?.Data?.ToString() ?? string.Empty,
-                };
-                var conversation = new List<ChatMessage>
-                {
-                    new(ChatRole.User, query),
-                };
-
-                conversation.AddRange(finalResponse.Response.Messages);
-
-                overallItems.Add(new EvalItem(query, finalResponse.Response.Text, conversation)
-                {
-                    Splitter = splitter,
-                });
+                overallItems.Add(overallItem);
+            }
+            else
+            {
+                // The caller asked for an overall evaluation but we couldn't find a final
+                // response to score — almost always because the workflow's agents weren't
+                // built with EmitAgentResponseEvents enabled (so no AgentResponseEvent was
+                // emitted) and no terminal ExecutorCompletedEvent carried an AgentResponse
+                // / ChatMessage / string payload. Fail loudly instead of silently returning
+                // 0/0 (or skipping evaluation against a supplied expectedOutput).
+                throw new InvalidOperationException(
+                    "Cannot evaluate the overall workflow output: no AgentResponseEvent or " +
+                    "ExecutorCompletedEvent with an AgentResponse/ChatMessage/string payload " +
+                    "was found in the run. Bind agents with " +
+                    "AIAgentHostOptions { EmitAgentResponseEvents = true } " +
+                    "(for example via agent.BindAsExecutor(new AIAgentHostOptions { EmitAgentResponseEvents = true })) " +
+                    "so the workflow surfaces the final agent response, or set 'includeOverall: false'.");
             }
         }
 
@@ -97,6 +107,86 @@ public static class WorkflowEvaluationExtensions
         return overallResult;
     }
 
+    internal static EvalItem? BuildOverallItem(
+        IReadOnlyList<WorkflowEvent> events,
+        IConversationSplitter? splitter,
+        string? expectedOutput)
+    {
+        var firstInvoked = events.OfType<ExecutorInvokedEvent>().FirstOrDefault();
+        var query = firstInvoked?.Data switch
+        {
+            ChatMessage cm => cm.Text ?? string.Empty,
+            IReadOnlyList<ChatMessage> msgs => msgs.LastOrDefault(m => m.Role == ChatRole.User)?.Text ?? string.Empty,
+            string s => s,
+            _ => firstInvoked?.Data?.ToString() ?? string.Empty,
+        };
+
+        var conversation = new List<ChatMessage>
+        {
+            new(ChatRole.User, query),
+        };
+
+        // Prefer AgentResponseEvent (only emitted when AIAgentHostOptions.EmitAgentResponseEvents
+        // is enabled). Otherwise fall back to the last ExecutorCompletedEvent that carries an
+        // AgentResponse / ChatMessage / string payload — these are always emitted by the runtime.
+        var finalResponse = events.OfType<AgentResponseEvent>().LastOrDefault();
+        string responseText;
+        if (finalResponse is not null)
+        {
+            responseText = finalResponse.Response.Text;
+            conversation.AddRange(finalResponse.Response.Messages);
+        }
+        else
+        {
+            ExecutorCompletedEvent? finalCompleted = null;
+            for (int i = events.Count - 1; i >= 0; i--)
+            {
+                if (events[i] is ExecutorCompletedEvent completed
+                    && !IsInternalExecutor(completed.ExecutorId)
+                    && completed.Data is AgentResponse or ChatMessage or string)
+                {
+                    finalCompleted = completed;
+                    break;
+                }
+            }
+
+            if (finalCompleted is null)
+            {
+                return null;
+            }
+
+            switch (finalCompleted.Data)
+            {
+                case AgentResponse ar:
+                    responseText = ar.Text;
+                    conversation.AddRange(ar.Messages);
+                    break;
+                case ChatMessage cm:
+                    responseText = cm.Text ?? string.Empty;
+                    conversation.Add(cm);
+                    break;
+                case string s:
+                    responseText = s;
+                    conversation.Add(new ChatMessage(ChatRole.Assistant, s));
+                    break;
+                default:
+                    // Unreachable — the for-loop above already constrains Data to one of the
+                    // three handled types. Throw if the contract drifts so the bug is visible
+                    // instead of silently dropping the overall item.
+                    throw new InvalidOperationException(
+                        "BuildOverallItem: unexpected ExecutorCompletedEvent.Data type " +
+                        $"'{finalCompleted.Data?.GetType().FullName ?? "null"}'. Expected " +
+                        $"{nameof(AgentResponse)}, {nameof(ChatMessage)}, or string.");
+            }
+        }
+
+        return new EvalItem(query, responseText, conversation)
+        {
+            Splitter = splitter,
+            ExpectedOutput = expectedOutput,
+        };
+    }
+
     internal static Dictionary<string, List<EvalItem>> ExtractAgentData(
         List<WorkflowEvent> events,
         IConversationSplitter? splitter)

dotnet/src/Microsoft.Agents.AI.Workflows/HandoffWorkflowBuilder.cs

@@ -54,6 +54,8 @@ public class HandoffWorkflowBuilderCore<TBuilder> where TBuilder : HandoffWorkfl
     private bool _emitAgentResponseUpdateEvents;
     private HandoffToolCallFilteringBehavior _toolCallFilteringBehavior = HandoffToolCallFilteringBehavior.HandoffOnly;
     private bool _returnToPrevious;
+    private string? _name;
+    private string? _description;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="HandoffsWorkflowBuilder"/> class with no handoff relationships.
@@ -97,6 +99,20 @@ public class HandoffWorkflowBuilderCore<TBuilder> where TBuilder : HandoffWorkfl
         return (TBuilder)this;
     }
 
+    /// <inheritdoc cref="WorkflowBuilder.WithName(string)"/>
+    public TBuilder WithName(string name)
+    {
+        this._name = name;
+        return (TBuilder)this;
+    }
+
+    /// <inheritdoc cref="WorkflowBuilder.WithDescription(string)"/>
+    public TBuilder WithDescription(string description)
+    {
+        this._description = description;
+        return (TBuilder)this;
+    }
+
     /// <summary>
     /// Sets a value indicating whether agent streaming update events should be emitted during execution.
     /// If <see langword="null"/>, the value will be taken from the <see cref="TurnToken"/>
@@ -330,7 +346,16 @@ public class HandoffWorkflowBuilderCore<TBuilder> where TBuilder : HandoffWorkfl
             builder.AddEdge(start, executors[this._initialAgent.Id]);
         }
 
-        // Build the workflow.
+        if (!string.IsNullOrWhiteSpace(this._name))
+        {
+            builder.WithName(this._name);
+        }
+
+        if (!string.IsNullOrWhiteSpace(this._description))
+        {
+            builder.WithDescription(this._description);
+        }
+
         return builder.WithOutputFrom(end).Build();
     }
 }

dotnet/src/Microsoft.Agents.AI.Workflows/MagenticWorkflowBuilder.cs

@@ -1,5 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using System;
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 using System.Threading.Tasks;
@@ -140,7 +141,15 @@ public class MagenticWorkflowBuilder(AIAgent managerAgent)
     }
 
     /// <inheritdoc cref="WorkflowBuilder.Build"/>
-    public Workflow Build() => this.ReduceToWorkflowBuilder().Build();
+    public Workflow Build()
+    {
+        if (this._team.Count == 0)
+        {
+            throw new InvalidOperationException("At least one participant must be added via AddParticipants() before building the workflow.");
+        }
+
+        return this.ReduceToWorkflowBuilder().Build();
+    }
 
     private TaskLimits Limits => new(
         MaxRoundCount: this._maxRounds,

dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/HandoffAgentExecutor.cs

@@ -235,11 +235,10 @@ internal sealed class HandoffAgentExecutor :
         // This will not filter out tool responses and approval responses that are part of this agent's turn, which is
         // the expected behavior since those are part of the agent's reasoning process.
         HandoffMessagesFilter handoffMessagesFilter = new(this._options.ToolCallFilteringBehavior);
-        IEnumerable<ChatMessage> messagesForAgent = state.IncomingState.RequestedHandoffTargetAgentId is not null
+        List<ChatMessage> messagesForAgent = (state.IncomingState.RequestedHandoffTargetAgentId is not null
                                                   ? handoffMessagesFilter.FilterMessages(incomingMessages)
-                                                  : incomingMessages;
-
-        List<ChatMessage>? roleChanges = messagesForAgent.ChangeAssistantToUserForOtherParticipants(this._agent.Name ?? this._agent.Id);
+                                                  : incomingMessages)
+                                             .CopyWithAssistantToUserForOtherParticipants(this._agent.Name ?? this._agent.Id);
 
         bool emitUpdateEvents = state.IncomingState!.ShouldEmitStreamingEvents(this._options.EmitAgentResponseUpdateEvents);
         AgentInvocationResult result = await this.InvokeAgentAsync(messagesForAgent, context, emitUpdateEvents, cancellationToken)
@@ -250,8 +249,6 @@ internal sealed class HandoffAgentExecutor :
             throw new InvalidOperationException("Cannot request a handoff while holding pending requests.");
         }
 
-        roleChanges.ResetUserToAssistantForChangedRoles();
-
         int newConversationBookmark = state.ConversationBookmark;
         await this._sharedStateRef.InvokeWithStateAsync(
             (sharedState, ctx, ct) =>

dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/Magentic/MagenticOrchestrator.cs

@@ -101,6 +101,7 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
         return base.ConfigureProtocol(protocolBuilder)
                    .SendsMessage<ChatMessage>()
                    .SendsMessage<ResetChatSignal>()
+                   .YieldsOutput<List<ChatMessage>>()
                    .ConfigureRoutes(ConfigureRoutes);
 
         void ConfigureRoutes(RouteBuilder routeBuilder) => routeBuilder.AddPortHandler<MagenticPlanReviewRequest, MagenticPlanReviewResponse>(
@@ -109,7 +110,7 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
                 out this._planReviewPort);
     }
 
-    private ValueTask SubmitPlanReviewRequestAsync(MagenticTaskContext taskContext, IWorkflowContext workflowContext)
+    private ValueTask SubmitPlanReviewRequestAsync(MagenticTaskContext taskContext, IWorkflowContext workflowContext, bool replanAfterStall = false)
     {
         MagenticProgressLedger? progressLedger = taskContext.ProgressLedger;
         if (progressLedger?.IsStarted is not true)
@@ -117,7 +118,7 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
             progressLedger = null;
         }
 
-        MagenticPlanReviewRequest request = new(taskContext.TaskLedger!.CurrentPlan, progressLedger, taskContext.IsStalled);
+        MagenticPlanReviewRequest request = new(taskContext.TaskLedger!.CurrentPlan, progressLedger, replanAfterStall);
 
         return this._planReviewPort!.PostRequestAsync(request);
     }
@@ -146,7 +147,7 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
 
         if (this._taskContext.IsTerminated)
         {
-            throw new InvalidOperationException("Magentic Orchestration has already been terminated and cannot process new messages. Please start a new session.");
+            throw new InvalidOperationException("This Magentic orchestration has already terminated. To process new messages, create a new workflow instance.");
         }
 
         if (response.IsApproved)
@@ -161,7 +162,7 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
         }
     }
 
-    private async ValueTask UpdatePlanAndDelegateAsync(MagenticTaskContext taskContext, IWorkflowContext context, CancellationToken cancellationToken)
+    private async ValueTask UpdatePlanAndDelegateAsync(MagenticTaskContext taskContext, IWorkflowContext context, CancellationToken cancellationToken, bool replanAfterStall = false)
     {
         bool isReplan = taskContext.TaskLedger != null;
 
@@ -177,7 +178,7 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
 
         if (requirePlanSignoff)
         {
-            await this.SubmitPlanReviewRequestAsync(taskContext, context).ConfigureAwait(false);
+            await this.SubmitPlanReviewRequestAsync(taskContext, context, replanAfterStall).ConfigureAwait(false);
         }
         else
         {
@@ -187,9 +188,22 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
 
     protected override async ValueTask TakeTurnAsync(List<ChatMessage> messages, IWorkflowContext context, bool? emitEvents, CancellationToken cancellationToken = default)
     {
-        // First Turn: Initialize the task context and send the initial messages to the planner agent
-        this._taskContext ??= new(messages, team, limits, emitEvents, []);
-        await this.UpdatePlanAndDelegateAsync(this._taskContext, context, cancellationToken).ConfigureAwait(false);
+        if (this._taskContext?.IsTerminated == true)
+        {
+            throw new InvalidOperationException("This Magentic orchestration has already terminated. To process new messages, create a new workflow instance.");
+        }
+
+        if (this._taskContext == null)
+        {
+            // First Turn: Initialize the task context and create the initial plan
+            this._taskContext = new(messages, team, limits, emitEvents, []);
+            await this.UpdatePlanAndDelegateAsync(this._taskContext, context, cancellationToken).ConfigureAwait(false);
+        }
+        else
+        {
+            // Subsequent turns: agent returned control, go directly to coordination (progress ledger only, no replan)
+            await this.RunCoordinationRoundAsync(this._taskContext, context, cancellationToken).ConfigureAwait(false);
+        }
     }
 
     private ChatMessage? _fullTaskLedgerMessage;
@@ -288,10 +302,11 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
 
     private async ValueTask ResetAndReplanAsync(MagenticTaskContext taskContext, IWorkflowContext context, CancellationToken cancellationToken)
     {
+        bool wasStalled = taskContext.IsStalled;
         taskContext.Reset();
         await context.SendMessageAsync(new ResetChatSignal(), cancellationToken: cancellationToken).ConfigureAwait(false);
 
-        await this.UpdatePlanAndDelegateAsync(taskContext, context, cancellationToken).ConfigureAwait(false);
+        await this.UpdatePlanAndDelegateAsync(taskContext, context, cancellationToken, replanAfterStall: wasStalled).ConfigureAwait(false);
     }
 
     private async ValueTask PrepareFinalAnswerAsync(MagenticTaskContext taskContext, IWorkflowContext context, CancellationToken cancellationToken)

dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/Magentic/MagenticTaskContext.cs

@@ -58,7 +58,7 @@ internal class MagenticTaskContext(List<ChatMessage> taskDefinition, List<AIAgen
 
     public bool IsTerminated { get; internal set; }
 
-    public bool IsStalled => this.TaskCounters.StallCount >= this.TaskLimits.MaxStallCount;
+    public bool IsStalled => this.TaskCounters.StallCount > this.TaskLimits.MaxStallCount;
 
     public (bool HitRoundLimit, bool HitResetLimit) CheckLimits()
     {

dotnet/src/Microsoft.Agents.AI.Workflows/SwitchBuilder.cs

@@ -36,9 +36,13 @@ public sealed class SwitchBuilder
         Throw.IfNull(executors);
 
         HashSet<int> indicies = [];
+        int executorIndex = 0;
 
         foreach (ExecutorBinding executor in executors)
         {
+            // Explicit name: null element inside the collection argument.
+            Throw.IfNull(executor, $"{nameof(executors)}[{executorIndex++}]");
+
             if (!this._executorIndicies.TryGetValue(executor.Id, out int index))
             {
                 index = this._executors.Count;
@@ -64,8 +68,13 @@ public sealed class SwitchBuilder
     {
         Throw.IfNull(executors);
 
+        int executorIndex = 0;
+
         foreach (ExecutorBinding executor in executors)
         {
+            // Explicit name: null element inside the collection argument.
+            Throw.IfNull(executor, $"{nameof(executors)}[{executorIndex++}]");
+
             if (!this._executorIndicies.TryGetValue(executor.Id, out int index))
             {
                 index = this._executors.Count;

dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowBuilderExtensions.cs

@@ -25,7 +25,11 @@ public static class WorkflowBuilderExtensions
     /// <param name="target">The target executor to which messages will be forwarded.</param>
     /// <returns>The updated <see cref="WorkflowBuilder"/> instance.</returns>
     public static WorkflowBuilder ForwardMessage<TMessage>(this WorkflowBuilder builder, ExecutorBinding source, ExecutorBinding target)
-        => builder.ForwardMessage<TMessage>(source, [target], condition: null);
+    {
+        Throw.IfNull(target, nameof(target));
+
+        return builder.ForwardMessage<TMessage>(source, [target], condition: null);
+    }
 
     /// <summary>
     /// Adds edges to the workflow that forward messages of the specified type from the source executor to
@@ -52,6 +56,8 @@ public static class WorkflowBuilderExtensions
     /// <returns>The updated <see cref="WorkflowBuilder"/> instance.</returns>
     public static WorkflowBuilder ForwardMessage<TMessage>(this WorkflowBuilder builder, ExecutorBinding source, IEnumerable<ExecutorBinding> targets, Func<TMessage, bool>? condition = null)
     {
+        Throw.IfNull(builder);
+        Throw.IfNull(source);
         Throw.IfNull(targets);
 
         Func<object?, bool> predicate = WorkflowBuilder.CreateConditionFunc<TMessage>(IsAllowedTypeAndMatchingCondition)!;
@@ -62,14 +68,16 @@ public static class WorkflowBuilderExtensions
         if (targets is ICollection<ExecutorBinding> { Count: 1 })
 #endif
         {
-            return builder.AddEdge(source, targets.First(), predicate);
+            return builder.AddEdge(source, Throw.IfNull(targets.First(), nameof(targets)), predicate);
         }
 
-        return builder.AddSwitch(source, (switch_) => switch_.AddCase(predicate, targets));
+        return builder.AddSwitch(source, (switch_) => switch_.AddCase(predicate, targets.Select(ValidateTarget)));
 
         // The reason we can check for "not null" here is that CreateConditionFunc<T> will do the correct unwrapping
         // logic for PortableValues.
         bool IsAllowedTypeAndMatchingCondition(TMessage? message) => message != null && (condition == null || condition(message));
+
+        ExecutorBinding ValidateTarget(ExecutorBinding target) => Throw.IfNull(target, nameof(targets));
     }
 
     /// <summary>
@@ -81,7 +89,11 @@ public static class WorkflowBuilderExtensions
     /// <param name="target">The target executor to which messages, except those of type <typeparamref name="TMessage"/>, will be forwarded.</param>
     /// <returns>The updated <see cref="WorkflowBuilder"/> instance with the added edges.</returns>
     public static WorkflowBuilder ForwardExcept<TMessage>(this WorkflowBuilder builder, ExecutorBinding source, ExecutorBinding target)
-        => builder.ForwardExcept<TMessage>(source, [target]);
+    {
+        Throw.IfNull(target, nameof(target));
+
+        return builder.ForwardExcept<TMessage>(source, [target]);
+    }
 
     /// <summary>
     /// Adds edges from the specified source to the provided executors, excluding messages of a specified type.
@@ -93,6 +105,8 @@ public static class WorkflowBuilderExtensions
     /// <returns>The updated <see cref="WorkflowBuilder"/> instance with the added edges.</returns>
     public static WorkflowBuilder ForwardExcept<TMessage>(this WorkflowBuilder builder, ExecutorBinding source, IEnumerable<ExecutorBinding> targets)
     {
+        Throw.IfNull(builder);
+        Throw.IfNull(source);
         Throw.IfNull(targets);
 
         Func<object?, bool> predicate = WorkflowBuilder.CreateConditionFunc<TMessage>((Func<object?, bool>)IsAllowedType)!;
@@ -103,14 +117,16 @@ public static class WorkflowBuilderExtensions
         if (targets is ICollection<ExecutorBinding> { Count: 1 })
 #endif
         {
-            return builder.AddEdge(source, targets.First(), predicate);
+            return builder.AddEdge(source, Throw.IfNull(targets.First(), nameof(targets)), predicate);
         }
 
-        return builder.AddSwitch(source, (switch_) => switch_.AddCase(predicate, targets));
+        return builder.AddSwitch(source, (switch_) => switch_.AddCase(predicate, targets.Select(ValidateTarget)));
 
         // The reason we can check for "null" here is that CreateConditionFunc<T> will do the correct unwrapping
         // logic for PortableValues.
         static bool IsAllowedType(object? message) => message is null;
+
+        ExecutorBinding ValidateTarget(ExecutorBinding target) => Throw.IfNull(target, nameof(targets));
     }
 
     /// <summary>
@@ -129,6 +145,7 @@ public static class WorkflowBuilderExtensions
     {
         Throw.IfNull(builder);
         Throw.IfNull(source);
+        Throw.IfNull(executors);
 
         HashSet<string> seenExecutors = [source.Id];
 

dotnet/src/Microsoft.Agents.AI/Harness/FileStore/FileSystemAgentFileStore.cs

@@ -122,6 +122,7 @@ public sealed class FileSystemAgentFileStore : AgentFileStore
         }
 
         var files = Directory.GetFiles(fullDir)
+            .Where(f => (File.GetAttributes(f) & FileAttributes.ReparsePoint) == 0)
             .Select(Path.GetFileName)
             .Where(name => name is not null)
             .ToList();
@@ -157,6 +158,12 @@ public sealed class FileSystemAgentFileStore : AgentFileStore
 
         foreach (string filePath in Directory.GetFiles(fullDir))
         {
+            // Skip files that are symlinks/reparse points to prevent reading outside the root.
+            if ((File.GetAttributes(filePath) & FileAttributes.ReparsePoint) != 0)
+            {
+                continue;
+            }
+
             string? fileName = Path.GetFileName(filePath);
             if (fileName is null)
             {
@@ -231,7 +238,7 @@ public sealed class FileSystemAgentFileStore : AgentFileStore
 
     /// <summary>
     /// Resolves a relative file path to a safe absolute path under the root directory.
-    /// Rejects paths that would escape the root via traversal or rooted paths.
+    /// Rejects paths that would escape the root via traversal, rooted paths, or symbolic links.
     /// </summary>
     private string ResolveSafePath(string relativePath)
     {
@@ -250,9 +257,55 @@ public sealed class FileSystemAgentFileStore : AgentFileStore
                 nameof(relativePath));
         }
 
+        // Reject symlinks/reparse points in any path segment to prevent escaping the root.
+        ThrowIfContainsSymlink(fullPath, this._rootPath);
+
         return fullPath;
     }
 
+    /// <summary>
+    /// Checks each path segment between the trusted root and the resolved path for symbolic links
+    /// or reparse points. Throws <see cref="ArgumentException"/> if any segment is a symlink.
+    /// Stops checking at the first segment that does not exist on disk (for write scenarios).
+    /// Uses <see cref="File.GetAttributes(string)"/> directly so that dangling symlinks (whose targets
+    /// do not exist) are still detected via their <see cref="FileAttributes.ReparsePoint"/> flag.
+    /// </summary>
+    private static void ThrowIfContainsSymlink(string fullPath, string rootPath)
+    {
+        string rootTrimmed = rootPath.TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
+        string relative = fullPath.Substring(rootTrimmed.Length);
+        string[] segments = relative.Split(
+            [Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar],
+            StringSplitOptions.RemoveEmptyEntries);
+
+        string current = rootTrimmed;
+        foreach (string segment in segments)
+        {
+            current = Path.Combine(current, segment);
+
+            FileAttributes attributes;
+            try
+            {
+                attributes = File.GetAttributes(current);
+            }
+            catch (FileNotFoundException)
+            {
+                // Segment does not exist on disk (write scenario); stop checking.
+                break;
+            }
+            catch (DirectoryNotFoundException)
+            {
+                break;
+            }
+
+            if ((attributes & FileAttributes.ReparsePoint) != 0)
+            {
+                throw new ArgumentException(
+                    "Invalid path: the resolved path contains a symbolic link or reparse point.");
+            }
+        }
+    }
+
     /// <summary>
     /// Resolves a relative directory path to a safe absolute path under the root directory.
     /// An empty string resolves to the root directory itself.

dotnet/src/Microsoft.Agents.AI/OpenTelemetryAgent.cs

@@ -3,10 +3,12 @@
 using System;
 using System.Collections.Generic;
 using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
 
 namespace Microsoft.Agents.AI;
 
@@ -32,6 +34,13 @@ public sealed class OpenTelemetryAgent : DelegatingAIAgent, IDisposable
     private readonly OpenTelemetryChatClient _otelClient;
     /// <summary>The provider name extracted from <see cref="AIAgentMetadata"/>.</summary>
     private readonly string? _providerName;
+    /// <summary>The resolved source name for telemetry. Always non-empty; defaults to <see cref="OpenTelemetryConsts.DefaultSourceName"/>.</summary>
+    private readonly string _sourceName;
+    /// <summary>
+    /// Indicates whether the underlying <see cref="IChatClient"/> of a <see cref="ChatClientAgent"/> inner agent
+    /// should be automatically wrapped with <see cref="OpenTelemetryChatClient"/> on each invocation.
+    /// </summary>
+    private readonly bool _autoWireChatClient;
 
     /// <summary>Initializes a new instance of the <see cref="OpenTelemetryAgent"/> class.</summary>
     /// <param name="innerAgent">The underlying <see cref="AIAgent"/> to be augmented with telemetry capabilities.</param>
@@ -44,13 +53,44 @@ public sealed class OpenTelemetryAgent : DelegatingAIAgent, IDisposable
     /// The constructor automatically extracts provider metadata from the inner agent and configures
     /// telemetry collection according to OpenTelemetry semantic conventions for AI systems.
     /// </remarks>
-    public OpenTelemetryAgent(AIAgent innerAgent, string? sourceName = null) : base(innerAgent)
+    public OpenTelemetryAgent(AIAgent innerAgent, string? sourceName = null)
+#pragma warning disable MAAI001 // Auto-wiring is the new default; the experimental opt-out lives on the 3-arg overload.
+        : this(innerAgent, sourceName, autoWireChatClient: true)
+#pragma warning restore MAAI001
+    {
+    }
+
+    /// <summary>Initializes a new instance of the <see cref="OpenTelemetryAgent"/> class.</summary>
+    /// <param name="innerAgent">The underlying <see cref="AIAgent"/> to be augmented with telemetry capabilities.</param>
+    /// <param name="sourceName">
+    /// An optional source name that will be used to identify telemetry data from this agent.
+    /// If not provided, a default source name will be used for telemetry identification.
+    /// </param>
+    /// <param name="autoWireChatClient">
+    /// When <see langword="true"/> and the inner agent is a <see cref="ChatClientAgent"/>, the underlying
+    /// <see cref="IChatClient"/> is automatically wrapped with <see cref="OpenTelemetryChatClient"/> for each invocation
+    /// so that chat-level telemetry flows alongside agent-level telemetry. If the underlying chat client is already
+    /// instrumented, no additional wrapping is applied. Set to <see langword="false"/> to opt-out of this behavior.
+    /// </param>
+    /// <exception cref="ArgumentNullException"><paramref name="innerAgent"/> is <see langword="null"/>.</exception>
+    /// <remarks>
+    /// The constructor automatically extracts provider metadata from the inner agent and configures
+    /// telemetry collection according to OpenTelemetry semantic conventions for AI systems.
+    /// </remarks>
+    [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+    public OpenTelemetryAgent(AIAgent innerAgent, string? sourceName, bool autoWireChatClient) : base(innerAgent)
     {
         this._providerName = innerAgent.GetService<AIAgentMetadata>()?.ProviderName;
 
+        // Resolve once so the outer OpenTelemetryChatClient and the auto-wired inner
+        // OpenTelemetryChatClient always emit spans under the same ActivitySource, even when
+        // the caller passes "" or whitespace (which neither client should treat as a real source).
+        this._sourceName = string.IsNullOrWhiteSpace(sourceName) ? OpenTelemetryConsts.DefaultSourceName : sourceName!;
+        this._autoWireChatClient = autoWireChatClient;
+
         this._otelClient = new OpenTelemetryChatClient(
             new ForwardingChatClient(this),
-            sourceName: string.IsNullOrEmpty(sourceName) ? OpenTelemetryConsts.DefaultSourceName : sourceName!);
+            sourceName: this._sourceName);
     }
 
     /// <inheritdoc/>
@@ -163,6 +203,85 @@ public sealed class OpenTelemetryAgent : DelegatingAIAgent, IDisposable
         public Activity? CurrentActivity { get; }
     }
 
+    /// <summary>
+    /// If auto-wiring is enabled and the inner agent is a <see cref="ChatClientAgent"/> whose underlying
+    /// <see cref="IChatClient"/> is not already instrumented with <see cref="OpenTelemetryChatClient"/>, returns a
+    /// new <see cref="ChatClientAgentRunOptions"/> with a <see cref="ChatClientAgentRunOptions.ChatClientFactory"/>
+    /// that wraps the chat client with <see cref="OpenTelemetryChatClient"/>. When <paramref name="options"/> is a
+    /// plain <see cref="AgentRunOptions"/> (the base type, not <see cref="ChatClientAgentRunOptions"/>), the base
+    /// properties are copied onto the new <see cref="ChatClientAgentRunOptions"/> so high-level callers that pass
+    /// the abstract <see cref="AgentRunOptions"/> still benefit from auto-wiring and propagate their settings to
+    /// the inner agent. Otherwise, returns <paramref name="options"/> unchanged.
+    /// </summary>
+    private AgentRunOptions? GetRunOptionsWithChatClientWiring(AgentRunOptions? options)
+    {
+        if (!this._autoWireChatClient)
+        {
+            return options;
+        }
+
+        // The auto-wiring only applies when a ChatClientAgent is reachable from the inner agent. Otherwise, no-op.
+        // Use GetService rather than a type check so wrapping agents that expose a nested ChatClientAgent are supported.
+        var chatClientAgent = this.InnerAgent.GetService<ChatClientAgent>();
+        if (chatClientAgent is null)
+        {
+            return options;
+        }
+
+        // Respect ChatClientAgentOptions.UseProvidedChatClientAsIs: don't decorate the chat client when the user opted out.
+        if (chatClientAgent.GetService<ChatClientAgentOptions>()?.UseProvidedChatClientAsIs is true)
+        {
+            return options;
+        }
+
+        // Capture the underlying IChatClient and check whether it is already instrumented.
+        var chatClient = chatClientAgent.GetService<IChatClient>();
+        if (chatClient is null || chatClient.GetService(typeof(OpenTelemetryChatClient)) is not null)
+        {
+            return options;
+        }
+
+        string sourceName = this._sourceName;
+        static IChatClient WrapIfNeeded(IChatClient cc, string sourceName) =>
+            cc.GetService(typeof(OpenTelemetryChatClient)) is not null
+                ? cc
+                : cc.AsBuilder().UseOpenTelemetry(sourceName: sourceName).Build();
+
+        if (options is ChatClientAgentRunOptions ccOptions)
+        {
+            // Don't mutate the caller's options; clone and chain any caller-provided factory.
+            // If the user factory already returns an OpenTelemetry-instrumented client, don't double-wrap.
+            var clone = (ChatClientAgentRunOptions)ccOptions.Clone();
+            var userFactory = clone.ChatClientFactory;
+            clone.ChatClientFactory = cc => WrapIfNeeded(userFactory is null ? cc : userFactory(cc), sourceName);
+            return clone;
+        }
+
+        // For a plain AgentRunOptions (or null), create a ChatClientAgentRunOptions and preserve
+        // any base AgentRunOptions properties from the caller so they reach the inner agent.
+        var newOptions = new ChatClientAgentRunOptions
+        {
+            ChatClientFactory = cc => WrapIfNeeded(cc, sourceName),
+        };
+
+        if (options is not null)
+        {
+            CopyBaseAgentRunOptions(options, newOptions);
+        }
+
+        return newOptions;
+    }
+
+#pragma warning disable MEAI001 // ContinuationToken is experimental; copy it through to preserve caller-provided value.
+    private static void CopyBaseAgentRunOptions(AgentRunOptions source, AgentRunOptions target)
+    {
+        target.ContinuationToken = source.ContinuationToken;
+        target.AllowBackgroundResponses = source.AllowBackgroundResponses;
+        target.AdditionalProperties = source.AdditionalProperties?.Clone();
+        target.ResponseFormat = source.ResponseFormat;
+    }
+#pragma warning restore MEAI001
+
     /// <summary>The stub <see cref="IChatClient"/> used to delegate from the <see cref="OpenTelemetryChatClient"/> into the inner <see cref="AIAgent"/>.</summary>
     /// <param name="parentAgent"></param>
     private sealed class ForwardingChatClient(OpenTelemetryAgent parentAgent) : IChatClient
@@ -175,8 +294,11 @@ public sealed class OpenTelemetryAgent : DelegatingAIAgent, IDisposable
             // Update the current activity to reflect the agent invocation.
             parentAgent.UpdateCurrentActivity(fo?.CurrentActivity);
 
+            // If enabled, wire the underlying chat client with OpenTelemetryChatClient via ChatClientFactory.
+            var runOptions = parentAgent.GetRunOptionsWithChatClientWiring(fo?.Options);
+
             // Invoke the inner agent.
-            var response = await parentAgent.InnerAgent.RunAsync(messages, fo?.Session, fo?.Options, cancellationToken).ConfigureAwait(false);
+            var response = await parentAgent.InnerAgent.RunAsync(messages, fo?.Session, runOptions, cancellationToken).ConfigureAwait(false);
 
             // Wrap the response in a ChatResponse so we can pass it back through OpenTelemetryChatClient.
             return response.AsChatResponse();
@@ -190,8 +312,11 @@ public sealed class OpenTelemetryAgent : DelegatingAIAgent, IDisposable
             // Update the current activity to reflect the agent invocation.
             parentAgent.UpdateCurrentActivity(fo?.CurrentActivity);
 
+            // If enabled, wire the underlying chat client with OpenTelemetryChatClient via ChatClientFactory.
+            var runOptions = parentAgent.GetRunOptionsWithChatClientWiring(fo?.Options);
+
             // Invoke the inner agent.
-            await foreach (var update in parentAgent.InnerAgent.RunStreamingAsync(messages, fo?.Session, fo?.Options, cancellationToken).ConfigureAwait(false))
+            await foreach (var update in parentAgent.InnerAgent.RunStreamingAsync(messages, fo?.Session, runOptions, cancellationToken).ConfigureAwait(false))
             {
                 // Wrap the response updates in ChatResponseUpdates so we can pass them back through OpenTelemetryChatClient.
                 yield return update.AsChatResponseUpdate();

dotnet/tests/Microsoft.Agents.AI.DevUI.UnitTests/DevUIIntegrationTests.cs

@@ -218,7 +218,7 @@ public class DevUIIntegrationTests
         Assert.Contains(discoveryResponse.Entities, e => e.Name == "default-workflow" && e.Type == "workflow");
     }
 
-    [Fact]
+    [Fact(Skip = "Flaky in merge_group; see https://github.com/microsoft/agent-framework/issues/5845")]
     public async Task TestServerWithDevUI_ResolvesMixedAgentsAndWorkflows_AllRegistrationsAsync()
     {
         // Arrange

dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/FoundryEvalConverterTests.cs

@@ -179,6 +179,35 @@ public sealed class FoundryEvalConverterTests
         Assert.Null(payload.Context);
     }
 
+    [Fact]
+    public void ConvertEvalItem_WithExpectedOutput_PopulatesGroundTruth()
+    {
+        // Arrange
+        var item = new EvalItem(query: "q", response: "r")
+        {
+            ExpectedOutput = "the golden answer",
+        };
+
+        // Act
+        var payload = FoundryEvalConverter.ConvertEvalItem(item);
+
+        // Assert
+        Assert.Equal("the golden answer", payload.GroundTruth);
+    }
+
+    [Fact]
+    public void ConvertEvalItem_WithoutExpectedOutput_OmitsGroundTruth()
+    {
+        // Arrange
+        var item = new EvalItem(query: "q", response: "r");
+
+        // Act
+        var payload = FoundryEvalConverter.ConvertEvalItem(item);
+
+        // Assert
+        Assert.Null(payload.GroundTruth);
+    }
+
     // ---------------------------------------------------------------
     // FoundryEvalConverter.BuildTestingCriteria tests
     // ---------------------------------------------------------------
@@ -239,6 +268,33 @@ public sealed class FoundryEvalConverterTests
         Assert.Equal("{{item.context}}", mapping["context"]);
     }
 
+    [Fact]
+    public void BuildTestingCriteria_SimilarityEvaluator_IncludesGroundTruth()
+    {
+        // Act
+        var criteria = FoundryEvalConverter.BuildTestingCriteria(
+            ["similarity"], "gpt-4o-mini", includeDataMapping: true);
+
+        // Assert
+        Assert.Single(criteria);
+        Assert.Equal("builtin.similarity", criteria[0].EvaluatorName);
+        var mapping = criteria[0].DataMapping;
+        Assert.NotNull(mapping);
+        Assert.True(mapping.ContainsKey("ground_truth"));
+        Assert.Equal("{{item.ground_truth}}", mapping["ground_truth"]);
+    }
+
+    [Fact]
+    public void BuildTestingCriteria_NonGroundTruthEvaluator_OmitsGroundTruth()
+    {
+        var criteria = FoundryEvalConverter.BuildTestingCriteria(
+            ["relevance"], "gpt-4o-mini", includeDataMapping: true);
+
+        var mapping = criteria[0].DataMapping;
+        Assert.NotNull(mapping);
+        Assert.False(mapping.ContainsKey("ground_truth"));
+    }
+
     [Fact]
     public void BuildTestingCriteria_WithoutDataMapping_OmitsMappingField()
     {
@@ -282,6 +338,59 @@ public sealed class FoundryEvalConverterTests
         Assert.True(schema.Properties.ContainsKey("tool_definitions"));
     }
 
+    [Fact]
+    public void BuildItemSchema_WithGroundTruth_IncludesGroundTruthProperty()
+    {
+        // Act
+        var schema = FoundryEvalConverter.BuildItemSchema(hasGroundTruth: true);
+
+        // Assert
+        Assert.True(schema.Properties.ContainsKey("ground_truth"));
+        Assert.Equal("string", schema.Properties["ground_truth"].Type);
+    }
+
+    [Fact]
+    public void BuildItemSchema_WithoutGroundTruth_OmitsGroundTruthProperty()
+    {
+        var schema = FoundryEvalConverter.BuildItemSchema();
+
+        Assert.False(schema.Properties.ContainsKey("ground_truth"));
+    }
+
+    // ---------------------------------------------------------------
+    // FoundryEvalConverter.FindMissingGroundTruthEvaluators tests
+    // ---------------------------------------------------------------
+
+    [Fact]
+    public void FindMissingGroundTruthEvaluators_NoGroundTruth_ReturnsSimilarity()
+    {
+        // Act
+        var missing = FoundryEvalConverter.FindMissingGroundTruthEvaluators(
+            ["similarity", "relevance"], hasGroundTruth: false);
+
+        // Assert
+        Assert.Single(missing);
+        Assert.Equal("similarity", missing[0]);
+    }
+
+    [Fact]
+    public void FindMissingGroundTruthEvaluators_HasGroundTruth_ReturnsEmpty()
+    {
+        var missing = FoundryEvalConverter.FindMissingGroundTruthEvaluators(
+            ["similarity"], hasGroundTruth: true);
+
+        Assert.Empty(missing);
+    }
+
+    [Fact]
+    public void FindMissingGroundTruthEvaluators_NoGroundTruthEvaluators_ReturnsEmpty()
+    {
+        var missing = FoundryEvalConverter.FindMissingGroundTruthEvaluators(
+            ["relevance", "coherence"], hasGroundTruth: false);
+
+        Assert.Empty(missing);
+    }
+
     // ---------------------------------------------------------------
     // FoundryEvalConverter.ConvertMessage DataContent test
     // ---------------------------------------------------------------

dotnet/tests/Microsoft.Agents.AI.Harness.UnitTests/HarnessAgentOptionsTests.cs

@@ -0,0 +1,56 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.UnitTests;
+
+public class HarnessAgentOptionsTests
+{
+    /// <summary>
+    /// Verify that default property values are as expected.
+    /// </summary>
+    [Fact]
+    public void DefaultPropertyValues()
+    {
+        // Arrange & Act
+        var options = new HarnessAgentOptions();
+
+        // Assert
+        Assert.Null(options.Id);
+        Assert.Null(options.Name);
+        Assert.Null(options.Description);
+        Assert.Null(options.ChatOptions);
+        Assert.Null(options.ChatHistoryProvider);
+        Assert.Null(options.AIContextProviders);
+    }
+
+    /// <summary>
+    /// Verify that all properties can be set and retrieved.
+    /// </summary>
+    [Fact]
+    public void PropertiesCanBeSetAndRetrieved()
+    {
+        // Arrange
+        var chatHistoryProvider = new InMemoryChatHistoryProvider();
+        var contextProviders = new AIContextProvider[] { new TodoProvider() };
+
+        // Act
+        var options = new HarnessAgentOptions
+        {
+            Id = "test-id",
+            Name = "test-name",
+            Description = "test-description",
+            ChatOptions = new() { Temperature = 0.5f, Instructions = "custom instructions" },
+            ChatHistoryProvider = chatHistoryProvider,
+            AIContextProviders = contextProviders,
+        };
+
+        // Assert
+        Assert.Equal("test-id", options.Id);
+        Assert.Equal("test-name", options.Name);
+        Assert.Equal("test-description", options.Description);
+        Assert.NotNull(options.ChatOptions);
+        Assert.Equal(0.5f, options.ChatOptions!.Temperature);
+        Assert.Equal("custom instructions", options.ChatOptions.Instructions);
+        Assert.Same(chatHistoryProvider, options.ChatHistoryProvider);
+        Assert.Same(contextProviders, options.AIContextProviders);
+    }
+}

dotnet/tests/Microsoft.Agents.AI.Harness.UnitTests/HarnessAgentTests.cs

@@ -0,0 +1,516 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Moq;
+
+namespace Microsoft.Agents.AI.UnitTests;
+
+public class HarnessAgentTests
+{
+    private const int TestMaxContextWindowTokens = 100_000;
+    private const int TestMaxOutputTokens = 10_000;
+
+    #region Constructor Validation
+
+    /// <summary>
+    /// Verify that the constructor throws when chatClient is null.
+    /// </summary>
+    [Fact]
+    public void Constructor_ThrowsWhenChatClientIsNull()
+    {
+        // Act & Assert
+        Assert.Throws<ArgumentNullException>(() => new HarnessAgent(null!, TestMaxContextWindowTokens, TestMaxOutputTokens));
+    }
+
+    /// <summary>
+    /// Verify that the constructor throws when MaxContextWindowTokens is invalid (zero).
+    /// </summary>
+    [Fact]
+    public void Constructor_ThrowsWhenMaxContextWindowTokensIsZero()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act & Assert
+        Assert.Throws<ArgumentOutOfRangeException>(() => new HarnessAgent(chatClient, 0, TestMaxOutputTokens));
+    }
+
+    /// <summary>
+    /// Verify that the constructor throws when MaxOutputTokens equals MaxContextWindowTokens.
+    /// </summary>
+    [Fact]
+    public void Constructor_ThrowsWhenMaxOutputTokensEqualsContextWindow()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act & Assert
+        Assert.Throws<ArgumentOutOfRangeException>(() => new HarnessAgent(chatClient, 100_000, 100_000));
+    }
+
+    /// <summary>
+    /// Verify that the constructor succeeds when options is null.
+    /// </summary>
+    [Fact]
+    public void Constructor_SucceedsWhenOptionsIsNull()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens);
+
+        // Assert
+        Assert.NotNull(agent);
+    }
+
+    #endregion
+
+    #region Agent Identity
+
+    /// <summary>
+    /// Verify that Name and Description are passed through to the inner agent.
+    /// </summary>
+    [Fact]
+    public void NameAndDescription_ArePassedThrough()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, new HarnessAgentOptions
+        {
+            Name = "TestAgent",
+            Description = "A test agent",
+        });
+
+        // Assert
+        Assert.Equal("TestAgent", agent.Name);
+        Assert.Equal("A test agent", agent.Description);
+    }
+
+    /// <summary>
+    /// Verify that Id is passed through to the inner agent.
+    /// </summary>
+    [Fact]
+    public void Id_IsPassedThrough()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, new HarnessAgentOptions
+        {
+            Id = "my-agent-id",
+        });
+
+        // Assert
+        Assert.Equal("my-agent-id", agent.Id);
+    }
+
+    #endregion
+
+    #region Instructions
+
+    /// <summary>
+    /// Verify that default instructions are used when none are provided.
+    /// </summary>
+    [Fact]
+    public void Instructions_DefaultsToBuiltInInstructions()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens);
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.NotNull(innerAgent);
+        Assert.Equal(HarnessAgent.DefaultInstructions, innerAgent!.Instructions);
+    }
+
+    /// <summary>
+    /// Verify that default instructions are used when options is provided but ChatOptions.Instructions is null.
+    /// </summary>
+    [Fact]
+    public void Instructions_DefaultsWhenChatOptionsInstructionsIsNull()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, new HarnessAgentOptions
+        {
+            ChatOptions = new ChatOptions { Temperature = 0.5f },
+        });
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.NotNull(innerAgent);
+        Assert.Equal(HarnessAgent.DefaultInstructions, innerAgent!.Instructions);
+    }
+
+    /// <summary>
+    /// Verify that ChatOptions.Instructions overrides the defaults.
+    /// </summary>
+    [Fact]
+    public void Instructions_CanBeOverriddenViaChatOptions()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, new HarnessAgentOptions
+        {
+            ChatOptions = new ChatOptions { Instructions = "You are a custom assistant." },
+        });
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.NotNull(innerAgent);
+        Assert.Equal("You are a custom assistant.", innerAgent!.Instructions);
+    }
+
+    #endregion
+
+    #region ChatHistoryProvider
+
+    /// <summary>
+    /// Verify that the default ChatHistoryProvider is InMemoryChatHistoryProvider when none is specified.
+    /// </summary>
+    [Fact]
+    public void ChatHistoryProvider_DefaultsToInMemory()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens);
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.NotNull(innerAgent);
+        Assert.IsType<InMemoryChatHistoryProvider>(innerAgent!.ChatHistoryProvider);
+    }
+
+    /// <summary>
+    /// Verify that a custom ChatHistoryProvider is used when provided.
+    /// </summary>
+    [Fact]
+    public void ChatHistoryProvider_UsesCustomProviderWhenSpecified()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var customProvider = new InMemoryChatHistoryProvider();
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, new HarnessAgentOptions
+        {
+            ChatHistoryProvider = customProvider,
+        });
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.NotNull(innerAgent);
+        Assert.Same(customProvider, innerAgent!.ChatHistoryProvider);
+    }
+
+    #endregion
+
+    #region ChatClient Pipeline
+
+    /// <summary>
+    /// Verify that the inner agent's ChatClient includes FunctionInvokingChatClient in the pipeline.
+    /// </summary>
+    [Fact]
+    public void Pipeline_IncludesFunctionInvokingChatClient()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens);
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.NotNull(innerAgent);
+        var ficc = innerAgent!.ChatClient.GetService<FunctionInvokingChatClient>();
+        Assert.NotNull(ficc);
+    }
+
+    /// <summary>
+    /// Verify that the inner agent's ChatClient pipeline includes more than just the raw chat client,
+    /// confirming that per-service-call persistence and other decorators have been applied.
+    /// </summary>
+    [Fact]
+    public void Pipeline_HasDecoratedChatClient()
+    {
+        // Arrange
+        var mockClient = new Mock<IChatClient>();
+        var rawClient = mockClient.Object;
+
+        // Act
+        var agent = new HarnessAgent(rawClient, TestMaxContextWindowTokens, TestMaxOutputTokens);
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert — the pipeline wraps the raw client, so the outer client is not the same object.
+        Assert.NotNull(innerAgent);
+        Assert.NotSame(rawClient, innerAgent!.ChatClient);
+    }
+
+    #endregion
+
+    #region AIContextProviders
+
+    /// <summary>
+    /// Verify that additional AIContextProviders from options are passed to the inner ChatClientAgent,
+    /// not merged into the chat client builder pipeline.
+    /// </summary>
+    [Fact]
+    public void AIContextProviders_ArePassedToInnerAgent()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var todoProvider = new TodoProvider();
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, new HarnessAgentOptions
+        {
+            AIContextProviders = [todoProvider],
+        });
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert — the TodoProvider should appear in the inner agent's AIContextProviders.
+        Assert.NotNull(innerAgent);
+        Assert.NotNull(innerAgent!.AIContextProviders);
+        Assert.Contains(todoProvider, innerAgent.AIContextProviders!);
+    }
+
+    /// <summary>
+    /// Verify that when no AIContextProviders are specified, the inner agent has no additional providers.
+    /// </summary>
+    [Fact]
+    public void AIContextProviders_IsNullWhenNoneSpecified()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens);
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.NotNull(innerAgent);
+        Assert.Null(innerAgent!.AIContextProviders);
+    }
+
+    #endregion
+
+    #region ChatOptions and Tools
+
+    /// <summary>
+    /// Verify that tools from ChatOptions are passed to the model during invocation.
+    /// </summary>
+    [Fact]
+    public async Task ChatOptions_ToolsArePreservedAsync()
+    {
+        // Arrange
+        var tool = AIFunctionFactory.Create(() => "test", "TestTool");
+        var mockClient = new Mock<IChatClient>();
+        ChatOptions? capturedOptions = null;
+        mockClient
+            .Setup(c => c.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>()))
+            .Callback<IEnumerable<ChatMessage>, ChatOptions?, CancellationToken>((_, opts, _) => capturedOptions = opts)
+            .ReturnsAsync(new ChatResponse(new ChatMessage(ChatRole.Assistant, "Done")));
+
+        var agent = new HarnessAgent(mockClient.Object, TestMaxContextWindowTokens, TestMaxOutputTokens, new HarnessAgentOptions
+        {
+            ChatOptions = new ChatOptions
+            {
+                Tools = [tool],
+            },
+        });
+        var session = await agent.CreateSessionAsync();
+
+        // Act
+        await agent.RunAsync([new ChatMessage(ChatRole.User, "Hi")], session);
+
+        // Assert — verify the tool was included in the ChatOptions passed to the model.
+        Assert.NotNull(capturedOptions);
+        Assert.NotNull(capturedOptions!.Tools);
+        Assert.Contains(capturedOptions.Tools, t => t == tool);
+    }
+
+    /// <summary>
+    /// Verify that the source ChatOptions are cloned and not modified.
+    /// </summary>
+    [Fact]
+    public void ChatOptions_SourceIsNotModified()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var sourceChatOptions = new ChatOptions
+        {
+            Instructions = "original instructions",
+            Temperature = 0.7f,
+        };
+
+        // Act
+        _ = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens, new HarnessAgentOptions
+        {
+            ChatOptions = sourceChatOptions,
+        });
+
+        // Assert — source ChatOptions should not be mutated.
+        Assert.Equal("original instructions", sourceChatOptions.Instructions);
+        Assert.Equal(0.7f, sourceChatOptions.Temperature);
+    }
+
+    #endregion
+
+    #region GetService
+
+    /// <summary>
+    /// Verify that GetService returns the HarnessAgent for its own type.
+    /// </summary>
+    [Fact]
+    public void GetService_ReturnsSelfForHarnessAgentType()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens);
+
+        // Assert
+        Assert.Same(agent, agent.GetService<HarnessAgent>());
+    }
+
+    /// <summary>
+    /// Verify that GetService returns the inner ChatClientAgent.
+    /// </summary>
+    [Fact]
+    public void GetService_ReturnsInnerChatClientAgent()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = new HarnessAgent(chatClient, TestMaxContextWindowTokens, TestMaxOutputTokens);
+
+        // Assert
+        Assert.NotNull(agent.GetService<ChatClientAgent>());
+    }
+
+    #endregion
+
+    #region RunAsync Delegation
+
+    /// <summary>
+    /// Verify that RunAsync delegates to the inner ChatClientAgent.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_DelegatesToInnerAgentAsync()
+    {
+        // Arrange
+        var mockClient = new Mock<IChatClient>();
+        mockClient
+            .Setup(c => c.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>()))
+            .ReturnsAsync(new ChatResponse(new ChatMessage(ChatRole.Assistant, "Hello!")));
+
+        var agent = new HarnessAgent(mockClient.Object, TestMaxContextWindowTokens, TestMaxOutputTokens);
+        var session = await agent.CreateSessionAsync();
+
+        // Act
+        var response = await agent.RunAsync(
+            [new ChatMessage(ChatRole.User, "Hi")],
+            session);
+
+        // Assert
+        Assert.NotNull(response);
+        Assert.True(response.Messages.Any());
+    }
+
+    #endregion
+
+    #region DefaultInstructions
+
+    /// <summary>
+    /// Verify that DefaultInstructions is a non-empty public constant.
+    /// </summary>
+    [Fact]
+    public void DefaultInstructions_IsNonEmpty()
+    {
+        // Assert
+        Assert.False(string.IsNullOrWhiteSpace(HarnessAgent.DefaultInstructions));
+    }
+
+    #endregion
+
+    #region AsHarnessAgent Extension Method
+
+    /// <summary>
+    /// Verify that AsHarnessAgent creates a HarnessAgent with default options.
+    /// </summary>
+    [Fact]
+    public void AsHarnessAgent_CreatesAgentWithDefaults()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = chatClient.AsHarnessAgent(TestMaxContextWindowTokens, TestMaxOutputTokens);
+
+        // Assert
+        Assert.NotNull(agent);
+        Assert.IsType<HarnessAgent>(agent);
+        Assert.Equal(HarnessAgent.DefaultInstructions, agent.GetService<ChatClientAgent>()!.Instructions);
+    }
+
+    /// <summary>
+    /// Verify that AsHarnessAgent passes options through to the HarnessAgent.
+    /// </summary>
+    [Fact]
+    public void AsHarnessAgent_PassesOptionsThrough()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+
+        // Act
+        var agent = chatClient.AsHarnessAgent(TestMaxContextWindowTokens, TestMaxOutputTokens, new HarnessAgentOptions
+        {
+            Name = "ExtensionAgent",
+            ChatOptions = new ChatOptions { Instructions = "Custom instructions" },
+        });
+        var innerAgent = agent.GetService<ChatClientAgent>();
+
+        // Assert
+        Assert.Equal("ExtensionAgent", agent.Name);
+        Assert.NotNull(innerAgent);
+        Assert.Equal("Custom instructions", innerAgent!.Instructions);
+    }
+
+    /// <summary>
+    /// Verify that AsHarnessAgent throws when chatClient is null.
+    /// </summary>
+    [Fact]
+    public void AsHarnessAgent_ThrowsWhenChatClientIsNull()
+    {
+        // Act & Assert
+        Assert.Throws<ArgumentNullException>(() => ((IChatClient)null!).AsHarnessAgent(TestMaxContextWindowTokens, TestMaxOutputTokens));
+    }
+
+    #endregion
+}

dotnet/tests/Microsoft.Agents.AI.Harness.UnitTests/Microsoft.Agents.AI.Harness.UnitTests.csproj

@@ -0,0 +1,11 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <NoWarn>$(NoWarn);MAAI001</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Microsoft.Agents.AI.Harness\Microsoft.Agents.AI.Harness.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/tests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests/OpenAIResponsesAgentResolutionIntegrationTests.cs

@@ -267,7 +267,43 @@ public sealed class OpenAIResponsesAgentResolutionIntegrationTests : IAsyncDispo
         Assert.Equal(System.Net.HttpStatusCode.BadRequest, httpResponse.StatusCode);
 
         string responseJson = await httpResponse.Content.ReadAsStringAsync();
-        Assert.Contains("agent.name", responseJson, StringComparison.OrdinalIgnoreCase);
+        using JsonDocument errorDoc1 = JsonDocument.Parse(responseJson);
+        string? errorCode = errorDoc1.RootElement.GetProperty("error").GetProperty("code").GetString();
+        Assert.Equal("missing_required_parameter", errorCode);
+    }
+
+    /// <summary>
+    /// Verifies that the model field alone is not used for agent resolution.
+    /// The multi-agent endpoint requires agent.name or metadata.entity_id; setting only model returns 400.
+    /// </summary>
+    [Fact]
+    public async Task CreateResponse_WithModelOnly_ReturnsBadRequestAsync()
+    {
+        // Arrange
+        const string AgentName = "test-agent";
+
+        this._httpClient = await this.CreateTestServerWithAgentResolutionAsync(
+            (AgentName, "Instructions", "Response"));
+
+        // Act - Send request with model=agentName but no agent.name or metadata.entity_id
+        using StringContent requestContent = new(JsonSerializer.Serialize(new
+        {
+            model = AgentName,
+            input = new[]
+            {
+                new { type = "message", role = "user", content = "Test message" }
+            }
+        }), Encoding.UTF8, "application/json");
+
+        using HttpResponseMessage httpResponse = await this._httpClient!.PostAsync(new Uri("/v1/responses", UriKind.Relative), requestContent);
+
+        // Assert - model is not used for agent resolution
+        Assert.Equal(System.Net.HttpStatusCode.BadRequest, httpResponse.StatusCode);
+
+        string responseJson = await httpResponse.Content.ReadAsStringAsync();
+        using JsonDocument errorDoc2 = JsonDocument.Parse(responseJson);
+        string? errorCode = errorDoc2.RootElement.GetProperty("error").GetProperty("code").GetString();
+        Assert.Equal("missing_required_parameter", errorCode);
     }
 
     /// <summary>

dotnet/tests/Microsoft.Agents.AI.Hosting.UnitTests/HostApplicationBuilderWorkflowExtensionsTests.cs

@@ -103,6 +103,30 @@ public class HostApplicationBuilderWorkflowExtensionsTests
         Assert.Contains(workflowDescriptors, d => (string)d.ServiceKey! == "workflow3");
     }
 
+    /// <summary>
+    /// Verifies that a handoff workflow can be named from the DI workflow key.
+    /// </summary>
+    [Fact]
+    public void AddWorkflow_HandoffWorkflowWithName_ResolvesWorkflow()
+    {
+        var builder = new HostApplicationBuilder();
+        const string WorkflowName = "handoffWorkflow";
+
+        var mockAgent = new Mock<AIAgent>();
+        mockAgent.Setup(a => a.Name).Returns("handoffAgent");
+
+#pragma warning disable MAAIW001 // This test covers hosting handoff workflows.
+        builder.AddWorkflow(WorkflowName, (sp, key) =>
+            AgentWorkflowBuilder.CreateHandoffBuilderWith(mockAgent.Object)
+                .WithName(key)
+                .Build());
+#pragma warning restore MAAIW001
+
+        var workflow = builder.Build().Services.GetRequiredKeyedService<Workflow>(WorkflowName);
+
+        Assert.Equal(WorkflowName, workflow.Name);
+    }
+
     /// <summary>
     /// Verifies that AddWorkflow handles empty strings for name.
     /// </summary>

dotnet/tests/Microsoft.Agents.AI.UnitTests/Harness/FileStore/FileSystemAgentFileStoreTests.cs

@@ -334,4 +334,475 @@ public sealed class FileSystemAgentFileStoreTests : IDisposable
     }
 
     #endregion
+
+    #region Symlink Escape Rejection
+
+#if NET
+    /// <summary>
+    /// Attempts to create a file symlink. Returns false if the platform does not support
+    /// symlink creation (e.g., Windows without developer mode) or if creation fails.
+    /// </summary>
+    private static bool TryCreateFileSymbolicLink(string linkPath, string targetPath)
+    {
+        try
+        {
+            File.CreateSymbolicLink(linkPath, targetPath);
+        }
+        catch (IOException)
+        {
+            return false;
+        }
+
+        // Verify the symlink was actually created as a reparse point.
+        return File.Exists(linkPath)
+            && (File.GetAttributes(linkPath) & FileAttributes.ReparsePoint) != 0;
+    }
+
+    /// <summary>
+    /// Attempts to create a directory symlink. Returns false if the platform does not support
+    /// symlink creation (e.g., Windows without developer mode) or if creation fails.
+    /// </summary>
+    private static bool TryCreateDirectorySymbolicLink(string linkPath, string targetPath)
+    {
+        try
+        {
+            Directory.CreateSymbolicLink(linkPath, targetPath);
+        }
+        catch (IOException)
+        {
+            return false;
+        }
+
+        // Verify the symlink was actually created as a reparse point.
+        return Directory.Exists(linkPath)
+            && (File.GetAttributes(linkPath) & FileAttributes.ReparsePoint) != 0;
+    }
+
+    [Fact]
+    public async Task ReadFileAsync_SymlinkedFile_ThrowsAsync()
+    {
+        // Arrange — create a file outside the root and symlink to it from inside.
+        string outsideFile = Path.Combine(Path.GetTempPath(), "symlink_target_read_" + Guid.NewGuid().ToString("N") + ".txt");
+        File.WriteAllText(outsideFile, "SECRET_OUTSIDE_ROOT");
+
+        string linkPath = Path.Combine(this._rootDir, "leak.txt");
+
+        try
+        {
+            if (!TryCreateFileSymbolicLink(linkPath, outsideFile))
+            {
+                return; // Cannot create symlinks in this environment; skip.
+            }
+
+            // Act & Assert — reading through the symlink should be rejected.
+            await Assert.ThrowsAsync<ArgumentException>(() => this._store.ReadFileAsync("leak.txt"));
+        }
+        finally
+        {
+            if (File.Exists(linkPath))
+            {
+                File.Delete(linkPath);
+            }
+
+            File.Delete(outsideFile);
+        }
+    }
+
+    [Fact]
+    public async Task WriteFileAsync_SymlinkedFile_ThrowsAsync()
+    {
+        // Arrange — create a file outside the root and symlink to it from inside.
+        string outsideFile = Path.Combine(Path.GetTempPath(), "symlink_target_write_" + Guid.NewGuid().ToString("N") + ".txt");
+        File.WriteAllText(outsideFile, "ORIGINAL_CONTENT");
+
+        string linkPath = Path.Combine(this._rootDir, "overwrite.txt");
+
+        try
+        {
+            if (!TryCreateFileSymbolicLink(linkPath, outsideFile))
+            {
+                return;
+            }
+
+            // Act & Assert — writing through the symlink should be rejected.
+            await Assert.ThrowsAsync<ArgumentException>(() => this._store.WriteFileAsync("overwrite.txt", "EVIL_CONTENT"));
+
+            // Verify the outside file was NOT modified.
+            Assert.Equal("ORIGINAL_CONTENT", await File.ReadAllTextAsync(outsideFile));
+        }
+        finally
+        {
+            if (File.Exists(linkPath))
+            {
+                File.Delete(linkPath);
+            }
+
+            File.Delete(outsideFile);
+        }
+    }
+
+    [Fact]
+    public async Task DeleteFileAsync_SymlinkedFile_ThrowsAsync()
+    {
+        // Arrange
+        string outsideFile = Path.Combine(Path.GetTempPath(), "symlink_target_delete_" + Guid.NewGuid().ToString("N") + ".txt");
+        File.WriteAllText(outsideFile, "DO_NOT_DELETE");
+
+        string linkPath = Path.Combine(this._rootDir, "trap.txt");
+
+        try
+        {
+            if (!TryCreateFileSymbolicLink(linkPath, outsideFile))
+            {
+                return;
+            }
+
+            // Act & Assert
+            await Assert.ThrowsAsync<ArgumentException>(() => this._store.DeleteFileAsync("trap.txt"));
+
+            // Verify the outside file still exists.
+            Assert.True(File.Exists(outsideFile));
+        }
+        finally
+        {
+            if (File.Exists(linkPath))
+            {
+                File.Delete(linkPath);
+            }
+
+            File.Delete(outsideFile);
+        }
+    }
+
+    [Fact]
+    public async Task FileExistsAsync_SymlinkedFile_ThrowsAsync()
+    {
+        // Arrange
+        string outsideFile = Path.Combine(Path.GetTempPath(), "symlink_target_exists_" + Guid.NewGuid().ToString("N") + ".txt");
+        File.WriteAllText(outsideFile, "EXISTS_OUTSIDE");
+
+        string linkPath = Path.Combine(this._rootDir, "phantom.txt");
+
+        try
+        {
+            if (!TryCreateFileSymbolicLink(linkPath, outsideFile))
+            {
+                return;
+            }
+
+            // Act & Assert
+            await Assert.ThrowsAsync<ArgumentException>(() => this._store.FileExistsAsync("phantom.txt"));
+        }
+        finally
+        {
+            if (File.Exists(linkPath))
+            {
+                File.Delete(linkPath);
+            }
+
+            File.Delete(outsideFile);
+        }
+    }
+
+    [Fact]
+    public async Task WriteFileAsync_DanglingSymlink_ThrowsAsync()
+    {
+        // Arrange — create a symlink pointing to a non-existent target.
+        string nonExistentTarget = Path.Combine(Path.GetTempPath(), "dangling_target_" + Guid.NewGuid().ToString("N") + ".txt");
+        string linkPath = Path.Combine(this._rootDir, "dangling.txt");
+
+        try
+        {
+            if (!TryCreateFileSymbolicLink(linkPath, nonExistentTarget))
+            {
+                return;
+            }
+
+            // Act & Assert — even a dangling symlink must be rejected.
+            await Assert.ThrowsAsync<ArgumentException>(() => this._store.WriteFileAsync("dangling.txt", "CONTENT"));
+
+            // Verify the target was NOT created by following the dangling link.
+            Assert.False(File.Exists(nonExistentTarget));
+        }
+        finally
+        {
+            // Dangling symlinks: File.Exists returns false, but the link entry still exists.
+            // Use FileInfo to delete the link itself.
+            var linkInfo = new FileInfo(linkPath);
+            if (linkInfo.Exists || (linkInfo.Attributes & FileAttributes.ReparsePoint) != 0)
+            {
+                linkInfo.Delete();
+            }
+        }
+    }
+
+    [Fact]
+    public async Task ListFilesAsync_SymlinkedDirectory_ThrowsAsync()
+    {
+        // Arrange — create a directory outside root and symlink a directory inside root to it.
+        string outsideDir = Path.Combine(Path.GetTempPath(), "symlink_dir_target_" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(outsideDir);
+        File.WriteAllText(Path.Combine(outsideDir, "secret.txt"), "SECRET");
+
+        string linkDir = Path.Combine(this._rootDir, "linked-dir");
+
+        try
+        {
+            if (!TryCreateDirectorySymbolicLink(linkDir, outsideDir))
+            {
+                return;
+            }
+
+            // Act & Assert
+            await Assert.ThrowsAsync<ArgumentException>(() => this._store.ListFilesAsync("linked-dir"));
+        }
+        finally
+        {
+            if (Directory.Exists(linkDir))
+            {
+                Directory.Delete(linkDir);
+            }
+
+            Directory.Delete(outsideDir, recursive: true);
+        }
+    }
+
+    [Fact]
+    public async Task SearchFilesAsync_SymlinkedDirectory_ThrowsAsync()
+    {
+        // Arrange
+        string outsideDir = Path.Combine(Path.GetTempPath(), "symlink_search_target_" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(outsideDir);
+        File.WriteAllText(Path.Combine(outsideDir, "data.txt"), "SENSITIVE_DATA");
+
+        string linkDir = Path.Combine(this._rootDir, "search-link");
+
+        try
+        {
+            if (!TryCreateDirectorySymbolicLink(linkDir, outsideDir))
+            {
+                return;
+            }
+
+            // Act & Assert
+            await Assert.ThrowsAsync<ArgumentException>(() => this._store.SearchFilesAsync("search-link", "SENSITIVE"));
+        }
+        finally
+        {
+            if (Directory.Exists(linkDir))
+            {
+                Directory.Delete(linkDir);
+            }
+
+            Directory.Delete(outsideDir, recursive: true);
+        }
+    }
+
+    [Fact]
+    public async Task ReadFileAsync_ThroughDirectorySymlink_ThrowsAsync()
+    {
+        // Arrange — directory symlink inside root pointing outside; read a file through it.
+        string outsideDir = Path.Combine(Path.GetTempPath(), "symlink_dir_read_" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(outsideDir);
+        File.WriteAllText(Path.Combine(outsideDir, "secret.txt"), "DIR_SYMLINK_SECRET");
+
+        string linkDir = Path.Combine(this._rootDir, "linked-output");
+
+        try
+        {
+            if (!TryCreateDirectorySymbolicLink(linkDir, outsideDir))
+            {
+                return;
+            }
+
+            // Act & Assert — reading through a directory symlink should be rejected.
+            await Assert.ThrowsAsync<ArgumentException>(() => this._store.ReadFileAsync("linked-output/secret.txt"));
+        }
+        finally
+        {
+            if (Directory.Exists(linkDir))
+            {
+                Directory.Delete(linkDir);
+            }
+
+            Directory.Delete(outsideDir, recursive: true);
+        }
+    }
+
+    [Fact]
+    public async Task WriteFileAsync_ThroughDirectorySymlink_ThrowsAsync()
+    {
+        // Arrange — directory symlink; attempt to create/overwrite a file through it.
+        string outsideDir = Path.Combine(Path.GetTempPath(), "symlink_dir_write_" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(outsideDir);
+
+        string linkDir = Path.Combine(this._rootDir, "linked-output");
+
+        try
+        {
+            if (!TryCreateDirectorySymbolicLink(linkDir, outsideDir))
+            {
+                return;
+            }
+
+            // Act & Assert
+            await Assert.ThrowsAsync<ArgumentException>(() => this._store.WriteFileAsync("linked-output/created-by-agent.txt", "CONTENT"));
+
+            // Verify no file was created outside.
+            Assert.False(File.Exists(Path.Combine(outsideDir, "created-by-agent.txt")));
+        }
+        finally
+        {
+            if (Directory.Exists(linkDir))
+            {
+                Directory.Delete(linkDir);
+            }
+
+            Directory.Delete(outsideDir, recursive: true);
+        }
+    }
+
+    [Fact]
+    public async Task DeleteFileAsync_ThroughDirectorySymlink_ThrowsAsync()
+    {
+        // Arrange — directory symlink; attempt to delete a file through it.
+        string outsideDir = Path.Combine(Path.GetTempPath(), "symlink_dir_delete_" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(outsideDir);
+        string outsideFile = Path.Combine(outsideDir, "delete-me.txt");
+        File.WriteAllText(outsideFile, "DO_NOT_DELETE");
+
+        string linkDir = Path.Combine(this._rootDir, "linked-output");
+
+        try
+        {
+            if (!TryCreateDirectorySymbolicLink(linkDir, outsideDir))
+            {
+                return;
+            }
+
+            // Act & Assert
+            await Assert.ThrowsAsync<ArgumentException>(() => this._store.DeleteFileAsync("linked-output/delete-me.txt"));
+
+            // Verify the outside file was NOT deleted.
+            Assert.True(File.Exists(outsideFile));
+        }
+        finally
+        {
+            if (Directory.Exists(linkDir))
+            {
+                Directory.Delete(linkDir);
+            }
+
+            Directory.Delete(outsideDir, recursive: true);
+        }
+    }
+
+    [Fact]
+    public async Task CreateDirectoryAsync_ThroughDirectorySymlink_ThrowsAsync()
+    {
+        // Arrange — directory symlink; attempt to create a subdirectory through it.
+        string outsideDir = Path.Combine(Path.GetTempPath(), "symlink_dir_mkdir_" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(outsideDir);
+
+        string linkDir = Path.Combine(this._rootDir, "linked-output");
+
+        try
+        {
+            if (!TryCreateDirectorySymbolicLink(linkDir, outsideDir))
+            {
+                return;
+            }
+
+            // Act & Assert
+            await Assert.ThrowsAsync<ArgumentException>(() => this._store.CreateDirectoryAsync("linked-output/created-directory"));
+
+            // Verify no directory was created outside.
+            Assert.False(Directory.Exists(Path.Combine(outsideDir, "created-directory")));
+        }
+        finally
+        {
+            if (Directory.Exists(linkDir))
+            {
+                Directory.Delete(linkDir);
+            }
+
+            Directory.Delete(outsideDir, recursive: true);
+        }
+    }
+
+    [Fact]
+    public async Task SearchFilesAsync_RootWithSymlinkedFile_DoesNotLeakContentAsync()
+    {
+        // Arrange — symlinked file at root level; search should not return its content.
+        string outsideFile = Path.Combine(Path.GetTempPath(), "symlink_search_root_" + Guid.NewGuid().ToString("N") + ".txt");
+        File.WriteAllText(outsideFile, "ROOT_LEVEL_SECRET_CONTENT");
+
+        string linkPath = Path.Combine(this._rootDir, "env-link.txt");
+
+        try
+        {
+            if (!TryCreateFileSymbolicLink(linkPath, outsideFile))
+            {
+                return;
+            }
+
+            // Also add a normal file to confirm search still works for non-symlinks.
+            await this._store.WriteFileAsync("normal.txt", "NORMAL_CONTENT");
+
+            // Act — search at root should skip the symlinked file.
+            var results = await this._store.SearchFilesAsync("", "SECRET_CONTENT");
+
+            // Assert — no results from the symlinked file.
+            Assert.Empty(results);
+        }
+        finally
+        {
+            if (File.Exists(linkPath))
+            {
+                File.Delete(linkPath);
+            }
+
+            File.Delete(outsideFile);
+        }
+    }
+
+    [Fact]
+    public async Task ListFilesAsync_RootWithSymlinkedFile_ExcludesSymlinkAsync()
+    {
+        // Arrange — symlinked file at root level; listing should not include it.
+        string outsideFile = Path.Combine(Path.GetTempPath(), "symlink_list_root_" + Guid.NewGuid().ToString("N") + ".txt");
+        File.WriteAllText(outsideFile, "OUTSIDE");
+
+        string linkPath = Path.Combine(this._rootDir, "hidden-link.txt");
+
+        try
+        {
+            if (!TryCreateFileSymbolicLink(linkPath, outsideFile))
+            {
+                return;
+            }
+
+            // Also add a normal file.
+            await this._store.WriteFileAsync("visible.txt", "VISIBLE");
+
+            // Act
+            var files = await this._store.ListFilesAsync("");
+
+            // Assert — symlinked file should not appear in listing.
+            Assert.DoesNotContain("hidden-link.txt", files);
+            Assert.Contains("visible.txt", files);
+        }
+        finally
+        {
+            if (File.Exists(linkPath))
+            {
+                File.Delete(linkPath);
+            }
+
+            File.Delete(outsideFile);
+        }
+    }
+#endif
+
+    #endregion
 }

dotnet/tests/Microsoft.Agents.AI.UnitTests/OpenTelemetryAgentTests.cs

@@ -627,4 +627,455 @@ public class OpenTelemetryAgentTests
     }
 
     private static string ReplaceWhitespace(string? input) => Regex.Replace(input ?? "", @"\s+", "").Trim();
+
+    #region AutoWireChatClient
+
+    [Fact]
+    public async Task AutoWireChatClient_DefaultsToEnabled_EmitsChatSpan_Async()
+    {
+        var sourceName = Guid.NewGuid().ToString();
+        var activities = new List<Activity>();
+        using var tracerProvider = OpenTelemetry.Sdk.CreateTracerProviderBuilder()
+            .AddSource(sourceName)
+            .AddInMemoryExporter(activities)
+            .Build();
+
+        var fakeChatClient = new AutoWireTestChatClient();
+        var inner = new ChatClientAgent(fakeChatClient);
+        using var agent = new OpenTelemetryAgent(inner, sourceName);
+
+        _ = await agent.RunAsync("hi");
+
+        // Expect 2 activities: the inner chat span (from auto-wired OpenTelemetryChatClient) and the invoke_agent span.
+        Assert.Equal(2, activities.Count);
+        Assert.Contains(activities, a => a.DisplayName.StartsWith("invoke_agent", StringComparison.Ordinal));
+        Assert.Contains(activities, a => string.Equals(a.GetTagItem("gen_ai.operation.name") as string, "chat", StringComparison.Ordinal));
+    }
+
+    [Fact]
+    public async Task AutoWireChatClient_Streaming_EmitsChatSpan_Async()
+    {
+        var sourceName = Guid.NewGuid().ToString();
+        var activities = new List<Activity>();
+        using var tracerProvider = OpenTelemetry.Sdk.CreateTracerProviderBuilder()
+            .AddSource(sourceName)
+            .AddInMemoryExporter(activities)
+            .Build();
+
+        var fakeChatClient = new AutoWireTestChatClient();
+        var inner = new ChatClientAgent(fakeChatClient);
+        using var agent = new OpenTelemetryAgent(inner, sourceName);
+
+        await foreach (var _ in agent.RunStreamingAsync("hi"))
+        {
+        }
+
+        Assert.Equal(2, activities.Count);
+        Assert.Contains(activities, a => a.DisplayName.StartsWith("invoke_agent", StringComparison.Ordinal));
+        Assert.Contains(activities, a => string.Equals(a.GetTagItem("gen_ai.operation.name") as string, "chat", StringComparison.Ordinal));
+    }
+
+    [Fact]
+    public async Task AutoWireChatClient_Disabled_DoesNotEmitChatSpan_Async()
+    {
+        var sourceName = Guid.NewGuid().ToString();
+        var activities = new List<Activity>();
+        using var tracerProvider = OpenTelemetry.Sdk.CreateTracerProviderBuilder()
+            .AddSource(sourceName)
+            .AddInMemoryExporter(activities)
+            .Build();
+
+        var fakeChatClient = new AutoWireTestChatClient();
+        var inner = new ChatClientAgent(fakeChatClient);
+        using var agent = new OpenTelemetryAgent(inner, sourceName, autoWireChatClient: false);
+
+        _ = await agent.RunAsync("hi");
+
+        // Only the invoke_agent activity should be emitted; no chat span.
+        var activity = Assert.Single(activities);
+        Assert.StartsWith("invoke_agent", activity.DisplayName);
+    }
+
+    [Fact]
+    public async Task AutoWireChatClient_NonChatClientAgent_NoOp_Async()
+    {
+        // Inner is not a ChatClientAgent — auto-wiring must be a no-op and options must remain null.
+        AgentRunOptions? observedOptions = null;
+        var inner = new TestAIAgent
+        {
+            RunAsyncFunc = (messages, session, options, ct) =>
+            {
+                observedOptions = options;
+                return Task.FromResult(new AgentResponse(new ChatMessage(ChatRole.Assistant, "ok")));
+            },
+        };
+
+        using var agent = new OpenTelemetryAgent(inner);
+
+        _ = await agent.RunAsync("hi");
+
+        Assert.Null(observedOptions);
+    }
+
+    [Fact]
+    public async Task AutoWireChatClient_UseProvidedChatClientAsIs_DoesNotEmitChatSpan_Async()
+    {
+        var sourceName = Guid.NewGuid().ToString();
+        var activities = new List<Activity>();
+        using var tracerProvider = OpenTelemetry.Sdk.CreateTracerProviderBuilder()
+            .AddSource(sourceName)
+            .AddInMemoryExporter(activities)
+            .Build();
+
+        var fakeChatClient = new AutoWireTestChatClient();
+        var inner = new ChatClientAgent(fakeChatClient, new ChatClientAgentOptions { UseProvidedChatClientAsIs = true });
+        using var agent = new OpenTelemetryAgent(inner, sourceName);
+
+        _ = await agent.RunAsync("hi");
+
+        // UseProvidedChatClientAsIs opts out of auto-wiring, so only the invoke_agent span should be emitted.
+        var activity = Assert.Single(activities);
+        Assert.StartsWith("invoke_agent", activity.DisplayName);
+    }
+
+    [Fact]
+    public async Task AutoWireChatClient_AlreadyInstrumented_DoesNotDoubleWrap_Async()
+    {
+        var sourceName = Guid.NewGuid().ToString();
+        var activities = new List<Activity>();
+        using var tracerProvider = OpenTelemetry.Sdk.CreateTracerProviderBuilder()
+            .AddSource(sourceName)
+            .AddInMemoryExporter(activities)
+            .Build();
+
+        var fakeChatClient = new AutoWireTestChatClient();
+        // Pre-wrap with OpenTelemetryChatClient on the same source so spans flow through the tracer.
+        IChatClient preWrapped = fakeChatClient.AsBuilder().UseOpenTelemetry(sourceName: sourceName).Build();
+        var inner = new ChatClientAgent(preWrapped);
+        using var agent = new OpenTelemetryAgent(inner, sourceName);
+
+        _ = await agent.RunAsync("hi");
+
+        // Expect exactly 2 activities (one invoke_agent + one chat from the pre-existing wrapper). If we had double-wrapped, we would see 3.
+        Assert.Equal(2, activities.Count);
+    }
+
+    [Fact]
+    public async Task AutoWireChatClient_PreservesUserChatClientFactory_Async()
+    {
+        var sourceName = Guid.NewGuid().ToString();
+        var activities = new List<Activity>();
+        using var tracerProvider = OpenTelemetry.Sdk.CreateTracerProviderBuilder()
+            .AddSource(sourceName)
+            .AddInMemoryExporter(activities)
+            .Build();
+
+        bool userFactoryCalled = false;
+        var fakeChatClient = new AutoWireTestChatClient();
+        var inner = new ChatClientAgent(fakeChatClient);
+        using var agent = new OpenTelemetryAgent(inner, sourceName);
+
+        var runOptions = new ChatClientAgentRunOptions
+        {
+            ChatClientFactory = cc =>
+            {
+                userFactoryCalled = true;
+                return cc;
+            },
+        };
+
+        _ = await agent.RunAsync("hi", options: runOptions);
+
+        Assert.True(userFactoryCalled);
+        // Auto-wiring should still produce a chat span on top of the user's factory.
+        Assert.Equal(2, activities.Count);
+        Assert.Contains(activities, a => string.Equals(a.GetTagItem("gen_ai.operation.name") as string, "chat", StringComparison.Ordinal));
+    }
+
+    [Fact]
+    public async Task AutoWireChatClient_PlainAgentRunOptions_PreservesBaseProperties_Async()
+    {
+        // Auto-wiring converts a plain AgentRunOptions into a ChatClientAgentRunOptions. The base
+        // properties (ContinuationToken, AllowBackgroundResponses, AdditionalProperties, ResponseFormat)
+        // must be preserved so they reach the inner agent.
+        AgentRunOptions? observedOptions = null;
+        var fakeChatClient = new AutoWireTestChatClient();
+        var innerChatClientAgent = new ChatClientAgent(fakeChatClient);
+
+        // Wrapping agent: surfaces the ChatClientAgent via GetService (so auto-wiring activates),
+        // but captures the AgentRunOptions passed to RunAsync by the OpenTelemetryAgent.
+        var wrapper = new TestAIAgent
+        {
+            GetServiceFunc = (type, key) =>
+                type == typeof(ChatClientAgent) ? innerChatClientAgent : null,
+            RunAsyncFunc = (messages, session, options, ct) =>
+            {
+                observedOptions = options;
+                return Task.FromResult(new AgentResponse(new ChatMessage(ChatRole.Assistant, "ok")));
+            },
+        };
+
+        using var agent = new OpenTelemetryAgent(wrapper);
+
+        var additionalProps = new AdditionalPropertiesDictionary { ["customKey"] = "customValue" };
+        var inputOptions = new AgentRunOptions
+        {
+            AllowBackgroundResponses = true,
+            AdditionalProperties = additionalProps,
+            ResponseFormat = ChatResponseFormat.Json,
+        };
+
+        _ = await agent.RunAsync("hi", options: inputOptions);
+
+        Assert.NotNull(observedOptions);
+        Assert.IsType<ChatClientAgentRunOptions>(observedOptions);
+        Assert.Equal(true, observedOptions!.AllowBackgroundResponses);
+        Assert.Same(ChatResponseFormat.Json, observedOptions.ResponseFormat);
+        Assert.NotNull(observedOptions.AdditionalProperties);
+        Assert.Equal("customValue", observedOptions.AdditionalProperties!["customKey"]);
+    }
+
+    [Fact]
+    public async Task AutoWireChatClient_UserFactoryReturnsInstrumentedClient_DoesNotDoubleWrap_Async()
+    {
+        var sourceName = Guid.NewGuid().ToString();
+        var activities = new List<Activity>();
+        using var tracerProvider = OpenTelemetry.Sdk.CreateTracerProviderBuilder()
+            .AddSource(sourceName)
+            .AddInMemoryExporter(activities)
+            .Build();
+
+        var fakeChatClient = new AutoWireTestChatClient();
+        var inner = new ChatClientAgent(fakeChatClient);
+        using var agent = new OpenTelemetryAgent(inner, sourceName);
+
+        // User factory wraps the chat client with OpenTelemetryChatClient itself.
+        var runOptions = new ChatClientAgentRunOptions
+        {
+            ChatClientFactory = cc => cc.AsBuilder().UseOpenTelemetry(sourceName: sourceName).Build(),
+        };
+
+        _ = await agent.RunAsync("hi", options: runOptions);
+
+        // Expect 2 activities (invoke_agent + a single chat span). If we double-wrapped, we would see 3.
+        Assert.Equal(2, activities.Count);
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("   ")]
+    [InlineData("\t")]
+    public async Task Ctor_NullOrWhitespaceSourceName_AutoWiredChatClientUsesDefaultSource_Async(string? sourceName)
+    {
+        // Both the agent-level invoke_agent span and the auto-wired chat span must be emitted under
+        // OpenTelemetryConsts.DefaultSourceName when the caller passes null, "", or whitespace, so they reach
+        // the same ActivitySource and are not silently dropped by the exporter.
+        var activities = new List<Activity>();
+        using var tracerProvider = OpenTelemetry.Sdk.CreateTracerProviderBuilder()
+            .AddSource("Experimental.Microsoft.Agents.AI")
+            .AddInMemoryExporter(activities)
+            .Build();
+
+        var fakeChatClient = new AutoWireTestChatClient();
+        var inner = new ChatClientAgent(fakeChatClient);
+        using var agent = new OpenTelemetryAgent(inner, sourceName);
+
+        _ = await agent.RunAsync("hi");
+
+        Assert.Equal(2, activities.Count);
+        Assert.All(activities, a => Assert.Equal("Experimental.Microsoft.Agents.AI", a.Source.Name));
+        Assert.Contains(activities, a => a.DisplayName.StartsWith("invoke_agent", StringComparison.Ordinal));
+        Assert.Contains(activities, a => string.Equals(a.GetTagItem("gen_ai.operation.name") as string, "chat", StringComparison.Ordinal));
+    }
+
+#pragma warning disable MEAI001 // ResponseContinuationToken is experimental.
+    [Fact]
+    public async Task AutoWireChatClient_PlainAgentRunOptions_PreservesContinuationToken_Async()
+    {
+        // ContinuationToken is the fourth base AgentRunOptions property copied by CopyBaseAgentRunOptions
+        // and is not exercised by AutoWireChatClient_PlainAgentRunOptions_PreservesBaseProperties_Async.
+        AgentRunOptions? observedOptions = null;
+        var fakeChatClient = new AutoWireTestChatClient();
+        var innerChatClientAgent = new ChatClientAgent(fakeChatClient);
+
+        var wrapper = new TestAIAgent
+        {
+            GetServiceFunc = (type, key) =>
+                type == typeof(ChatClientAgent) ? innerChatClientAgent : null,
+            RunAsyncFunc = (messages, session, options, ct) =>
+            {
+                observedOptions = options;
+                return Task.FromResult(new AgentResponse(new ChatMessage(ChatRole.Assistant, "ok")));
+            },
+        };
+
+        using var agent = new OpenTelemetryAgent(wrapper);
+
+        var token = ResponseContinuationToken.FromBytes(new byte[] { 1, 2, 3 });
+        var inputOptions = new AgentRunOptions
+        {
+            ContinuationToken = token,
+        };
+
+        _ = await agent.RunAsync("hi", options: inputOptions);
+
+        Assert.NotNull(observedOptions);
+        Assert.IsType<ChatClientAgentRunOptions>(observedOptions);
+        Assert.Same(token, observedOptions!.ContinuationToken);
+    }
+#pragma warning restore MEAI001
+
+    [Fact]
+    public async Task AutoWireChatClient_ChatClientAgentRunOptions_NoUserFactory_PreservesChatOptions_Async()
+    {
+        // When the caller passes a ChatClientAgentRunOptions without a ChatClientFactory, the auto-wiring
+        // must clone (not mutate) the caller's options, set the factory, and preserve nested ChatOptions.
+        var sourceName = Guid.NewGuid().ToString();
+        var activities = new List<Activity>();
+        using var tracerProvider = OpenTelemetry.Sdk.CreateTracerProviderBuilder()
+            .AddSource(sourceName)
+            .AddInMemoryExporter(activities)
+            .Build();
+
+        ChatOptions? observedChatOptions = null;
+        var fakeChatClient = new AutoWireTestChatClient
+        {
+            OnGetResponseAsync = (msgs, opts) => observedChatOptions = opts,
+        };
+        var inner = new ChatClientAgent(fakeChatClient);
+        using var agent = new OpenTelemetryAgent(inner, sourceName);
+
+        var inputChatOptions = new ChatOptions { Temperature = 0.42f, ModelId = "test-model" };
+        var inputOptions = new ChatClientAgentRunOptions(inputChatOptions);
+
+        _ = await agent.RunAsync("hi", options: inputOptions);
+
+        // Caller's options must not have been mutated (no factory installed on the caller's instance).
+        Assert.Null(inputOptions.ChatClientFactory);
+
+        // Inner chat client must observe the caller-supplied ChatOptions.
+        Assert.NotNull(observedChatOptions);
+        Assert.Equal(0.42f, observedChatOptions!.Temperature);
+        Assert.Equal("test-model", observedChatOptions.ModelId);
+
+        // Auto-wiring still produces a chat span.
+        Assert.Equal(2, activities.Count);
+        Assert.Contains(activities, a => string.Equals(a.GetTagItem("gen_ai.operation.name") as string, "chat", StringComparison.Ordinal));
+    }
+
+    [Fact]
+    public async Task AutoWireChatClient_StreamingDisabled_DoesNotEmitChatSpan_Async()
+    {
+        // Symmetry with AutoWireChatClient_Disabled_DoesNotEmitChatSpan_Async for the streaming path.
+        var sourceName = Guid.NewGuid().ToString();
+        var activities = new List<Activity>();
+        using var tracerProvider = OpenTelemetry.Sdk.CreateTracerProviderBuilder()
+            .AddSource(sourceName)
+            .AddInMemoryExporter(activities)
+            .Build();
+
+        var fakeChatClient = new AutoWireTestChatClient();
+        var inner = new ChatClientAgent(fakeChatClient);
+        using var agent = new OpenTelemetryAgent(inner, sourceName, autoWireChatClient: false);
+
+        await foreach (var _ in agent.RunStreamingAsync("hi"))
+        {
+        }
+
+        var activity = Assert.Single(activities);
+        Assert.StartsWith("invoke_agent", activity.DisplayName);
+    }
+
+    [Fact]
+    public async Task AutoWireChatClient_PlainAgentRunOptions_RealChatClientAgent_EmitsChatSpan_Async()
+    {
+        // High-level callers may pass the abstract base AgentRunOptions (not ChatClientAgentRunOptions) when
+        // wiring a ChatClientAgent. Auto-wiring must still kick in: convert to ChatClientAgentRunOptions,
+        // install the OTel-wrapping factory, and produce both the invoke_agent and chat spans end-to-end.
+        var sourceName = Guid.NewGuid().ToString();
+        var activities = new List<Activity>();
+        using var tracerProvider = OpenTelemetry.Sdk.CreateTracerProviderBuilder()
+            .AddSource(sourceName)
+            .AddInMemoryExporter(activities)
+            .Build();
+
+        ChatOptions? observedChatOptions = null;
+        var fakeChatClient = new AutoWireTestChatClient
+        {
+            OnGetResponseAsync = (_, opts) => observedChatOptions = opts,
+        };
+        var inner = new ChatClientAgent(fakeChatClient);
+        using var agent = new OpenTelemetryAgent(inner, sourceName);
+
+        // Pass the base AgentRunOptions, not ChatClientAgentRunOptions.
+        var inputOptions = new AgentRunOptions { AllowBackgroundResponses = false };
+
+        _ = await agent.RunAsync("hi", options: inputOptions);
+
+        // Inner chat client was actually invoked (auto-wired factory ran without breaking the pipeline).
+        Assert.NotNull(observedChatOptions);
+
+        Assert.Equal(2, activities.Count);
+        Assert.Contains(activities, a => a.DisplayName.StartsWith("invoke_agent", StringComparison.Ordinal));
+        Assert.Contains(activities, a => string.Equals(a.GetTagItem("gen_ai.operation.name") as string, "chat", StringComparison.Ordinal));
+    }
+
+    [Fact]
+    public async Task AutoWireChatClient_PlainAgentRunOptions_RealChatClientAgent_StreamingEmitsChatSpan_Async()
+    {
+        // Same as the sync test above but for the streaming path so both invocation paths
+        // are covered when callers pass a base AgentRunOptions.
+        var sourceName = Guid.NewGuid().ToString();
+        var activities = new List<Activity>();
+        using var tracerProvider = OpenTelemetry.Sdk.CreateTracerProviderBuilder()
+            .AddSource(sourceName)
+            .AddInMemoryExporter(activities)
+            .Build();
+
+        ChatOptions? observedChatOptions = null;
+        var fakeChatClient = new AutoWireTestChatClient
+        {
+            OnGetResponseAsync = (_, opts) => observedChatOptions = opts,
+        };
+        var inner = new ChatClientAgent(fakeChatClient);
+        using var agent = new OpenTelemetryAgent(inner, sourceName);
+
+        var inputOptions = new AgentRunOptions { AllowBackgroundResponses = false };
+
+        await foreach (var _ in agent.RunStreamingAsync("hi", options: inputOptions))
+        {
+        }
+
+        Assert.NotNull(observedChatOptions);
+
+        Assert.Equal(2, activities.Count);
+        Assert.Contains(activities, a => a.DisplayName.StartsWith("invoke_agent", StringComparison.Ordinal));
+        Assert.Contains(activities, a => string.Equals(a.GetTagItem("gen_ai.operation.name") as string, "chat", StringComparison.Ordinal));
+    }
+
+    private sealed class AutoWireTestChatClient : IChatClient
+    {
+        public Action<IEnumerable<ChatMessage>, ChatOptions?>? OnGetResponseAsync { get; set; }
+
+        public Task<ChatResponse> GetResponseAsync(IEnumerable<ChatMessage> messages, ChatOptions? options = null, CancellationToken cancellationToken = default)
+        {
+            this.OnGetResponseAsync?.Invoke(messages, options);
+            return Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, "ok")));
+        }
+
+        public async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(IEnumerable<ChatMessage> messages, ChatOptions? options = null, [EnumeratorCancellation] CancellationToken cancellationToken = default)
+        {
+            this.OnGetResponseAsync?.Invoke(messages, options);
+            await Task.Yield();
+            yield return new ChatResponseUpdate(ChatRole.Assistant, "ok");
+        }
+
+        public object? GetService(Type serviceType, object? serviceKey = null) =>
+            serviceType?.IsInstanceOfType(this) == true ? this : null;
+
+        public void Dispose() { }
+    }
+
+    #endregion
 }

dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.Mcp.UnitTests/DefaultMcpToolHandlerTests.cs

@@ -4,6 +4,7 @@ using System;
 using System.Collections.Generic;
 using System.Net.Http;
 using System.Text;
+using System.Text.Json;
 using System.Threading;
 using System.Threading.Tasks;
 using FluentAssertions;
@@ -320,6 +321,92 @@ public sealed class DefaultMcpToolHandlerTests
 
     #endregion
 
+    #region Reserved Tools/List Tests
+
+    [Fact]
+    public void IsListToolsToolName_WithReservedName_ShouldReturnTrue()
+    {
+        // Act
+        bool result = DefaultMcpToolHandler.IsListToolsToolName(DefaultMcpToolHandler.ListToolsToolName);
+
+        // Assert
+        result.Should().BeTrue();
+    }
+
+    [Fact]
+    public void IsListToolsToolName_WithRegularToolName_ShouldReturnFalse()
+    {
+        // Act
+        bool result = DefaultMcpToolHandler.IsListToolsToolName("search");
+
+        // Assert
+        result.Should().BeFalse();
+    }
+
+    [Fact]
+    public async Task InvokeToolAsync_WithListToolsArguments_ShouldThrowArgumentExceptionAsync()
+    {
+        // Arrange
+        DefaultMcpToolHandler handler = new();
+
+        try
+        {
+            // Act
+            Func<Task> act = async () => await handler.InvokeToolAsync(
+                serverUrl: "http://localhost:12345/mcp",
+                serverLabel: "test",
+                toolName: DefaultMcpToolHandler.ListToolsToolName,
+                arguments: new Dictionary<string, object?> { ["ignored"] = true },
+                headers: null,
+                connectionName: null);
+
+            // Assert
+            await act.Should().ThrowAsync<ArgumentException>()
+                .WithMessage("*does not accept tool arguments*");
+        }
+        finally
+        {
+            await handler.DisposeAsync();
+        }
+    }
+
+    [Fact]
+    public async Task CreateListToolsResultContent_WithTools_ShouldSerializeToolMetadataAsync()
+    {
+        // Arrange
+        JsonElement inputSchema = JsonSerializer.Deserialize<JsonElement>(
+            """
+            {
+              "type": "object",
+              "properties": {
+                "query": {
+                  "type": "string"
+                }
+              },
+              "required": [ "query" ]
+            }
+            """);
+        Tool tool = new()
+        {
+            Name = "search",
+            Description = "Searches documentation.",
+            InputSchema = inputSchema
+        };
+
+        // Act
+        McpServerToolResultContent result = DefaultMcpToolHandler.CreateListToolsResultContent([tool]);
+
+        // Assert
+        TextContent text = result.Outputs.Should().ContainSingle().Subject.Should().BeOfType<TextContent>().Subject;
+        using JsonDocument document = JsonDocument.Parse(text.Text);
+        JsonElement listedTool = document.RootElement.GetProperty("tools")[0];
+        listedTool.GetProperty("name").GetString().Should().Be("search");
+        listedTool.GetProperty("description").GetString().Should().Be("Searches documentation.");
+        listedTool.GetProperty("inputSchema").GetProperty("properties").GetProperty("query").GetProperty("type").GetString().Should().Be("string");
+    }
+
+    #endregion
+
     #region Interface Implementation Tests
 
     [Fact]
@@ -488,5 +575,75 @@ public sealed class DefaultMcpToolHandlerTests
         dataContent.MediaType.Should().Be("audio/*");
     }
 
+    [Fact]
+    public void ConvertContentBlock_EmbeddedResourceBlock_WithTextResource_ShouldReturnTextContent()
+    {
+        // Arrange
+        EmbeddedResourceBlock block = new()
+        {
+            Resource = new TextResourceContents
+            {
+                Text = "embedded text payload",
+                Uri = "resource://example",
+                MimeType = "text/plain",
+            },
+        };
+
+        // Act
+        AIContent result = DefaultMcpToolHandler.ConvertContentBlock(block);
+
+        // Assert
+        result.Should().BeOfType<TextContent>()
+            .Which.Text.Should().Be("embedded text payload");
+    }
+
+    [Fact]
+    public void ConvertContentBlock_EmbeddedResourceBlock_WithBlobResource_ShouldReturnDataContent()
+    {
+        // Arrange
+        byte[] base64Bytes = Encoding.UTF8.GetBytes("UklGRiQA");
+        EmbeddedResourceBlock block = new()
+        {
+            Resource = new BlobResourceContents
+            {
+                Blob = new ReadOnlyMemory<byte>(base64Bytes),
+                Uri = "resource://example.bin",
+                MimeType = "application/zip",
+            },
+        };
+
+        // Act
+        AIContent result = DefaultMcpToolHandler.ConvertContentBlock(block);
+
+        // Assert
+        DataContent dataContent = result.Should().BeOfType<DataContent>().Subject;
+        dataContent.MediaType.Should().Be("application/zip");
+        dataContent.Uri.Should().Be("data:application/zip;base64,UklGRiQA");
+    }
+
+    [Fact]
+    public void ConvertContentBlock_EmbeddedResourceBlock_WithBlobResource_NullMimeType_DefaultsToOctetStream()
+    {
+        // Arrange
+        byte[] base64Bytes = Encoding.UTF8.GetBytes("UklGRiQA");
+        EmbeddedResourceBlock block = new()
+        {
+            Resource = new BlobResourceContents
+            {
+                Blob = new ReadOnlyMemory<byte>(base64Bytes),
+                Uri = "resource://example.bin",
+                MimeType = null!,
+            },
+        };
+
+        // Act
+        AIContent result = DefaultMcpToolHandler.ConvertContentBlock(block);
+
+        // Assert
+        DataContent dataContent = result.Should().BeOfType<DataContent>().Subject;
+        dataContent.MediaType.Should().Be("application/octet-stream");
+        dataContent.Uri.Should().Be("data:application/octet-stream;base64,UklGRiQA");
+    }
+
     #endregion
 }

dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/ObjectModel/InvokeMcpToolExecutorTest.cs

@@ -432,6 +432,44 @@ public sealed class InvokeMcpToolExecutorTest(ITestOutputHelper output) : Workfl
         VerifyInvocationEvent(events);
     }
 
+    [Fact]
+    public async Task InvokeMcpToolExecuteWithReservedListToolsNameAsync()
+    {
+        // Arrange
+        this.State.InitializeSystem();
+        const string ListToolsToolName = "tools/list";
+        string? capturedToolName = null;
+        InvokeMcpTool model = this.CreateModel(
+            displayName: nameof(InvokeMcpToolExecuteWithReservedListToolsNameAsync),
+            serverUrl: TestServerUrl,
+            toolName: ListToolsToolName);
+        Mock<IMcpToolHandler> mockProvider = new();
+        mockProvider.Setup(provider => provider.InvokeToolAsync(
+                It.IsAny<string>(),
+                It.IsAny<string?>(),
+                It.IsAny<string>(),
+                It.IsAny<IDictionary<string, object?>?>(),
+                It.IsAny<IDictionary<string, string>?>(),
+                It.IsAny<string?>(),
+                It.IsAny<CancellationToken>()))
+            .Callback<string, string?, string, IDictionary<string, object?>?, IDictionary<string, string>?, string?, CancellationToken>(
+                (_, _, toolName, _, _, _, _) => capturedToolName = toolName)
+            .ReturnsAsync(new McpServerToolResultContent("list-tools-call-id")
+            {
+                Outputs = [new TextContent("{\"tools\":[]}")]
+            });
+        MockAgentProvider mockAgentProvider = new();
+        InvokeMcpToolExecutor action = new(model, mockProvider.Object, mockAgentProvider.Object, this.State);
+
+        // Act
+        WorkflowEvent[] events = await this.ExecuteAsync(action, isDiscrete: false);
+
+        // Assert
+        VerifyModel(model, action);
+        VerifyInvocationEvent(events);
+        Assert.Equal(ListToolsToolName, capturedToolName);
+    }
+
     [Fact]
     public async Task InvokeMcpToolExecuteWithMultipleContentTypesAsync()
     {

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/AIAgentsAbstractionsExtensionsTests.cs

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.Workflows.UnitTests;
+
+public class AIAgentsAbstractionsExtensionsTests
+{
+    [Fact]
+    public void CopyWithAssistantToUserForOtherParticipants_DoesNotMutateOriginalMessages()
+    {
+        ChatMessage original = new(ChatRole.Assistant, "from first agent")
+        {
+            AuthorName = "firstAgent"
+        };
+
+        List<ChatMessage> copied = new[] { original }
+            .CopyWithAssistantToUserForOtherParticipants("secondAgent");
+
+        Assert.Single(copied);
+        Assert.Equal(ChatRole.Assistant, original.Role);
+        Assert.Equal(ChatRole.User, copied[0].Role);
+        Assert.NotSame(original, copied[0]);
+    }
+}

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/HandoffOrchestrationTests.cs

@@ -86,6 +86,23 @@ public class HandoffOrchestrationTests
         target.Reason.Should().Be("instructions");
     }
 
+    [Fact]
+    public void BuildHandoffs_WithNameAndDescription_SetsWorkflowMetadata()
+    {
+        const string WorkflowName = "handoff-workflow";
+        const string WorkflowDescription = "A handoff workflow";
+
+        DoubleEchoAgent agent = new("agent");
+
+        var workflow = AgentWorkflowBuilder.CreateHandoffBuilderWith(agent)
+            .WithName(WorkflowName)
+            .WithDescription(WorkflowDescription)
+            .Build();
+
+        Assert.Equal(WorkflowName, workflow.Name);
+        Assert.Equal(WorkflowDescription, workflow.Description);
+    }
+
     [Fact]
     public async Task Handoffs_NoTransfers_ResponseServedByOriginalAgentAsync()
     {
@@ -209,6 +226,36 @@ public class HandoffOrchestrationTests
         Assert.DoesNotContain(capturedNextAgentMessages, m => m.Role == ChatRole.Tool && m.Contents.Any(c => c is FunctionResultContent frc && frc.Result?.ToString() == "Transferred."));
     }
 
+    [Fact]
+    public async Task Handoffs_ReassignedMessagesDoNotMutateSharedConversationAsync()
+    {
+        var firstAgent = new ChatClientAgent(new MockChatClient((_, options) =>
+        {
+            string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
+            Assert.NotNull(transferFuncName);
+
+            return new ChatResponse([
+                new ChatMessage(ChatRole.Assistant, "Context from first agent"),
+                new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call1", transferFuncName)]),
+            ]);
+        }), name: "firstAgent");
+        CapturingAgent secondAgent = new("secondAgent", "The second agent", "Context from first agent");
+
+        var workflow =
+            AgentWorkflowBuilder.CreateHandoffBuilderWith(firstAgent)
+            .WithHandoff(firstAgent, secondAgent)
+            .Build();
+
+        (_, List<ChatMessage>? result, _, _) = await RunWorkflowAsync(workflow, [new ChatMessage(ChatRole.User, "start")]);
+
+        Assert.NotNull(result);
+        Assert.Equal(ChatRole.User, secondAgent.RoleSeenDuringRun);
+
+        ChatMessage sharedMessage = Assert.Single(result, m => m.Text == "Context from first agent");
+        Assert.Equal(ChatRole.Assistant, sharedMessage.Role);
+        Assert.NotSame(sharedMessage, secondAgent.MessageSeenDuringRun);
+    }
+
     [Fact]
     public async Task Handoffs_TwoTransfers_HandoffTargetsDoNotReceiveHandoffFunctionMessagesAsync()
     {
@@ -1198,6 +1245,44 @@ public class HandoffOrchestrationTests
         Workflow workflow, List<ChatMessage> input, ExecutionEnvironment executionEnvironment = ExecutionEnvironment.InProcess_Lockstep)
         => RunWorkflowCheckpointedAsync(workflow, input, executionEnvironment.ToWorkflowExecutionEnvironment());
 
+    private sealed class CapturingAgent(string name, string description, string textToCapture) : AIAgent
+    {
+        public override string Name => name;
+        public override string Description => description;
+        public ChatMessage? MessageSeenDuringRun { get; private set; }
+        public ChatRole? RoleSeenDuringRun { get; private set; }
+
+        protected override ValueTask<AgentSession> CreateSessionCoreAsync(CancellationToken cancellationToken = default)
+            => new(new TestAgentSession());
+
+        protected override ValueTask<AgentSession> DeserializeSessionCoreAsync(JsonElement serializedState, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
+            => new(new TestAgentSession());
+
+        protected override ValueTask<JsonElement> SerializeSessionCoreAsync(AgentSession session, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
+            => default;
+
+        protected override Task<AgentResponse> RunCoreAsync(
+            IEnumerable<ChatMessage> messages, AgentSession? session = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default) =>
+            throw new NotImplementedException();
+
+        protected override async IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(
+            IEnumerable<ChatMessage> messages, AgentSession? session = null, AgentRunOptions? options = null, [EnumeratorCancellation] CancellationToken cancellationToken = default)
+        {
+            await Task.Yield();
+
+            this.MessageSeenDuringRun = messages.Single(m => m.Text == textToCapture);
+            this.RoleSeenDuringRun = this.MessageSeenDuringRun.Role;
+
+            yield return new AgentResponseUpdate(ChatRole.Assistant, "Done")
+            {
+                AuthorName = this.Name,
+                MessageId = Guid.NewGuid().ToString("N"),
+            };
+        }
+    }
+
+    private sealed class TestAgentSession() : AgentSession();
+
     private sealed class DoubleEchoAgent(string name) : AIAgent
     {
         public override string Name => name;

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/InputWaiterAndOutputFilterTests.cs

@@ -34,15 +34,26 @@ public sealed class InputWaiterTests : IDisposable
     [Fact]
     public async Task InputWaiter_WaitForInputAsync_BlocksUntilSignaledAsync()
     {
-        Task waitTask = this._waiter.WaitForInputAsync(TimeSpan.FromSeconds(5));
+        // Use the no-timeout overload so that the wait can only be released by SignalInput.
+        // A finite timeout would make this test's logic racy: the component correctly
+        // honors the timeout, but if the test thread is starved of CPU time (CI load,
+        // GC pause) long enough for the timeout to fire, waitTask completes before
+        // SignalInput is called and the "should not complete before signaled" assertion
+        // flakes. Timeout behavior is covered separately below.
+        Task waitTask = this._waiter.WaitForInputAsync(CancellationToken.None);
 
-        await Task.Delay(50);
-        waitTask.IsCompleted.Should().BeFalse("the waiter should block until input is signaled");
+        Task completedBeforeSignal = await Task.WhenAny(waitTask, Task.Delay(100));
+        completedBeforeSignal.Should().NotBeSameAs(
+            waitTask,
+            "the waiter should not complete before input is signaled");
 
         this._waiter.SignalInput();
 
-        Task completed = await Task.WhenAny(waitTask, Task.Delay(TimeSpan.FromSeconds(1)));
-        completed.Should().BeSameAs(waitTask, "the wait task should complete after being signaled");
+        Task completedAfterSignal = await Task.WhenAny(waitTask, Task.Delay(TimeSpan.FromSeconds(1)));
+        completedAfterSignal.Should().BeSameAs(
+            waitTask,
+            "the wait task should complete after being signaled");
+
         await waitTask;
     }
 
@@ -95,6 +106,21 @@ public sealed class InputWaiterTests : IDisposable
         this._waiter.SignalInput();
         await this._waiter.WaitForInputAsync(TimeSpan.FromSeconds(1));
     }
+
+    [Fact]
+    public async Task InputWaiter_WaitForInputAsync_CompletesWhenTimeoutExpiresAsync()
+    {
+        // Verify that a finite timeout releases the block even without a signal.
+        // We only assert that it *does* complete (within a generous outer bound);
+        // we intentionally do not assert that it stays blocked until the timeout,
+        // because that would re-introduce the same wall-clock flakiness
+        // described in BlocksUntilSignaledAsync (see comment on that test).
+        Task waitTask = this._waiter.WaitForInputAsync(TimeSpan.FromMilliseconds(300));
+
+        Task completed = await Task.WhenAny(waitTask, Task.Delay(TimeSpan.FromSeconds(5)));
+        completed.Should().BeSameAs(waitTask, "the wait task should complete once the timeout expires");
+        await waitTask;
+    }
 }
 
 public class OutputFilterTests

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/ObservabilityTests.cs

@@ -133,31 +133,31 @@ public sealed class ObservabilityTests : IDisposable
         activityEvents.Should().Contain(e => e.Name == EventNames.WorkflowCompleted, "activity should have workflow completed event");
     }
 
-    [Fact(Skip = "Flaky test - temporarily disabled.")]
+    [Fact]
     public async Task CreatesWorkflowEndToEndActivities_WithCorrectName_DefaultAsync()
     {
         await this.TestWorkflowEndToEndActivitiesAsync("Default");
     }
 
-    [Fact(Skip = "Flaky test - temporarily disabled.")]
+    [Fact]
     public async Task CreatesWorkflowEndToEndActivities_WithCorrectName_OffThreadAsync()
     {
         await this.TestWorkflowEndToEndActivitiesAsync("OffThread");
     }
 
-    [Fact(Skip = "Flaky test - temporarily disabled.")]
+    [Fact]
     public async Task CreatesWorkflowEndToEndActivities_WithCorrectName_ConcurrentAsync()
     {
         await this.TestWorkflowEndToEndActivitiesAsync("Concurrent");
     }
 
-    [Fact(Skip = "Flaky test - temporarily disabled.")]
+    [Fact]
     public async Task CreatesWorkflowEndToEndActivities_WithCorrectName_LockstepAsync()
     {
         await this.TestWorkflowEndToEndActivitiesAsync("Lockstep");
     }
 
-    [Fact(Skip = "Flaky test - temporarily disabled.")]
+    [Fact]
     public async Task CreatesWorkflowActivities_WithCorrectNameAsync()
     {
         // Arrange
@@ -182,7 +182,7 @@ public sealed class ObservabilityTests : IDisposable
         tags.Should().ContainKey(Tags.WorkflowDefinition);
     }
 
-    [Fact(Skip = "Flaky test - temporarily disabled.")]
+    [Fact]
     public async Task TelemetryDisabledByDefault_CreatesNoActivitiesAsync()
     {
         // Arrange
@@ -200,7 +200,7 @@ public sealed class ObservabilityTests : IDisposable
         capturedActivities.Should().BeEmpty("No activities should be created when telemetry is disabled (default).");
     }
 
-    [Fact(Skip = "Flaky test - temporarily disabled.")]
+    [Fact]
     public async Task WithOpenTelemetry_UsesProvidedActivitySourceAsync()
     {
         // Arrange
@@ -235,7 +235,7 @@ public sealed class ObservabilityTests : IDisposable
             "All activities should come from the user-provided ActivitySource.");
     }
 
-    [Fact(Skip = "Flaky test - temporarily disabled.")]
+    [Fact]
     public async Task DisableWorkflowBuild_PreventsWorkflowBuildActivityAsync()
     {
         // Arrange
@@ -255,7 +255,7 @@ public sealed class ObservabilityTests : IDisposable
             "WorkflowBuild activity should be disabled.");
     }
 
-    [Fact(Skip = "Flaky test - temporarily disabled.")]
+    [Fact]
     public async Task DisableWorkflowRun_PreventsWorkflowRunActivityAsync()
     {
         // Arrange
@@ -285,7 +285,7 @@ public sealed class ObservabilityTests : IDisposable
             "Other activities should still be created.");
     }
 
-    [Fact(Skip = "Flaky test - temporarily disabled.")]
+    [Fact]
     public async Task DisableExecutorProcess_PreventsExecutorProcessActivityAsync()
     {
         // Arrange
@@ -312,7 +312,7 @@ public sealed class ObservabilityTests : IDisposable
             "Other activities should still be created.");
     }
 
-    [Fact(Skip = "Flaky test - temporarily disabled.")]
+    [Fact]
     public async Task DisableEdgeGroupProcess_PreventsEdgeGroupProcessActivityAsync()
     {
         // Arrange
@@ -333,7 +333,7 @@ public sealed class ObservabilityTests : IDisposable
             "Other activities should still be created.");
     }
 
-    [Fact(Skip = "Flaky test - temporarily disabled.")]
+    [Fact]
     public async Task DisableMessageSend_PreventsMessageSendActivityAsync()
     {
         // Arrange
@@ -382,7 +382,7 @@ public sealed class ObservabilityTests : IDisposable
         return builder.WithOpenTelemetry(configure: opts => opts.DisableMessageSend = true).Build();
     }
 
-    [Fact(Skip = "Flaky test - temporarily disabled.")]
+    [Fact]
     public async Task EnableSensitiveData_LogsExecutorInputAndOutputAsync()
     {
         // Arrange
@@ -413,7 +413,7 @@ public sealed class ObservabilityTests : IDisposable
         tags[Tags.ExecutorOutput].Should().Contain("HELLO", "Output should contain the transformed value.");
     }
 
-    [Fact(Skip = "Flaky test - temporarily disabled.")]
+    [Fact]
     public async Task EnableSensitiveData_Disabled_DoesNotLogInputOutputAsync()
     {
         // Arrange
@@ -442,7 +442,7 @@ public sealed class ObservabilityTests : IDisposable
         tags.Should().NotContainKey(Tags.ExecutorOutput, "Output should NOT be logged when EnableSensitiveData is false.");
     }
 
-    [Fact(Skip = "Flaky test - temporarily disabled.")]
+    [Fact]
     public async Task EnableSensitiveData_LogsMessageSendContentAsync()
     {
         // Arrange
@@ -474,7 +474,7 @@ public sealed class ObservabilityTests : IDisposable
         tags.Should().ContainKey(Tags.MessageSourceId, "Source ID should be logged.");
     }
 
-    [Fact(Skip = "Flaky test - temporarily disabled.")]
+    [Fact]
     public async Task EnableSensitiveData_Disabled_DoesNotLogMessageContentAsync()
     {
         // Arrange

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/RouteBuilderTests.cs

@@ -0,0 +1,546 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using FluentAssertions;
+using Microsoft.Agents.AI.Workflows.Execution;
+
+namespace Microsoft.Agents.AI.Workflows.UnitTests;
+
+public sealed class RouteBuilderTests
+{
+    public enum HandlerOverload
+    {
+        SyncWithCancellation = 0,
+        SyncWithoutCancellation = 1,
+        AsyncWithCancellation = 2,
+        AsyncWithoutCancellation = 3,
+    }
+
+    private sealed record TestPayload(string Value);
+
+    private sealed class HandlerInvocation
+    {
+        public object? Message { get; private set; }
+
+        public IWorkflowContext? Context { get; private set; }
+
+        public CancellationToken CancellationToken { get; private set; }
+
+        public int InvocationCount { get; private set; }
+
+        public void Capture(object? message, IWorkflowContext context, CancellationToken cancellationToken = default)
+        {
+            this.Message = message;
+            this.Context = context;
+            this.CancellationToken = cancellationToken;
+            this.InvocationCount++;
+        }
+    }
+
+    private sealed class TestExternalRequestContext : IExternalRequestContext, IExternalRequestSink
+    {
+        public List<RequestPort> RegisteredPorts { get; } = [];
+
+        public List<ExternalRequest> PostedRequests { get; } = [];
+
+        public IExternalRequestSink RegisterPort(RequestPort port)
+        {
+            this.RegisteredPorts.Add(port);
+            return this;
+        }
+
+        public ValueTask PostAsync(ExternalRequest request)
+        {
+            this.PostedRequests.Add(request);
+            return default;
+        }
+    }
+
+    [Theory]
+    [InlineData(HandlerOverload.SyncWithCancellation)]
+    [InlineData(HandlerOverload.SyncWithoutCancellation)]
+    [InlineData(HandlerOverload.AsyncWithCancellation)]
+    [InlineData(HandlerOverload.AsyncWithoutCancellation)]
+    public async Task AddHandler_VoidOverloads_RouteExpectedMessageAsync(HandlerOverload overload)
+    {
+        // Arrange
+        RouteBuilder routeBuilder = new(null);
+        HandlerInvocation invocation = new();
+        CancellationToken cancellationToken = new CancellationTokenSource().Token;
+        RegisterVoidHandler(routeBuilder, invocation, overload);
+        MessageRouter router = routeBuilder.Build();
+        TestWorkflowContext context = new("executor");
+
+        // Act
+        CallResult? result = await router.RouteMessageAsync("hello", context, cancellationToken: cancellationToken);
+
+        // Assert
+        result.Should().NotBeNull();
+        result!.IsSuccess.Should().BeTrue();
+        result.IsVoid.Should().BeTrue();
+        result.Result.Should().BeNull();
+        invocation.InvocationCount.Should().Be(1);
+        invocation.Message.Should().Be("hello");
+        invocation.Context.Should().BeSameAs(context);
+
+        if (UsesCancellationToken(overload))
+        {
+            invocation.CancellationToken.Should().Be(cancellationToken);
+        }
+    }
+
+    [Theory]
+    [InlineData(HandlerOverload.SyncWithCancellation)]
+    [InlineData(HandlerOverload.SyncWithoutCancellation)]
+    [InlineData(HandlerOverload.AsyncWithCancellation)]
+    [InlineData(HandlerOverload.AsyncWithoutCancellation)]
+    public async Task AddHandler_ResultOverloads_RouteExpectedMessageAsync(HandlerOverload overload)
+    {
+        // Arrange
+        RouteBuilder routeBuilder = new(null);
+        HandlerInvocation invocation = new();
+        CancellationToken cancellationToken = new CancellationTokenSource().Token;
+        RegisterResultHandler(routeBuilder, invocation, overload);
+        MessageRouter router = routeBuilder.Build();
+        TestWorkflowContext context = new("executor");
+
+        // Act
+        CallResult? result = await router.RouteMessageAsync("hello", context, cancellationToken: cancellationToken);
+
+        // Assert
+        result.Should().NotBeNull();
+        result!.IsSuccess.Should().BeTrue();
+        result.IsVoid.Should().BeFalse();
+        result.Result.Should().Be("HELLO");
+        router.DefaultOutputTypes.Should().Contain(typeof(string));
+        invocation.InvocationCount.Should().Be(1);
+        invocation.Message.Should().Be("hello");
+        invocation.Context.Should().BeSameAs(context);
+
+        if (UsesCancellationToken(overload))
+        {
+            invocation.CancellationToken.Should().Be(cancellationToken);
+        }
+    }
+
+    [Theory]
+    [InlineData(HandlerOverload.SyncWithCancellation)]
+    [InlineData(HandlerOverload.SyncWithoutCancellation)]
+    [InlineData(HandlerOverload.AsyncWithCancellation)]
+    [InlineData(HandlerOverload.AsyncWithoutCancellation)]
+    public async Task AddCatchAll_VoidOverloads_RouteUnexpectedMessageAsync(HandlerOverload overload)
+    {
+        // Arrange
+        RouteBuilder routeBuilder = new(null);
+        HandlerInvocation invocation = new();
+        CancellationToken cancellationToken = new CancellationTokenSource().Token;
+        TestPayload payload = new("hello");
+        RegisterVoidCatchAll(routeBuilder, invocation, overload);
+        MessageRouter router = routeBuilder.Build();
+        TestWorkflowContext context = new("executor");
+
+        // Act
+        CallResult? result = await router.RouteMessageAsync(payload, context, cancellationToken: cancellationToken);
+
+        // Assert
+        result.Should().NotBeNull();
+        result!.IsSuccess.Should().BeTrue();
+        result.IsVoid.Should().BeTrue();
+        result.Result.Should().BeNull();
+        invocation.InvocationCount.Should().Be(1);
+        invocation.Message.Should().BeEquivalentTo(new PortableValue(payload));
+        invocation.Context.Should().BeSameAs(context);
+
+        if (UsesCancellationToken(overload))
+        {
+            invocation.CancellationToken.Should().Be(cancellationToken);
+        }
+    }
+
+    [Theory]
+    [InlineData(HandlerOverload.SyncWithCancellation)]
+    [InlineData(HandlerOverload.SyncWithoutCancellation)]
+    [InlineData(HandlerOverload.AsyncWithCancellation)]
+    [InlineData(HandlerOverload.AsyncWithoutCancellation)]
+    public async Task AddCatchAll_ResultOverloads_RouteUnexpectedMessageAsync(HandlerOverload overload)
+    {
+        // Arrange
+        RouteBuilder routeBuilder = new(null);
+        HandlerInvocation invocation = new();
+        CancellationToken cancellationToken = new CancellationTokenSource().Token;
+        TestPayload payload = new("hello");
+        RegisterResultCatchAll(routeBuilder, invocation, overload);
+        MessageRouter router = routeBuilder.Build();
+        TestWorkflowContext context = new("executor");
+
+        // Act
+        CallResult? result = await router.RouteMessageAsync(payload, context, cancellationToken: cancellationToken);
+
+        // Assert
+        result.Should().NotBeNull();
+        result!.IsSuccess.Should().BeTrue();
+        result.IsVoid.Should().BeFalse();
+        result.Result.Should().Be("HELLO");
+        invocation.InvocationCount.Should().Be(1);
+        invocation.Message.Should().BeEquivalentTo(new PortableValue(payload));
+        invocation.Context.Should().BeSameAs(context);
+
+        if (UsesCancellationToken(overload))
+        {
+            invocation.CancellationToken.Should().Be(cancellationToken);
+        }
+    }
+
+    [Fact]
+    public async Task AddHandlerUntyped_VoidAndResultOverloads_RouteExpectedMessageAsync()
+    {
+        // Arrange
+        RouteBuilder routeBuilder = new(null);
+        HandlerInvocation voidInvocation = new();
+        HandlerInvocation resultInvocation = new();
+        CancellationToken cancellationToken = new CancellationTokenSource().Token;
+        routeBuilder.AddHandlerUntyped(typeof(string), (message, context, token) =>
+        {
+            voidInvocation.Capture(message, context, token);
+            return default;
+        });
+        routeBuilder.AddHandlerUntyped<int>(typeof(int), (message, context, token) =>
+        {
+            resultInvocation.Capture(message, context, token);
+            return new((int)message + 1);
+        });
+        MessageRouter router = routeBuilder.Build();
+        TestWorkflowContext context = new("executor");
+
+        // Act
+        CallResult? voidResult = await router.RouteMessageAsync("hello", context, cancellationToken: cancellationToken);
+        CallResult? typedResult = await router.RouteMessageAsync(41, context, cancellationToken: cancellationToken);
+
+        // Assert
+        voidResult.Should().NotBeNull();
+        voidResult!.IsVoid.Should().BeTrue();
+        voidInvocation.Message.Should().Be("hello");
+        voidInvocation.Context.Should().BeSameAs(context);
+        voidInvocation.CancellationToken.Should().Be(cancellationToken);
+
+        typedResult.Should().NotBeNull();
+        typedResult!.Result.Should().Be(42);
+        router.DefaultOutputTypes.Should().Contain(typeof(int));
+        resultInvocation.Message.Should().Be(41);
+        resultInvocation.Context.Should().BeSameAs(context);
+        resultInvocation.CancellationToken.Should().Be(cancellationToken);
+    }
+
+    [Fact]
+    public void AddHandler_ForPortableValue_ThrowsInvalidOperationException()
+    {
+        // Arrange
+        RouteBuilder routeBuilder = new(null);
+
+        // Act
+        Action act = () => routeBuilder.AddHandler<PortableValue>((message, context) => { });
+
+        // Assert
+        act.Should().Throw<InvalidOperationException>()
+           .WithMessage("*Use AddCatchAll()*");
+    }
+
+    [Fact]
+    public void AddHandler_DuplicateRegistrationWithoutOverwrite_ThrowsArgumentException()
+    {
+        // Arrange
+        RouteBuilder routeBuilder = new(null);
+        routeBuilder.AddHandler<string>((message, context) => { });
+
+        // Act
+        Action act = () => routeBuilder.AddHandler<string>((message, context) => { });
+
+        // Assert
+        act.Should().Throw<ArgumentException>()
+           .WithMessage("*already registered*");
+    }
+
+    [Fact]
+    public void AddHandler_OverwriteWithoutExistingRegistration_ThrowsArgumentException()
+    {
+        // Arrange
+        RouteBuilder routeBuilder = new(null);
+
+        // Act
+        Action act = () => routeBuilder.AddHandler<string>((message, context) => { }, overwrite: true);
+
+        // Assert
+        act.Should().Throw<ArgumentException>()
+           .WithMessage("*has not yet been registered*");
+    }
+
+    [Fact]
+    public async Task AddHandler_OverwriteExistingRegistration_RoutesUpdatedHandlerAsync()
+    {
+        // Arrange
+        RouteBuilder routeBuilder = new(null);
+        routeBuilder.AddHandler<string>((message, context) => context.SendMessageAsync("first"));
+        routeBuilder.AddHandler<string>((message, context) => context.SendMessageAsync("second"), overwrite: true);
+        MessageRouter router = routeBuilder.Build();
+        TestWorkflowContext context = new("executor");
+
+        // Act
+        _ = await router.RouteMessageAsync("hello", context);
+
+        // Assert
+        context.SentMessages.Should().ContainSingle().Which.Should().Be("second");
+    }
+
+    [Fact]
+    public void AddCatchAll_DuplicateRegistrationWithoutOverwrite_ThrowsInvalidOperationException()
+    {
+        // Arrange
+        RouteBuilder routeBuilder = new(null);
+        routeBuilder.AddCatchAll((message, context) => { });
+
+        // Act
+        Action act = () => routeBuilder.AddCatchAll((message, context) => { });
+
+        // Assert
+        act.Should().Throw<InvalidOperationException>()
+           .WithMessage("*already registered*");
+    }
+
+    [Fact]
+    public async Task AddCatchAll_OverwriteExistingRegistration_RoutesUpdatedHandlerAsync()
+    {
+        // Arrange
+        RouteBuilder routeBuilder = new(null);
+        routeBuilder.AddCatchAll((message, context) => context.SendMessageAsync("first"));
+        routeBuilder.AddCatchAll((message, context) => context.SendMessageAsync("second"), overwrite: true);
+        MessageRouter router = routeBuilder.Build();
+        TestWorkflowContext context = new("executor");
+
+        // Act
+        _ = await router.RouteMessageAsync(new TestPayload("hello"), context);
+
+        // Assert
+        context.SentMessages.Should().ContainSingle().Which.Should().Be("second");
+    }
+
+    [Fact]
+    public void AddPortHandler_WithoutExternalRequestContext_ThrowsInvalidOperationException()
+    {
+        // Arrange
+        RouteBuilder routeBuilder = new(null);
+
+        // Act
+        Action act = () => routeBuilder.AddPortHandler<string, int>("port", (response, context, cancellationToken) => default, out _);
+
+        // Assert
+        act.Should().Throw<InvalidOperationException>()
+           .WithMessage("*external request context is required*");
+    }
+
+    [Fact]
+    public async Task AddPortHandler_RoutesMatchingExternalResponseAsync()
+    {
+        // Arrange
+        TestExternalRequestContext externalRequestContext = new();
+        RouteBuilder routeBuilder = new(externalRequestContext);
+        HandlerInvocation invocation = new();
+        routeBuilder.AddPortHandler<string, int>("port", (response, context, cancellationToken) =>
+        {
+            invocation.Capture(response, context, cancellationToken);
+            return default;
+        }, out PortBinding portBinding);
+        await portBinding.PostRequestAsync("request", requestId: "req-1");
+        MessageRouter router = routeBuilder.Build();
+        TestWorkflowContext context = new("executor");
+        CancellationToken cancellationToken = new CancellationTokenSource().Token;
+        ExternalResponse response = externalRequestContext.PostedRequests.Single().CreateResponse(42);
+
+        // Act
+        CallResult? result = await router.RouteMessageAsync(response, context, cancellationToken: cancellationToken);
+
+        // Assert
+        externalRequestContext.RegisteredPorts.Should().ContainSingle(port => port.Id == "port");
+        externalRequestContext.PostedRequests.Should().ContainSingle(request => request.RequestId == "req-1");
+        result.Should().NotBeNull();
+        result!.IsSuccess.Should().BeTrue();
+        result.Result.Should().BeSameAs(response);
+        invocation.InvocationCount.Should().Be(1);
+        invocation.Message.Should().Be(42);
+        invocation.Context.Should().BeSameAs(context);
+        invocation.CancellationToken.Should().Be(cancellationToken);
+    }
+
+    [Fact]
+    public async Task AddPortHandler_UnknownPort_ReturnsExceptionResultAsync()
+    {
+        // Arrange
+        TestExternalRequestContext externalRequestContext = new();
+        RouteBuilder routeBuilder = new(externalRequestContext);
+        routeBuilder.AddPortHandler<string, int>("port", (response, context, cancellationToken) => default, out _);
+        MessageRouter router = routeBuilder.Build();
+        ExternalRequest request = ExternalRequest.Create(RequestPort.Create<string, int>("other"), "request", requestId: "req-1");
+
+        // Act
+        CallResult? result = await router.RouteMessageAsync(request.CreateResponse(42), new TestWorkflowContext("executor"));
+
+        // Assert
+        result.Should().NotBeNull();
+        result!.IsSuccess.Should().BeFalse();
+        result.Exception.Should().BeOfType<InvalidOperationException>();
+        result.Exception!.Message.Should().Contain("Unknown port");
+    }
+
+    private static void RegisterVoidHandler(RouteBuilder routeBuilder, HandlerInvocation invocation, HandlerOverload overload)
+    {
+        switch (overload)
+        {
+            case HandlerOverload.SyncWithCancellation:
+                routeBuilder.AddHandler<string>((message, context, cancellationToken) => invocation.Capture(message, context, cancellationToken));
+                break;
+            case HandlerOverload.SyncWithoutCancellation:
+                routeBuilder.AddHandler<string>((message, context) => invocation.Capture(message, context));
+                break;
+            case HandlerOverload.AsyncWithCancellation:
+                routeBuilder.AddHandler<string>((message, context, cancellationToken) =>
+                {
+                    invocation.Capture(message, context, cancellationToken);
+                    return default;
+                });
+                break;
+            case HandlerOverload.AsyncWithoutCancellation:
+                routeBuilder.AddHandler<string>((message, context) =>
+                {
+                    invocation.Capture(message, context);
+                    return default;
+                });
+                break;
+            default:
+                throw new ArgumentOutOfRangeException(nameof(overload));
+        }
+    }
+
+    private static void RegisterResultHandler(RouteBuilder routeBuilder, HandlerInvocation invocation, HandlerOverload overload)
+    {
+        switch (overload)
+        {
+            case HandlerOverload.SyncWithCancellation:
+                routeBuilder.AddHandler<string, string>((message, context, cancellationToken) =>
+                {
+                    invocation.Capture(message, context, cancellationToken);
+                    return NormalizeHandlerResult(message);
+                });
+                break;
+            case HandlerOverload.SyncWithoutCancellation:
+                routeBuilder.AddHandler<string, string>((message, context) =>
+                {
+                    invocation.Capture(message, context);
+                    return NormalizeHandlerResult(message);
+                });
+                break;
+            case HandlerOverload.AsyncWithCancellation:
+                Func<string, IWorkflowContext, CancellationToken, ValueTask<string>> asyncHandlerWithCancellation = (message, context, cancellationToken) =>
+                {
+                    invocation.Capture(message, context, cancellationToken);
+                    return new ValueTask<string>(NormalizeHandlerResult(message));
+                };
+                routeBuilder.AddHandler(asyncHandlerWithCancellation);
+                break;
+            case HandlerOverload.AsyncWithoutCancellation:
+                Func<string, IWorkflowContext, ValueTask<string>> asyncHandler = (message, context) =>
+                {
+                    invocation.Capture(message, context);
+                    return new ValueTask<string>(NormalizeHandlerResult(message));
+                };
+                routeBuilder.AddHandler(asyncHandler);
+                break;
+            default:
+                throw new ArgumentOutOfRangeException(nameof(overload));
+        }
+    }
+
+    private static void RegisterVoidCatchAll(RouteBuilder routeBuilder, HandlerInvocation invocation, HandlerOverload overload)
+    {
+        switch (overload)
+        {
+            case HandlerOverload.SyncWithCancellation:
+                routeBuilder.AddCatchAll((message, context, cancellationToken) => invocation.Capture(message, context, cancellationToken));
+                break;
+            case HandlerOverload.SyncWithoutCancellation:
+                routeBuilder.AddCatchAll((message, context) => invocation.Capture(message, context));
+                break;
+            case HandlerOverload.AsyncWithCancellation:
+                routeBuilder.AddCatchAll((message, context, cancellationToken) =>
+                {
+                    invocation.Capture(message, context, cancellationToken);
+                    return default;
+                });
+                break;
+            case HandlerOverload.AsyncWithoutCancellation:
+                routeBuilder.AddCatchAll((message, context) =>
+                {
+                    invocation.Capture(message, context);
+                    return default;
+                });
+                break;
+            default:
+                throw new ArgumentOutOfRangeException(nameof(overload));
+        }
+    }
+
+    private static void RegisterResultCatchAll(RouteBuilder routeBuilder, HandlerInvocation invocation, HandlerOverload overload)
+    {
+        switch (overload)
+        {
+            case HandlerOverload.SyncWithCancellation:
+                routeBuilder.AddCatchAll((message, context, cancellationToken) =>
+                {
+                    invocation.Capture(message, context, cancellationToken);
+                    return NormalizeCatchAllResult(message);
+                });
+                break;
+            case HandlerOverload.SyncWithoutCancellation:
+                routeBuilder.AddCatchAll((message, context) =>
+                {
+                    invocation.Capture(message, context);
+                    return NormalizeCatchAllResult(message);
+                });
+                break;
+            case HandlerOverload.AsyncWithCancellation:
+                Func<PortableValue, IWorkflowContext, CancellationToken, ValueTask<string>> asyncCatchAllWithCancellation = (message, context, cancellationToken) =>
+                {
+                    invocation.Capture(message, context, cancellationToken);
+                    return new ValueTask<string>(NormalizeCatchAllResult(message));
+                };
+                routeBuilder.AddCatchAll(asyncCatchAllWithCancellation);
+                break;
+            case HandlerOverload.AsyncWithoutCancellation:
+                Func<PortableValue, IWorkflowContext, ValueTask<string>> asyncCatchAll = (message, context) =>
+                {
+                    invocation.Capture(message, context);
+                    return new ValueTask<string>(NormalizeCatchAllResult(message));
+                };
+                routeBuilder.AddCatchAll(asyncCatchAll);
+                break;
+            default:
+                throw new ArgumentOutOfRangeException(nameof(overload));
+        }
+    }
+
+    private static bool UsesCancellationToken(HandlerOverload overload) =>
+        overload is HandlerOverload.SyncWithCancellation or HandlerOverload.AsyncWithCancellation;
+
+    private static string NormalizeHandlerResult(string message) => message.ToUpperInvariant();
+
+    private static string NormalizeCatchAllResult(PortableValue message) => GetPayloadValue(message).ToUpperInvariant();
+
+    private static string GetPayloadValue(PortableValue message)
+    {
+        return message.As<TestPayload>() is TestPayload payload
+            ? payload.Value
+            : throw new InvalidOperationException("Expected catch-all message payload to deserialize as TestPayload.");
+    }
+}

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/WorkflowBuilderSmokeTests.cs

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System;
+using System.Collections.Generic;
 using FluentAssertions;
 
 namespace Microsoft.Agents.AI.Workflows.UnitTests;
@@ -157,4 +158,301 @@ public partial class WorkflowBuilderSmokeTests
         workflow3.Name.Should().Be("Named Only");
         workflow3.Description.Should().BeNull();
     }
+
+    [Fact]
+    public void ForwardMessage_WithSingleTarget_CreatesDirectEdge()
+    {
+        // Arrange
+        NoOpExecutor source = new("start");
+        NoOpExecutor target = new("target");
+
+        // Act
+        Workflow workflow = new WorkflowBuilder(source.Id)
+            .ForwardMessage<string>(source, target)
+            .Build();
+
+        // Assert
+        Edge edge = GetSingleEdge(workflow, source.Id);
+        edge.Kind.Should().Be(EdgeKind.Direct);
+        edge.DirectEdgeData.Should().NotBeNull();
+        edge.DirectEdgeData!.SourceId.Should().Be(source.Id);
+        edge.DirectEdgeData!.SinkId.Should().Be(target.Id);
+        edge.DirectEdgeData.Condition.Should().NotBeNull();
+        edge.DirectEdgeData.Condition!("message").Should().BeTrue();
+        edge.DirectEdgeData.Condition!(42).Should().BeFalse();
+        edge.DirectEdgeData.Condition!(null).Should().BeFalse();
+    }
+
+    [Fact]
+    public void ForwardMessage_WithMultipleTargets_CreatesFanOutEdge()
+    {
+        // Arrange
+        NoOpExecutor source = new("start");
+        NoOpExecutor target1 = new("target1");
+        NoOpExecutor target2 = new("target2");
+
+        // Act
+        Workflow workflow = new WorkflowBuilder(source.Id)
+            .ForwardMessage<string>(source, [target1, target2], message => message == "match")
+            .Build();
+
+        // Assert
+        Edge edge = GetSingleEdge(workflow, source.Id);
+        edge.Kind.Should().Be(EdgeKind.FanOut);
+        edge.FanOutEdgeData.Should().NotBeNull();
+        edge.FanOutEdgeData!.SourceId.Should().Be(source.Id);
+        edge.FanOutEdgeData!.SinkIds.Should().Equal([target1.Id, target2.Id]);
+        edge.FanOutEdgeData.EdgeAssigner.Should().NotBeNull();
+        edge.FanOutEdgeData.EdgeAssigner!("match", 2).Should().Equal([0, 1]);
+        edge.FanOutEdgeData.EdgeAssigner!("other", 2).Should().BeEmpty();
+        edge.FanOutEdgeData.EdgeAssigner!(42, 2).Should().BeEmpty();
+    }
+
+    [Fact]
+    public void ForwardExcept_WithSingleTarget_CreatesDirectEdge()
+    {
+        // Arrange
+        NoOpExecutor source = new("start");
+        NoOpExecutor target = new("target");
+
+        // Act
+        Workflow workflow = new WorkflowBuilder(source.Id)
+            .ForwardExcept<string>(source, target)
+            .Build();
+
+        // Assert
+        Edge edge = GetSingleEdge(workflow, source.Id);
+        edge.Kind.Should().Be(EdgeKind.Direct);
+        edge.DirectEdgeData.Should().NotBeNull();
+        edge.DirectEdgeData!.SourceId.Should().Be(source.Id);
+        edge.DirectEdgeData!.SinkId.Should().Be(target.Id);
+        edge.DirectEdgeData.Condition.Should().NotBeNull();
+        edge.DirectEdgeData.Condition!("message").Should().BeFalse();
+        edge.DirectEdgeData.Condition!(42).Should().BeTrue();
+        edge.DirectEdgeData.Condition!(null).Should().BeTrue();
+    }
+
+    [Fact]
+    public void ForwardExcept_WithMultipleTargets_CreatesFanOutEdge()
+    {
+        // Arrange
+        NoOpExecutor source = new("start");
+        NoOpExecutor target1 = new("target1");
+        NoOpExecutor target2 = new("target2");
+
+        // Act
+        Workflow workflow = new WorkflowBuilder(source.Id)
+            .ForwardExcept<string>(source, [target1, target2])
+            .Build();
+
+        // Assert
+        Edge edge = GetSingleEdge(workflow, source.Id);
+        edge.Kind.Should().Be(EdgeKind.FanOut);
+        edge.FanOutEdgeData.Should().NotBeNull();
+        edge.FanOutEdgeData!.SourceId.Should().Be(source.Id);
+        edge.FanOutEdgeData!.SinkIds.Should().Equal([target1.Id, target2.Id]);
+        edge.FanOutEdgeData.EdgeAssigner.Should().NotBeNull();
+        edge.FanOutEdgeData.EdgeAssigner!(42, 2).Should().Equal([0, 1]);
+        edge.FanOutEdgeData.EdgeAssigner!("message", 2).Should().BeEmpty();
+    }
+
+    [Fact]
+    public void AddChain_CreatesSequentialDirectEdges()
+    {
+        // Arrange
+        NoOpExecutor source = new("start");
+        NoOpExecutor middle = new("middle");
+        NoOpExecutor end = new("end");
+
+        // Act
+        Workflow workflow = new WorkflowBuilder(source.Id)
+            .AddChain(source, [middle, end])
+            .Build();
+
+        // Assert
+        Edge firstEdge = GetSingleEdge(workflow, source.Id);
+        firstEdge.Kind.Should().Be(EdgeKind.Direct);
+        firstEdge.DirectEdgeData!.SourceId.Should().Be(source.Id);
+        firstEdge.DirectEdgeData.SinkId.Should().Be(middle.Id);
+
+        Edge secondEdge = GetSingleEdge(workflow, middle.Id);
+        secondEdge.Kind.Should().Be(EdgeKind.Direct);
+        secondEdge.DirectEdgeData!.SourceId.Should().Be(middle.Id);
+        secondEdge.DirectEdgeData.SinkId.Should().Be(end.Id);
+    }
+
+    [Fact]
+    public void AddChain_WhenExecutorRepeats_Throws()
+    {
+        // Arrange
+        NoOpExecutor source = new("start");
+        NoOpExecutor middle = new("middle");
+
+        // Act
+        Action act = () => new WorkflowBuilder(source.Id)
+            .AddChain(source, [middle, source]);
+
+        // Assert
+        act.Should().Throw<ArgumentException>()
+            .WithParameterName("executors");
+    }
+
+    [Fact]
+    public void AddExternalCall_CreatesRequestPortAndRoundTripEdges()
+    {
+        // Arrange
+        const string PortId = "port1";
+        NoOpExecutor source = new("start");
+
+        // Act
+        Workflow workflow = new WorkflowBuilder(source.Id)
+            .AddExternalCall<string, int>(source, PortId)
+            .Build();
+
+        // Assert
+        workflow.Ports.Should().ContainKey(PortId);
+        workflow.Ports[PortId].Request.Should().Be(typeof(string));
+        workflow.Ports[PortId].Response.Should().Be(typeof(int));
+        workflow.ExecutorBindings.Should().ContainKey(PortId);
+
+        Edge requestEdge = GetSingleEdge(workflow, source.Id);
+        requestEdge.Kind.Should().Be(EdgeKind.Direct);
+        requestEdge.DirectEdgeData!.SourceId.Should().Be(source.Id);
+        requestEdge.DirectEdgeData.SinkId.Should().Be(PortId);
+
+        Edge responseEdge = GetSingleEdge(workflow, PortId);
+        responseEdge.Kind.Should().Be(EdgeKind.Direct);
+        responseEdge.DirectEdgeData!.SourceId.Should().Be(PortId);
+        responseEdge.DirectEdgeData.SinkId.Should().Be(source.Id);
+    }
+
+    [Fact]
+    public void AddSwitch_CreatesFanOutEdgeWithCasesAndDefault()
+    {
+        // Arrange
+        NoOpExecutor source = new("start");
+        NoOpExecutor stringTarget = new("string-target");
+        NoOpExecutor intTarget = new("int-target");
+        NoOpExecutor defaultTarget = new("default-target");
+
+        // Act
+        Workflow workflow = new WorkflowBuilder(source.Id)
+            .AddSwitch(source, switchBuilder => switchBuilder
+                .AddCase<string>(message => message == "match", [stringTarget])
+                .AddCase<int>(message => message > 0, [intTarget])
+                .WithDefault([defaultTarget]))
+            .Build();
+
+        // Assert
+        Edge edge = GetSingleEdge(workflow, source.Id);
+        edge.Kind.Should().Be(EdgeKind.FanOut);
+        edge.FanOutEdgeData.Should().NotBeNull();
+        edge.FanOutEdgeData!.SourceId.Should().Be(source.Id);
+        edge.FanOutEdgeData!.SinkIds.Should().Equal([stringTarget.Id, intTarget.Id, defaultTarget.Id]);
+        edge.FanOutEdgeData.EdgeAssigner.Should().NotBeNull();
+        edge.FanOutEdgeData.EdgeAssigner!("match", 3).Should().Equal([0]);
+        edge.FanOutEdgeData.EdgeAssigner!(2, 3).Should().Equal([1]);
+        edge.FanOutEdgeData.EdgeAssigner!("other", 3).Should().Equal([2]);
+    }
+
+    [Fact]
+    public void ForwardMessage_InvalidArguments_Throw()
+    {
+        // Arrange
+        WorkflowBuilder builder = new("start");
+        NoOpExecutor source = new("start");
+        NoOpExecutor target = new("target");
+
+        // Act/Assert
+        Assert.Throws<ArgumentNullException>(() => ((WorkflowBuilder)null!).ForwardMessage<string>(source, target));
+        Assert.Throws<ArgumentNullException>("source", () => builder.ForwardMessage<string>(null!, target));
+        Assert.Throws<ArgumentNullException>("target", () => builder.ForwardMessage<string>(source, (ExecutorBinding)null!));
+        Assert.Throws<ArgumentNullException>("targets", () => builder.ForwardMessage<string>(source, (IEnumerable<ExecutorBinding>)null!));
+        Assert.Throws<ArgumentNullException>("targets", () => builder.ForwardMessage<string>(source, [target, null!]));
+        Assert.Throws<ArgumentException>("targets", () => builder.ForwardMessage<string>(source, []));
+    }
+
+    [Fact]
+    public void ForwardExcept_InvalidArguments_Throw()
+    {
+        // Arrange
+        WorkflowBuilder builder = new("start");
+        NoOpExecutor source = new("start");
+        NoOpExecutor target = new("target");
+
+        // Act/Assert
+        Assert.Throws<ArgumentNullException>(() => ((WorkflowBuilder)null!).ForwardExcept<string>(source, target));
+        Assert.Throws<ArgumentNullException>("source", () => builder.ForwardExcept<string>(null!, target));
+        Assert.Throws<ArgumentNullException>("target", () => builder.ForwardExcept<string>(source, (ExecutorBinding)null!));
+        Assert.Throws<ArgumentNullException>("targets", () => builder.ForwardExcept<string>(source, (IEnumerable<ExecutorBinding>)null!));
+        Assert.Throws<ArgumentNullException>("targets", () => builder.ForwardExcept<string>(source, [target, null!]));
+        Assert.Throws<ArgumentException>("targets", () => builder.ForwardExcept<string>(source, []));
+    }
+
+    [Fact]
+    public void AddChain_InvalidArguments_Throw()
+    {
+        // Arrange
+        WorkflowBuilder builder = new("start");
+        NoOpExecutor source = new("start");
+        NoOpExecutor target = new("target");
+        NoOpExecutor otherTarget = new("other-target");
+
+        // Act/Assert
+        Assert.Throws<ArgumentNullException>(() => ((WorkflowBuilder)null!).AddChain(source, [target]));
+        Assert.Throws<ArgumentNullException>("source", () => builder.AddChain(null!, [target]));
+        Assert.Throws<ArgumentNullException>("executors", () => builder.AddChain(source, null!));
+        Assert.Throws<ArgumentNullException>("executors", () => builder.AddChain(source, [target, null!]));
+        Assert.Throws<ArgumentException>("executors", () => builder.AddChain(source, [target, source]));
+        Assert.Throws<ArgumentException>("executors", () => builder.AddChain(source, [target, otherTarget, target]));
+    }
+
+    [Fact]
+    public void AddExternalCall_InvalidArguments_Throw()
+    {
+        // Arrange
+        WorkflowBuilder builder = new("start");
+        NoOpExecutor source = new("start");
+
+        // Act/Assert
+        Assert.Throws<ArgumentNullException>(() => ((WorkflowBuilder)null!).AddExternalCall<string, int>(source, "port"));
+        Assert.Throws<ArgumentNullException>("source", () => builder.AddExternalCall<string, int>(null!, "port"));
+        Assert.Throws<ArgumentNullException>("portId", () => builder.AddExternalCall<string, int>(source, null!));
+    }
+
+    [Fact]
+    public void AddSwitch_InvalidArguments_Throw()
+    {
+        // Arrange
+        WorkflowBuilder builder = new("start");
+        NoOpExecutor source = new("start");
+
+        // Act/Assert
+        Assert.Throws<ArgumentNullException>(() => ((WorkflowBuilder)null!).AddSwitch(source, _ => { }));
+        Assert.Throws<ArgumentNullException>("source", () => builder.AddSwitch(null!, _ => { }));
+        Assert.Throws<ArgumentNullException>("configureSwitch", () => builder.AddSwitch(source, null!));
+        Assert.Throws<ArgumentException>("targets", () => builder.AddSwitch(source, _ => { }));
+        Assert.Throws<ArgumentException>("targets", () => builder.AddSwitch(source, switchBuilder => switchBuilder.AddCase<string>(_ => true, [])));
+    }
+
+    [Fact]
+    public void SwitchBuilder_InvalidArguments_Throw()
+    {
+        // Arrange
+        SwitchBuilder switchBuilder = new();
+        NoOpExecutor target = new("target");
+
+        // Act/Assert
+        Assert.Throws<ArgumentNullException>("predicate", () => switchBuilder.AddCase<string>(null!, [target]));
+        Assert.Throws<ArgumentNullException>("executors", () => switchBuilder.AddCase<string>(_ => true, null!));
+        Assert.Throws<ArgumentNullException>("executors[1]", () => switchBuilder.AddCase<string>(_ => true, [target, null!]));
+        Assert.Throws<ArgumentNullException>("executors", () => switchBuilder.WithDefault(null!));
+        Assert.Throws<ArgumentNullException>("executors[1]", () => switchBuilder.WithDefault([target, null!]));
+    }
+
+    /// <summary>
+    /// Gets the only edge emitted by the specified workflow source.
+    /// </summary>
+    private static Edge GetSingleEdge(Workflow workflow, string sourceId)
+        => workflow.Edges[sourceId].Should().ContainSingle().Subject;
 }