test: assert no subsequent tool call and exact agent invocation counts in coord/spec/coord ping-pong handoff

HandoffAgentExecutor synthesizes a 'Transferred.' tool-result update for
each handoff function call. That update was created without setting
ResponseId, so MessageMerger routed it to the global dangling bucket and
flushed all such tool results at the very end of the merged
AgentResponse, breaking per-step grouping for multi-step handoffs (see
#4544). Streaming output already preserved order because updates are
yielded directly without going through the merger.

Fix: stamp the synthesized update with the same ResponseId as the
preceding agent stream updates so it groups with the agent's other
messages in MessageMerger.

Also adds a regression test that drives the real workflow through
WorkflowHostAgent.RunAsync over a 3-agent handoff chain and asserts the
per-step message ordering of the merged response.

docs/decisions/0026-message-merger-invariants.md

@@ -0,0 +1,191 @@
+---
+status: accepted
+contact: lokitoth
+date: 2026-05-13
+deciders: lokitoth
+consulted:
+informed:
+---
+
+# MessageMerger Streaming Merge Invariants
+
+## Context and Problem Statement
+
+`Microsoft.Agents.AI.Workflows.MessageMerger` is the internal component that
+folds a stream of `AgentResponseUpdate` items emitted by an agent (or by a
+hosting executor wrapping an agent) into a single `AgentResponse` for a turn.
+Multi-agent workflows (handoff, group chat, orchestration) rely on this
+merger to produce a coherent transcript even when updates arrive interleaved
+across responses, messages, and timestamps.
+
+Prior to this change the contract that hosting executors and the merger
+should jointly enforce was implicit. The implementation also carried a small
+amount of dead state (`createdTimes`) that was collected but never consumed,
+suggesting that an earlier, timestamp-driven ordering scheme had been
+abandoned without documentation, and the live code still ran an unreliable
+`CreatedAt`-based sort that could reorder messages across concurrent agents
+inside a single workflow super-step. There were no tests pinning down the
+ordering or grouping behavior, so any future refactor risked silently
+regressing it.
+
+The problem this ADR addresses is therefore: **what merge guarantees does
+`MessageMerger` make to its callers, and how do we lock those guarantees in
+without changing observable behavior in non-pathological cases?**
+
+## Decision Drivers
+
+- **A. Predictable ordering.** Developers consuming a merged `AgentResponse`
+  must be able to reason about the order in which messages appear without
+  having to know whether updates carried `CreatedAt`.
+- **B. Coherent multi-agent transcripts.** When several agents stream into
+  one merger within a single workflow super-step, each agent's contribution
+  must read as a contiguous block; and a step's updates must precede the
+  next step's updates.
+- **C. Stable hosting-executor contract.** A turn must be addressable by a
+  single `ResponseId`; updates without one are an exceptional, "dangling"
+  case rather than the norm.
+- **D. Minimal behavioral change for non-pathological inputs.** This work
+  is intended to document and test current behavior, not to alter what
+  users see today in well-formed agent streams.
+- **E. Discoverability for future contributors.** Known sharp edges (e.g.
+  cross-`ResponseId` ordering, dangling-update placement) should be written
+  down so they are not rediscovered as bugs.
+
+## Considered Options
+
+1. **Option 1 — Document invariants, pin them with tests, and use pure
+   emission/insertion order for both responses and the messages inside
+   each response.** Removes the unreliable `CreatedAt`-based sort and the
+   dead `createdTimes` collection. Behavioral change only for inputs that
+   relied on `CreatedAt` to re-order updates after the fact — which the
+   prior comparer could not do correctly anyway (non-transitive).
+2. **Option 2 — Rewrite `MessageMerger` to group strictly by `AgentId`
+   (rather than `ResponseId`), and to use a stable, transitive comparer
+   that mixes `CreatedAt` with insertion index.** Behavioral change; would
+   also require updating hosting executors that currently assume
+   `ResponseId`-based grouping.
+3. **Option 3 — Leave the code and tests as-is; capture edge cases only
+   in a working note.** No code or test change.
+
+## Decision Outcome
+
+Chosen option: **Option 1 — Document invariants, pin them with tests,
+and use pure emission/insertion order; remove the dead `createdTimes`
+collection.**
+
+This option satisfies driver A (predictable ordering: emission order is
+the simplest reasoning model), driver B (per-`ResponseId` grouping plus
+first-seen ordering across responses gives both per-agent blocks within a
+step and step-ordering across steps), driver C (single ResponseId per
+turn is unchanged), and driver E (invariants and edge cases are now
+written down and covered by tests).
+
+Driver D (minimal behavioral change) is satisfied because well-formed
+agent streams already emit updates in the order they want to appear; the
+prior `CreatedAt`-based sort only mattered for pathological inputs (mixed
+or out-of-order timestamps from concurrent agents), and on those inputs
+the old comparer was non-transitive and therefore unreliable. Removing
+the sort makes those inputs deterministic — they now follow emission
+order — without disturbing the well-formed case.
+
+Option 2 was rejected for this iteration because it changes what callers
+observe in well-formed flows and would require a coordinated change
+across hosting executors. It is a candidate for a follow-up ADR if the
+known edge cases below are reported as bugs in practice.
+
+Option 3 was rejected because it leaves the invariants un-tested and the
+dead code in place, so the next refactor can break the contract without
+any signal.
+
+### Invariants
+
+The following invariants are now part of the contract of
+`MessageMerger`/hosting executors and are covered by tests in
+`MessageMergerTests`:
+
+1. **Single `ResponseId` per turn.** Every `AgentResponseUpdate` produced
+   by a hosting executor in a single agent turn shares one `ResponseId`.
+   If the underlying agent does not supply one, the executor assigns it.
+   Updates with `ResponseId == null` are treated as "dangling" and
+   flattened into loose messages at the end of the merged response.
+2. **Pure emission-order preservation.** Within a `ResponseId` block,
+   messages appear in the order their updates first arrived at the
+   merger. Across `ResponseId` blocks, blocks appear in first-seen order.
+   `CreatedAt` is **not** consulted when ordering messages or blocks —
+   only when stamping the merged response and its child messages.
+3. **Per-`ResponseId` grouping (no interleaving).** Messages produced
+   under one `ResponseId` are emitted as a contiguous block in the merged
+   `AgentResponse`. Combined with Invariant 1, this yields:
+   - **Within a workflow super-step with one agent**: all messages
+     appear together, in emission order.
+   - **Within a super-step with multiple agents**: each agent's messages
+     are a contiguous block, ordered by which agent emitted first.
+   - **Across super-steps**: a step's blocks all precede the next step's
+     blocks, because the next step cannot start emitting until the
+     current step's emissions have arrived at the merger.
+
+### Consequences
+
+- Good, because the merge contract is now explicit, regression-tested,
+  and trivially reasoned about (it is just emission order with
+  per-`ResponseId` grouping).
+- Good, because removing the unreliable `CreatedAt`-based sort eliminates
+  a latent bug — the prior comparer was non-transitive on mixed-timestamp
+  inputs, so `List<T>.Sort` could in principle return any of several
+  orderings or throw on some runtimes.
+- Good, because removing the unused `createdTimes` collection eliminates
+  a misleading code smell.
+- Good, because hosting-executor authors have a written checklist of
+  invariants to satisfy.
+- Neutral, because well-formed agent streams (those that emit updates in
+  the order they want to appear) see no change in output.
+- Bad, because callers who relied on a server-supplied `CreatedAt` to
+  retro-correct out-of-order emissions will no longer see that
+  correction — they must ensure emission order matches desired output
+  order, or attach to `RawRepresentation` for original timestamps.
+
+## Validation
+
+- Unit tests in
+  `dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/MessageMergerTests.cs`
+  cover each invariant:
+  - Insertion-order preservation with no timestamps.
+  - Insertion-order preservation with mixed timestamps (emission order
+    wins over `CreatedAt`).
+  - Determinism across repeated runs with mixed timestamps.
+  - Per-`ResponseId` grouping for interleaved multi-agent streams within
+    a single step.
+  - Per-`ResponseId` grouping with distinct response ids.
+- Existing tests for assembly, function-call/result ordering, and
+  `FinishReason` propagation continue to pass.
+
+## More Information
+
+### Known edge cases (intentionally not fixed in this ADR)
+
+These are properties of the *current* `MessageMerger` that callers should
+be aware of. They are not invariants — they may change in a future ADR —
+but they are present in the shipped behavior covered by tests above.
+
+| # | Edge case | Risk | Notes |
+|---|-----------|------|-------|
+| 1 | Cross-`ResponseId` ordering follows first-seen-`ResponseId` order, not chronological order across responses. | Medium | Acceptable today because each turn has a single `ResponseId` (Invariant 1); only matters if a caller deliberately interleaves multiple response ids inside one step. |
+| 2 | Updates with `ResponseId == null` are always emitted **after** all keyed responses, regardless of arrival time. | Medium | Documented as the "dangling" path; agents should always emit a `ResponseId`. |
+| 3 | Within a response, updates with `MessageId == null` are always emitted **after** keyed messages. | Low | Same rationale as #2, scoped to messages within a response. |
+| 4 | The merged response's `CreatedAt` is set to `DateTimeOffset.UtcNow`; per-response `CreatedAt` is propagated onto each contained `ChatMessage` instead of being preserved at the response level. | Low | Callers who need original per-update timestamps should read them from `RawRepresentation` or capture them before merging. |
+| 5 | Metadata on dangling (`ResponseId == null`) updates — `FinishReason`, `Usage`, `AgentId`, `AdditionalProperties` — is **not** merged into the final `AgentResponse`; only their `Messages` are surfaced. | Medium | Hosting executors must attach metadata to a keyed update if they want it reflected in the merged response. |
+| 6 | Emission order is the **only** ordering signal — `CreatedAt` differences between updates are ignored when ordering. | Low | This is the intended behavior under Invariant 2; producers must emit in the desired output order. |
+
+If any of these become observable problems in production, the appropriate
+follow-up is a new ADR that supersedes this one (likely realizing
+"Option 2") rather than a silent fix.
+
+### Code references
+
+- `dotnet/src/Microsoft.Agents.AI.Workflows/MessageMerger.cs` — merger
+  implementation. The previously-unused `createdTimes` collection and
+  the `CreatedAt`-based sort have both been removed in this change.
+- `dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/MessageMergerTests.cs` —
+  invariant tests added in this change.
+- `AgentInvocationContext.ResponseId` and `ToStreamingResponseAsync` —
+  the hosting-executor side of Invariant 1.

dotnet/agent-framework-dotnet.slnx

@@ -242,7 +242,6 @@
     <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" />

dotnet/eng/verify-samples/WorkflowSamples.cs

@@ -478,17 +478,6 @@ 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.6.1</VersionPrefix>
+    <VersionPrefix>1.6.0</VersionPrefix>
     <RCNumber>1</RCNumber>
-    <DateSuffix>260514</DateSuffix>
+    <DateSuffix>260512</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.6.1</GitTag>
+    <GitTag>1.6.0</GitTag>
 
     <Configurations>Debug;Release;Publish</Configurations>
     <IsPackable>true</IsPackable>

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

@@ -9,30 +9,42 @@ namespace Harness.ConsoleReactiveComponents;
 /// </summary>
 public record TextPanelProps : ConsoleReactiveProps
 {
-    /// <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>Gets the items to render in the panel.</summary>
+    public IReadOnlyList<object> Items { get; init; } = [];
 }
 
 /// <summary>
-/// A component that renders a list of pre-rendered string items vertically.
+/// A component that renders a list of items vertically using a custom render delegate.
 /// 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<string> items)
+    public static int CalculateHeight(IReadOnlyList<object> items, Func<object, string> renderItem)
     {
         int total = 0;
         for (int i = 0; i < items.Count; i++)
         {
-            total += CountLines(items[i]);
+            string text = renderItem(items[i]);
+            total += CountLines(text);
         }
 
         return total;
@@ -45,7 +57,7 @@ public class TextPanel : ConsoleReactiveComponent<TextPanelProps, ConsoleReactiv
 
         for (int i = 0; i < props.Items.Count; i++)
         {
-            string text = props.Items[i];
+            string text = this._renderItem(props.Items[i]);
             string[] lines = text.Split('\n');
             int lineCount = CountLines(text);
 

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

@@ -9,9 +9,8 @@ namespace Harness.ConsoleReactiveComponents;
 /// </summary>
 public record TextScrollPanelProps : ConsoleReactiveProps
 {
-    /// <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>Gets the items to render in the scroll panel.</summary>
+    public IReadOnlyList<object> Items { get; init; } = [];
 }
 
 /// <summary>
@@ -21,17 +20,21 @@ public record TextScrollPanelProps : ConsoleReactiveProps
 public record TextScrollPanelState(int RenderedCount = 0) : ConsoleReactiveState;
 
 /// <summary>
-/// A component that renders pre-rendered string items within a scroll area.
+/// A component that renders items within a scroll area using a custom render delegate.
 /// 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>
-    public TextScrollPanel()
+    /// <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)
     {
+        this._renderItem = renderItem;
         this.State = new TextScrollPanelState();
     }
 
@@ -57,7 +60,8 @@ public class TextScrollPanel : ConsoleReactiveComponent<TextScrollPanelProps, Te
         // Output only new items since last rendered
         for (int i = state.RenderedCount; i < props.Items.Count; i++)
         {
-            Console.Write(props.Items[i]);
+            string text = this._renderItem(props.Items[i]);
+            Console.Write(text);
         }
 
         // Update state to track what we've rendered

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

@@ -0,0 +1,315 @@
+// 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 state driver for rendering output.</param>
+    /// <param name="ux">The UX container 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, IUXStateDriver ux);
+    public abstract ValueTask<bool> TryHandleAsync(string input, AgentSession session, HarnessUXContainer ux);
 }

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

@@ -1,26 +0,0 @@
-// 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>
-public sealed class ModeCommandHandler : CommandHandler
+internal sealed class ModeCommandHandler : CommandHandler
 {
     private readonly AgentModeProvider? _modeProvider;
     private readonly IReadOnlyDictionary<string, ConsoleColor>? _modeColors;
@@ -27,7 +27,7 @@ public 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, IUXStateDriver ux)
+    public override async ValueTask<bool> TryHandleAsync(string input, AgentSession session, HarnessUXContainer 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>
-public sealed class TodoCommandHandler : CommandHandler
+internal sealed class TodoCommandHandler : CommandHandler
 {
     private readonly TodoProvider? _todoProvider;
 
@@ -24,7 +24,7 @@ public 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, IUXStateDriver ux)
+    public override async ValueTask<bool> TryHandleAsync(string input, AgentSession session, HarnessUXContainer ux)
     {
         if (!input.Equals("/todos", StringComparison.OrdinalIgnoreCase))
         {

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

@@ -1,59 +0,0 @@
-// 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

@@ -1,279 +0,0 @@
-// 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,89 +3,171 @@
 using Harness.ConsoleReactiveComponents;
 using Harness.ConsoleReactiveFramework;
 using Harness.Shared.Console.Components;
-using Microsoft.Extensions.AI;
 
 namespace Harness.Shared.Console;
 
 /// <summary>
-/// The main application component for the Harness console. Manages the scroll region
-/// 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"/>.
+/// Determines which component is shown in the bottom panel.
 /// </summary>
-public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps, HarnessAppComponentState>, IDisposable
+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.
+/// </summary>
+public class HarnessAppComponent : ConsoleReactiveComponent<HarnessAppComponentProps, HarnessAppComponentState>, IDisposable
 {
     private readonly TopBottomRule _rule = new();
     private readonly ListSelection _listSelection = new();
     private readonly TextInput _textInput = new();
-    private readonly TextScrollPanel _textScrollPanel = new();
-    private readonly TextPanel _textPanel = new();
-    private readonly TextPanel _queuedPanel = new();
+    private readonly TextScrollPanel _textScrollPanel;
+    private readonly TextPanel _textPanel;
+    private readonly TextPanel _queuedPanel;
     private readonly AgentStatus _agentStatus = new();
     private readonly AgentModeAndHelp _modeAndHelp = new();
-    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 readonly Func<object, string> _renderItem;
+    private bool _resizedSinceLastRender;
     private bool _deactivated;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="HarnessAppComponent"/> 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="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)
+    /// <param name="renderScrollItem">A delegate that renders a single output entry and returns the text to display.</param>
+    public HarnessAppComponent(Func<object, string> renderScrollItem)
     {
-        this.Props = new ConsoleReactiveProps();
+        this._renderItem = renderScrollItem;
+        this._textScrollPanel = new TextScrollPanel(renderScrollItem);
+        this._textPanel = new TextPanel(renderScrollItem);
+        this._queuedPanel = new TextPanel(renderScrollItem);
         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 agent runner that owns the agent loop. Constructed by the factory
-    /// passed to the component's constructor.
+    /// Gets the 1-based row number of the last row in the output scroll region.
     /// </summary>
-    public HarnessAgentRunner Runner { get; }
+    public int ScrollRegionBottom { get; private set; }
 
     /// <summary>
-    /// Completes when a command handler requests application shutdown (e.g. the user types <c>/exit</c>).
-    /// Awaited by <see cref="HarnessConsole.RunAgentAsync"/>.
+    /// 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.
     /// </summary>
-    public Task ShutdownTask => this._shutdownTcs.Task;
+    public event EventHandler<InputSubmittedEventArgs>? InputSubmitted;
 
     /// <summary>
     /// Deactivates the component, resetting the scroll region and unsubscribing from events.
@@ -102,6 +184,9 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
         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/>
@@ -120,23 +205,20 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
         if (disposing)
         {
             this.Deactivate();
-            this._followUpGate.Dispose();
-            this.Runner.Dispose();
         }
     }
 
     private void OnKeyPressed(object? sender, KeyPressEventArgs e)
     {
-        BottomPanelMode mode = this.State!.Mode;
-        if (mode == BottomPanelMode.TextInput)
+        if (this.Props!.Mode == BottomPanelMode.TextInput)
         {
             this.HandleTextInputKey(e);
         }
-        else if (mode == BottomPanelMode.ListSelection)
+        else if (this.Props.Mode == BottomPanelMode.ListSelection)
         {
             this.HandleListSelectionKey(e);
         }
-        else if (mode == BottomPanelMode.Streaming && this.State.InputEnabled)
+        else if (this.Props.Mode == BottomPanelMode.Streaming && this.Props.InputEnabled)
         {
             this.HandleStreamingInputKey(e);
         }
@@ -153,7 +235,7 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
             }
 
             this.SetState(this.State with { InputText = "" });
-            this.DispatchTextInputSubmission(text);
+            this.InputSubmitted?.Invoke(this, new InputSubmittedEventArgs(text, BottomPanelMode.TextInput));
         }
         else if (e.KeyInfo.Key == ConsoleKey.Backspace)
         {
@@ -170,50 +252,51 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
 
     private void HandleListSelectionKey(KeyPressEventArgs e)
     {
-        int maxIndex = this.State!.ListSelectionOptions.Count - 1;
-        if (this.State.ListSelectionCustomTextPlaceholder != null)
+        int maxIndex = this.Props!.Items.Count - 1;
+        if (this.Props.ListCustomTextPlaceholder != null)
         {
-            maxIndex = this.State.ListSelectionOptions.Count;
+            maxIndex = this.Props.Items.Count;
         }
 
-        bool isOnCustomTextOption = this.State.ListSelectionCustomTextPlaceholder != null
-            && this.State.ListSelectionIndex == this.State.ListSelectionOptions.Count;
+        bool isOnCustomTextOption = this.Props.ListCustomTextPlaceholder != null
+            && this.State!.SelectedIndex == this.Props.Items.Count;
 
         if (e.KeyInfo.Key == ConsoleKey.UpArrow)
         {
-            this.SetState(this.State with { ListSelectionIndex = Math.Max(0, this.State.ListSelectionIndex - 1) });
+            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 { ListSelectionIndex = Math.Min(maxIndex, this.State.ListSelectionIndex + 1) });
+            this.SetState(this.State! with { SelectedIndex = Math.Min(maxIndex, this.State.SelectedIndex + 1) });
         }
         else if (e.KeyInfo.Key == ConsoleKey.Enter)
         {
             string result = isOnCustomTextOption
-                ? this.State.ListSelectionCustomInputText
-                : this.State.ListSelectionOptions[this.State.ListSelectionIndex];
+                ? this.State!.ListInputText
+                : this.Props.Items[this.State!.SelectedIndex];
 
-            this.SetState(this.State with { ListSelectionCustomInputText = "", ListSelectionIndex = 0 });
-            this.DispatchListSelectionSubmission(result);
+            this.SetState(this.State with { ListInputText = "", SelectedIndex = 0 });
+            this.InputSubmitted?.Invoke(this, new InputSubmittedEventArgs(result, BottomPanelMode.ListSelection));
         }
         else if (isOnCustomTextOption)
         {
             if (e.KeyInfo.Key == ConsoleKey.Backspace)
             {
-                if (this.State.ListSelectionCustomInputText.Length > 0)
+                if (this.State!.ListInputText.Length > 0)
                 {
-                    this.SetState(this.State with { ListSelectionCustomInputText = this.State.ListSelectionCustomInputText[..^1] });
+                    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 { ListSelectionCustomInputText = this.State.ListSelectionCustomInputText + e.KeyInfo.KeyChar });
+                this.SetState(this.State! with { ListInputText = this.State.ListInputText + 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;
@@ -223,7 +306,7 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
             }
 
             this.SetState(this.State with { InputText = "" });
-            _ = this.Runner.OnStreamingInputAsync(text);
+            this.InputSubmitted?.Invoke(this, new InputSubmittedEventArgs(text, BottomPanelMode.Streaming));
         }
         else if (e.KeyInfo.Key == ConsoleKey.Backspace)
         {
@@ -238,90 +321,6 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
         }
     }
 
-    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;
@@ -333,40 +332,35 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
     }
 
     /// <inheritdoc />
-    public override void RenderCore(ConsoleReactiveProps props, HarnessAppComponentState state)
+    public override void RenderCore(HarnessAppComponentProps props, HarnessAppComponentState state)
     {
-        if (this._deactivated)
-        {
-            return;
-        }
-
         // Determine the text panel height for the last scroll item
-        IReadOnlyList<string> lastItems = state.ScrollAreaContentItems.Count > 0
-            ? [state.ScrollAreaContentItems[^1]]
+        IReadOnlyList<object> lastItems = props.ScrollItems.Count > 0
+            ? [props.ScrollItems[^1]]
             : [];
-        int textPanelHeight = TextPanel.CalculateHeight(lastItems);
+        int textPanelHeight = TextPanel.CalculateHeight(lastItems, this._renderItem);
         if (textPanelHeight > 0)
         {
             textPanelHeight++; // Extra line for spacing between text panel and rule
         }
 
         // Calculate queued items panel height
-        int queuedPanelHeight = TextPanel.CalculateHeight(state.QueuedItems);
+        int queuedPanelHeight = TextPanel.CalculateHeight(props.QueuedItems, this._renderItem);
 
         // Build the bottom panel child based on mode
         ConsoleReactiveComponent bottomChild;
         int bottomChildHeight;
 
-        if (state.Mode == BottomPanelMode.ListSelection)
+        if (props.Mode == BottomPanelMode.ListSelection)
         {
             var listProps = new ListSelectionProps
             {
-                Title = state.ListSelectionTitle,
-                Items = state.ListSelectionOptions,
-                SelectedIndex = state.ListSelectionIndex,
-                HighlightColor = state.ListHighlightColor,
-                CustomTextPlaceholder = state.ListSelectionCustomTextPlaceholder,
-                CustomText = state.ListSelectionCustomInputText,
+                Title = props.ListTitle,
+                Items = props.Items,
+                SelectedIndex = state.SelectedIndex,
+                HighlightColor = props.ListHighlightColor,
+                CustomTextPlaceholder = props.ListCustomTextPlaceholder,
+                CustomText = state.ListInputText,
             };
 
             bottomChildHeight = ListSelection.CalculateHeight(listProps);
@@ -374,25 +368,25 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
             this._listSelection.Props = listProps;
             bottomChild = this._listSelection;
         }
-        else if (state.Mode == BottomPanelMode.Streaming)
+        else if (props.Mode == BottomPanelMode.Streaming)
         {
             TextInputProps textInputProps;
-            if (state.InputEnabled)
+            if (props.InputEnabled)
             {
                 textInputProps = new TextInputProps
                 {
-                    Prompt = state.Prompt,
+                    Prompt = props.Prompt,
                     Text = state.InputText,
-                    Placeholder = state.Placeholder,
+                    Placeholder = props.Placeholder,
                 };
             }
             else
             {
                 textInputProps = new TextInputProps
                 {
-                    Prompt = state.Prompt,
+                    Prompt = props.Prompt,
                     Text = "",
-                    Placeholder = state.StreamingPrompt,
+                    Placeholder = props.StreamingPrompt,
                 };
             }
 
@@ -406,9 +400,9 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
         {
             var textInputProps = new TextInputProps
             {
-                Prompt = state.Prompt,
+                Prompt = props.Prompt,
                 Text = state.InputText,
-                Placeholder = state.Placeholder,
+                Placeholder = props.Placeholder,
             };
 
             bottomChildHeight = TextInput.CalculateHeight(textInputProps, state.ConsoleWidth);
@@ -421,52 +415,46 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
         var ruleProps = new TopBottomRuleProps
         {
             Width = state.ConsoleWidth,
-            Color = state.ModeColor,
+            Color = props.ModeColor,
             Children = [bottomChild],
         };
 
+        // Calculate the agent status height
         var agentStatusProps = new AgentStatusProps
         {
-            ShowSpinner = state.ShowSpinner,
-            UsageText = state.UsageText,
+            ShowSpinner = props.ShowSpinner,
+            UsageText = props.UsageText,
         };
+        int agentStatusHeight = AgentStatus.CalculateHeight(agentStatusProps);
 
+        // Calculate the mode-and-help height
         var modeAndHelpProps = new AgentModeAndHelpProps
         {
-            Mode = state.ModeText,
-            ModeColor = state.ModeColor,
-            HelpText = state.HelpText,
+            Mode = props.ModeText,
+            ModeColor = props.ModeColor,
+            HelpText = props.HelpText,
         };
-
-        // 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 modeAndHelpHeight = AgentModeAndHelp.CalculateHeight(modeAndHelpProps);
 
         int ruleHeight = TopBottomRule.CalculateHeight(ruleProps);
-        int nonScrollHeight = ruleHeight + textPanelHeight + agentStatusHeight + queuedPanelHeight + modeAndHelpHeight + 1; // +1 for bottom padding
-        int scrollBottom = Math.Max(1, state.ConsoleHeight - nonScrollHeight);
+        int scrollBottom = Math.Max(1, state.ConsoleHeight - ruleHeight - textPanelHeight - agentStatusHeight - queuedPanelHeight - modeAndHelpHeight);
 
         // 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<string> scrollItems = state.ScrollAreaContentItems.Count > 1
-            ? state.ScrollAreaContentItems.Take(state.ScrollAreaContentItems.Count - 1).ToList()
+        IReadOnlyList<object> scrollItems = props.ScrollItems.Count > 1
+            ? props.ScrollItems.Take(props.ScrollItems.Count - 1).ToList()
             : [];
 
         this._textScrollPanel.X = 1;
@@ -498,21 +486,18 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
         this._queuedPanel.Height = queuedPanelHeight;
         this._queuedPanel.Props = new TextPanelProps
         {
-            Items = state.QueuedItems,
+            Items = props.QueuedItems,
         };
         this._queuedPanel.Render();
 
         // Render the agent status line between queued items and rule
         int agentStatusY = queuedPanelY + queuedPanelHeight;
-        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();
-        }
+        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;
@@ -521,27 +506,24 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
         this._rule.Render();
 
         // Render the mode-and-help line below the bottom rule
-        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();
-        }
+        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(state);
+        this.PositionCursor(props, state);
     }
 
-    private void PositionCursor(HarnessAppComponentState state)
+    private void PositionCursor(HarnessAppComponentProps props, HarnessAppComponentState state)
     {
-        if (state.Mode == BottomPanelMode.TextInput
-            || (state.Mode == BottomPanelMode.Streaming && state.InputEnabled))
+        if (props.Mode == BottomPanelMode.TextInput
+            || (props.Mode == BottomPanelMode.Streaming && props.InputEnabled))
         {
-            int promptLength = state.Prompt.Length;
+            int promptLength = props.Prompt.Length;
             int textWidth = state.ConsoleWidth - promptLength;
             int textLength = state.InputText.Length;
 
@@ -558,13 +540,13 @@ public class HarnessAppComponent : ConsoleReactiveComponent<ConsoleReactiveProps
                 System.Console.Write(AnsiEscapes.MoveCursor(textInputY + cursorRow, promptLength + cursorCol + 1));
             }
         }
-        else if (state.Mode == BottomPanelMode.ListSelection
-            && state.ListSelectionCustomTextPlaceholder != null
-            && state.ListSelectionIndex == state.ListSelectionOptions.Count)
+        else if (props.Mode == BottomPanelMode.ListSelection
+            && props.ListCustomTextPlaceholder != null
+            && state.SelectedIndex == props.Items.Count)
         {
-            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;
+            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;
             System.Console.Write(AnsiEscapes.MoveCursor(customOptionY, cursorCol));
         }
     }

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

@@ -1,125 +0,0 @@
-// 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,7 +1,9 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-using Harness.ConsoleReactiveComponents;
+using Harness.Shared.Console.Commands;
+using Harness.Shared.Console.Observers;
 using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
 
 namespace Harness.Shared.Console;
 
@@ -13,58 +15,244 @@ public static class HarnessConsole
 {
     /// <summary>
     /// Runs an interactive console session with the specified agent.
-    /// 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>).
+    /// Supports streaming output, tool call display, spinner animation,
+    /// optional planning UX with structured output, and the <c>/todos</c> command.
     /// </summary>
     /// <param name="agent">The agent to interact with.</param>
-    /// <param name="userPrompt">A short prompt to the user, displayed as a placeholder in the input area.</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="options">Optional configuration options for the console session.</param>
-    public static async Task RunAgentAsync(AIAgent agent, string userPrompt, HarnessConsoleOptions? options = null)
+    public static async Task RunAgentAsync(AIAgent agent, string title, string userPrompt, HarnessConsoleOptions? options = null)
     {
         options ??= new();
 
-        // 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);
+        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));
+        }
 
+        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 component = new HarnessAppComponent(
+        using var ux = new HarnessUXContainer(
             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);
 
-        // Trigger the initial render of the component now that state is seeded.
-        component.Render();
+        // Streaming-mode submissions are enqueued for injection; the queued display
+        // is then refreshed from the injector's current pending list.
+        ux.StreamingInputReceived += (sender, e) =>
+        {
+            if (messageInjector is null)
+            {
+                return;
+            }
 
-        try
+            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
-        {
-            component.Deactivate();
+            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();
         }
 
+        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,11 +1,5 @@
 // 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>
@@ -14,120 +8,45 @@ namespace Harness.Shared.Console;
 public class HarnessConsoleOptions
 {
     /// <summary>
-    /// 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.
+    /// Gets or sets the optional maximum context window size in tokens.
+    /// When set, token usage is displayed as a percentage of the budget.
     /// </summary>
-    public IReadOnlyList<ConsoleObserver>? Observers { get; set; }
+    public int? MaxContextWindowTokens { get; set; }
 
     /// <summary>
-    /// 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.
+    /// Gets or sets the optional maximum output tokens.
+    /// Used with <see cref="MaxContextWindowTokens"/> to show input/output budget breakdown.
     /// </summary>
-    public IReadOnlyList<CommandHandler>? CommandHandlers { get; set; }
+    public int? MaxOutputTokens { get; set; }
 
     /// <summary>
-    /// The default mode-to-color mapping used when no custom <see cref="ModeColors"/> are provided.
+    /// 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.
     /// </summary>
-    public static readonly IReadOnlyDictionary<string, ConsoleColor> DefaultModeColors = new ReadOnlyDictionary<string, ConsoleColor>(
-        new Dictionary<string, ConsoleColor>(StringComparer.OrdinalIgnoreCase)
-        {
-            ["plan"] = ConsoleColor.Cyan,
-            ["execute"] = ConsoleColor.Green,
-        });
+    /// <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; }
 
     /// <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(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)
+    public Dictionary<string, ConsoleColor> ModeColors { get; set; } = new(StringComparer.OrdinalIgnoreCase)
     {
-        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),
-        ];
-    }
+        ["plan"] = ConsoleColor.Cyan,
+        ["execute"] = ConsoleColor.Green,
+    };
 }

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

@@ -1,408 +0,0 @@
-// 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

@@ -0,0 +1,478 @@
+// 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

@@ -1,120 +0,0 @@
-// 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,41 +18,36 @@ public abstract class ConsoleObserver
     /// Override to set options such as <see cref="AgentRunOptions.ResponseFormat"/>.
     /// </summary>
     /// <param name="options">The run options to configure.</param>
-    /// <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)
+    public virtual void ConfigureRunOptions(AgentRunOptions options)
     {
     }
 
     /// <summary>
     /// Called for each <see cref="AIContent"/> item in the response stream.
     /// </summary>
-    /// <param name="ux">The UX state driver, used for rendering output.</param>
+    /// <param name="ux">The harness UX container, used for rendering output and interacting with the user.</param>
     /// <param name="content">The content item from the stream.</param>
-    /// <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;
+    public virtual Task OnContentAsync(HarnessUXContainer ux, AIContent content) => Task.CompletedTask;
 
     /// <summary>
     /// Called for each text update in the response stream.
     /// </summary>
-    /// <param name="ux">The UX state driver, used for rendering output.</param>
+    /// <param name="ux">The harness UX container, used for rendering output and interacting with the user.</param>
     /// <param name="text">The text from the update.</param>
-    /// <param name="agent">The agent being interacted with.</param>
-    /// <param name="session">The current agent session.</param>
-    public virtual Task OnTextAsync(IUXStateDriver ux, string text, AIAgent agent, AgentSession session) => Task.CompletedTask;
+    public virtual Task OnTextAsync(HarnessUXContainer ux, string text) => 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.
+    /// 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 UX state driver, used for rendering output.</param>
+    /// <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>
-    /// <returns>Follow-up actions to process after the stream completes, or <see langword="null"/>.</returns>
-    public virtual Task<IList<FollowUpAction>?> OnStreamCompleteAsync(
-        IUXStateDriver ux,
+    /// <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,
         AIAgent agent,
-        AgentSession session) => Task.FromResult<IList<FollowUpAction>?>(null);
+        AgentSession session,
+        HarnessConsoleOptions options) => Task.FromResult<IList<ChatMessage>?>(null);
 }

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

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

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

@@ -2,77 +2,51 @@
 
 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 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.
+/// 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.
 /// </summary>
-public sealed class PlanningOutputObserver : ConsoleObserver
+internal 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>
-    /// <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)
+    public PlanningOutputObserver(AgentModeProvider modeProvider)
     {
         this._modeProvider = modeProvider;
-        this._planModeName = planModeName;
-        this._executionModeName = executionModeName;
-        this._modeColors = modeColors;
     }
 
     /// <inheritdoc/>
-    public override void ConfigureRunOptions(AgentRunOptions options, AIAgent agent, AgentSession session)
+    public override void ConfigureRunOptions(AgentRunOptions options)
     {
-        if (this.IsPlanningMode(this._modeProvider.GetMode(session)))
-        {
-            options.ResponseFormat = ChatResponseFormat.ForJsonSchema<PlanningResponse>();
-        }
+        options.ResponseFormat = ChatResponseFormat.ForJsonSchema<PlanningResponse>();
     }
 
     /// <inheritdoc/>
-    public override Task OnTextAsync(IUXStateDriver ux, string text, AIAgent agent, AgentSession session)
+    public override Task OnTextAsync(HarnessUXContainer ux, string text)
     {
-        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);
+        // Collect text silently instead of displaying it.
+        this._textCollector.Append(text);
+        return Task.CompletedTask;
     }
 
     /// <inheritdoc/>
-    public override async Task<IList<FollowUpAction>?> OnStreamCompleteAsync(
-        IUXStateDriver ux,
+    public override async Task<IList<ChatMessage>?> OnStreamCompleteAsync(
+        HarnessUXContainer ux,
         AIAgent agent,
-        AgentSession session)
+        AgentSession session,
+        HarnessConsoleOptions options)
     {
-        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();
@@ -101,9 +75,10 @@ public sealed class PlanningOutputObserver : ConsoleObserver
             return null;
         }
 
+        // Render based on response type.
         if (planningResponse.Type == PlanningResponseType.Clarification)
         {
-            return BuildClarificationActions(planningResponse);
+            return AsUserMessages(await this.RenderClarificationsAndCollectResponsesAsync(ux, planningResponse));
         }
 
         if (planningResponse.Type == PlanningResponseType.Approval)
@@ -115,87 +90,67 @@ public sealed class PlanningOutputObserver : ConsoleObserver
                 return null;
             }
 
-            return new List<FollowUpAction> { this.BuildApprovalAction(question, session) };
+            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);
         }
 
         await ux.WriteInfoLineAsync($"(unexpected response type: {planningResponse.Type})", ConsoleColor.DarkYellow);
         return null;
     }
 
-    private static List<FollowUpAction> BuildClarificationActions(PlanningResponse response)
+    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)
     {
-        var actions = new List<FollowUpAction>(response.Questions.Count);
+        var answers = new List<string>();
 
         foreach (var question in response.Questions)
         {
-            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}");
-            }
-
+            string? answer;
             if (question.Choices is { Count: > 0 })
             {
-                actions.Add(new ChoiceFollowUpQuestion(
-                    Prompt: prompt,
-                    Choices: question.Choices,
-                    AllowCustomText: true,
-                    Continuation: Continuation));
+                answer = await ux.ReadSelectionAsync(
+                    question.Message,
+                    question.Choices);
             }
             else
             {
-                actions.Add(new TextFollowUpQuestion(
-                    Prompt: prompt,
-                    Continuation: Continuation));
+                answer = (await ux.ReadLineAsync(question.Message))?.Trim();
+            }
+
+            if (!string.IsNullOrWhiteSpace(answer))
+            {
+                answers.Add($"Q: {question.Message}\nA: {answer}");
             }
         }
 
-        return actions;
+        return answers.Count > 0 ? string.Join("\n\n", answers) : null;
     }
 
-    private ChoiceFollowUpQuestion BuildApprovalAction(PlanningQuestion question, AgentSession session)
+    private async Task<string> RenderApprovalAndCollectResponseAsync(HarnessUXContainer ux, PlanningQuestion question, HarnessConsoleOptions options)
     {
-        const string ApproveOption = "Approve and switch to execute mode";
-        var choices = new List<string> { ApproveOption };
+        var choices = new List<string>
+        {
+            "Approve and switch to execute mode",
+        };
 
-        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);
+        string selection = await ux.ReadSelectionAsync(question.Message, choices);
 
-                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");
-                }
+        if (selection == choices[0])
+        {
+            return "Approved";
+        }
 
-                // Custom freeform input — treat as suggested changes.
-                return new ChatMessage(ChatRole.User, selection);
-            });
+        // Custom freeform input — treat as suggested changes.
+        return 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,6 +1,5 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 
 namespace Harness.Shared.Console.Observers;
@@ -8,10 +7,10 @@ namespace Harness.Shared.Console.Observers;
 /// <summary>
 /// Displays reasoning content in dark magenta from the response stream.
 /// </summary>
-public sealed class ReasoningDisplayObserver : ConsoleObserver
+internal sealed class ReasoningDisplayObserver : ConsoleObserver
 {
     /// <inheritdoc/>
-    public override async Task OnContentAsync(IUXStateDriver ux, AIContent content, AIAgent agent, AgentSession session)
+    public override async Task OnContentAsync(HarnessUXContainer ux, AIContent content)
     {
         if (content is TextReasoningContent reasoning && !string.IsNullOrEmpty(reasoning.Text))
         {

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

@@ -1,17 +1,15 @@
 // 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>
-public sealed class TextOutputObserver : ConsoleObserver
+internal sealed class TextOutputObserver : ConsoleObserver
 {
     /// <inheritdoc/>
-    public override async Task OnTextAsync(IUXStateDriver ux, string text, AIAgent agent, AgentSession session)
+    public override async Task OnTextAsync(HarnessUXContainer ux, string text)
     {
         await ux.WriteTextAsync(text);
     }

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

@@ -1,7 +1,5 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-using Harness.ConsoleReactiveComponents;
-using Harness.Shared.Console.ToolFormatters;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 
@@ -9,103 +7,86 @@ namespace Harness.Shared.Console.Observers;
 
 /// <summary>
 /// Collects <see cref="ToolApprovalRequestContent"/> items during the response stream,
-/// 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.
+/// displays approval-needed notifications inline, and prompts the user for approval
+/// decisions after the stream completes.
 /// </summary>
-public sealed class ToolApprovalObserver : ConsoleObserver
+internal 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(IUXStateDriver ux, AIContent content, AIAgent agent, AgentSession session)
+    public override async Task OnContentAsync(HarnessUXContainer ux, AIContent content)
     {
         if (content is ToolApprovalRequestContent approvalRequest)
         {
             this._approvalRequests.Add(approvalRequest);
             string toolName = approvalRequest.ToolCall is FunctionCallContent fc
-                ? ToolCallFormatter.Format(this._formatters, fc)
+                ? ToolCallFormatter.Format(fc)
                 : approvalRequest.ToolCall?.ToString() ?? "unknown";
             await ux.WriteInfoLineAsync($"⚠️ Approval needed: {toolName}", ConsoleColor.Yellow);
         }
     }
 
     /// <inheritdoc/>
-    public override Task<IList<FollowUpAction>?> OnStreamCompleteAsync(
-        IUXStateDriver ux,
+    public override async Task<IList<ChatMessage>?> OnStreamCompleteAsync(
+        HarnessUXContainer ux,
         AIAgent agent,
-        AgentSession session)
+        AgentSession session,
+        HarnessConsoleOptions options)
     {
         if (this._approvalRequests.Count == 0)
         {
-            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));
+            return null;
         }
 
+        var messages = await PromptForApprovalsAsync(ux, this._approvalRequests);
         this._approvalRequests.Clear();
-        return Task.FromResult<IList<FollowUpAction>?>(actions);
+        return messages;
     }
 
-    private ChoiceFollowUpQuestion BuildApprovalQuestion(ToolApprovalRequestContent request)
+    private static async Task<List<ChatMessage>?> PromptForApprovalsAsync(HarnessUXContainer ux, List<ToolApprovalRequestContent> approvalRequests)
     {
-        string toolName = request.ToolCall is FunctionCallContent fc
-            ? ToolCallFormatter.Format(this._formatters, fc)
-            : request.ToolCall?.ToString() ?? "unknown";
-
-        var choices = new List<string>
+        if (approvalRequests.Count == 0)
         {
-            "Approve this call",
-            "Always approve this tool (any arguments)",
-            "Always approve this tool with these arguments",
-            "Deny",
-        };
+            return null;
+        }
 
-        string prompt = $"🔐 Tool approval: {toolName}";
+        var responses = new List<AIContent>();
+        foreach (var request in approvalRequests)
+        {
+            string toolName = request.ToolCall is FunctionCallContent fc
+                ? ToolCallFormatter.Format(fc)
+                : request.ToolCall?.ToString() ?? "unknown";
 
-        return new ChoiceFollowUpQuestion(
-            Prompt: prompt,
-            Choices: choices,
-            AllowCustomText: false,
-            Continuation: async (selection, ux) =>
+            var choices = new List<string>
             {
-                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"),
-                };
+                "Approve this call",
+                "Always approve this tool (any arguments)",
+                "Always approve this tool with these arguments",
+                "Deny",
+            };
 
-                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 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"),
+            };
 
-                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);
+            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);
 
-                return new ChatMessage(ChatRole.User, [response]);
-            });
+            responses.Add(response);
+        }
+
+        return [new ChatMessage(ChatRole.User, responses)];
     }
 }

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

@@ -1,7 +1,5 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-using Harness.Shared.Console.ToolFormatters;
-using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 
 namespace Harness.Shared.Console.Observers;
@@ -10,26 +8,14 @@ namespace Harness.Shared.Console.Observers;
 /// Displays tool call notifications (🔧) for <see cref="FunctionCallContent"/>
 /// and <see cref="ToolCallContent"/> items in the response stream.
 /// </summary>
-public sealed class ToolCallDisplayObserver : ConsoleObserver
+internal 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(IUXStateDriver ux, AIContent content, AIAgent agent, AgentSession session)
+    public override async Task OnContentAsync(HarnessUXContainer ux, AIContent content)
     {
         if (content is FunctionCallContent functionCall)
         {
-            await ux.WriteInfoLineAsync($"🔧 Calling tool: {ToolCallFormatter.Format(this._formatters, functionCall)}...", ConsoleColor.DarkYellow);
+            await ux.WriteInfoLineAsync($"🔧 Calling tool: {ToolCallFormatter.Format(functionCall)}...", ConsoleColor.DarkYellow);
         }
         else if (content is ToolCallContent toolCall)
         {

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

@@ -0,0 +1,288 @@
+// 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,6 +1,5 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 
 namespace Harness.Shared.Console.Observers;
@@ -8,7 +7,7 @@ namespace Harness.Shared.Console.Observers;
 /// <summary>
 /// Displays token usage statistics (📊) from the response stream.
 /// </summary>
-public sealed class UsageDisplayObserver : ConsoleObserver
+internal sealed class UsageDisplayObserver : ConsoleObserver
 {
     private readonly int? _maxContextWindowTokens;
     private readonly int? _maxOutputTokens;
@@ -25,7 +24,7 @@ public sealed class UsageDisplayObserver : ConsoleObserver
     }
 
     /// <inheritdoc/>
-    public override Task OnContentAsync(IUXStateDriver ux, AIContent content, AIAgent agent, AgentSession session)
+    public override Task OnContentAsync(HarnessUXContainer ux, AIContent content)
     {
         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>
-internal enum OutputEntryType
+public enum OutputEntryType
 {
     /// <summary>User input echo (e.g. "You: hello").</summary>
     UserInput,
@@ -25,10 +25,9 @@ internal enum OutputEntryType
 
 /// <summary>
 /// Represents a single output entry in the console conversation history.
-/// Used internally by <see cref="HarnessConsoleUXStateDriver"/> to track
-/// the in-progress streaming entry and last-entry type for spacing decisions.
+/// These entries are rendered by the <see cref="HarnessAppComponent"/> via its render delegate.
 /// </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>
-internal sealed record OutputEntry(OutputEntryType Type, string Text, ConsoleColor? Color = null);
+public record OutputEntry(OutputEntryType Type, string Text, ConsoleColor? Color = null);

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

@@ -1,51 +0,0 @@
-// 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

@@ -1,61 +0,0 @@
-// 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

@@ -1,27 +0,0 @@
-// 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

@@ -1,101 +0,0 @@
-// 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

@@ -1,84 +0,0 @@
-// 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

@@ -1,135 +0,0 @@
-// 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

@@ -1,22 +0,0 @@
-// 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

@@ -1,23 +0,0 @@
-// 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/Program.cs

@@ -8,8 +8,7 @@
 //
 // Special commands:
 //   /todos  — Display the current todo list without invoking the agent.
-//   /mode   — Get or set the current agent mode.
-//   /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 +16,6 @@
 using System.ClientModel.Primitives;
 using Azure.Identity;
 using Harness.Shared.Console;
-using Harness.Shared.Console.ToolFormatters;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 using OpenAI;
@@ -160,15 +158,13 @@ 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
     {
-        Observers = HarnessConsoleOptions.BuildObserversWithPlanning(
-            agent,
-            planModeName: "plan",
-            executionModeName: "execute",
-            maxContextWindowTokens: MaxContextWindowTokens,
-            maxOutputTokens: MaxOutputTokens,
-            toolFormatters: [new DownloadUriToolFormatter(), .. ToolCallFormatter.BuildDefaultToolFormatters()]),
-        CommandHandlers = HarnessConsoleOptions.BuildDefaultCommandHandlers(agent),
+        MaxContextWindowTokens = MaxContextWindowTokens,
+        MaxOutputTokens = MaxOutputTokens,
+        EnablePlanningUx = true,
+        PlanningModeName = "plan",
+        ExecutionModeName = "execute"
     });

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.
@@ -103,4 +103,5 @@ AIAgent parentAgent =
 // 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_Step03_DataProcessing/Program.cs

@@ -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.
@@ -85,4 +85,5 @@ AIAgent agent =
 // 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/03-workflows/Declarative/InvokeFoundryToolboxMcp/InvokeFoundryToolboxMcp.csproj

@@ -1,42 +0,0 @@
-<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

@@ -1,87 +0,0 @@
-#
-# 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

@@ -1,218 +0,0 @@
-// 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/src/Microsoft.Agents.AI.DevUI/DevUIAuthFilter.cs

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

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

@@ -100,7 +100,10 @@ public static class DevUIExtensions
 
         if (options.AllowRemoteAccess && !tokenConfigured && options.ConfigureEndpoints is null)
         {
-            DevUILog.InsecurelyExposed(logger, DevUIOptions.AuthTokenEnvironmentVariable);
+            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);
         }
     }
 }

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

@@ -1,20 +0,0 @@
-// 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.Harness/HarnessAgent.cs

@@ -17,7 +17,6 @@ namespace Microsoft.Agents.AI;
 /// <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>
@@ -111,7 +110,6 @@ public sealed class HarnessAgent : DelegatingAIAgent
         return chatClient
             .AsBuilder()
             .UseFunctionInvocation()
-            .UseMessageInjection()
             .UsePerServiceCallChatHistoryPersistence()
             .UseAIContextProviders(compactionProvider)
             .BuildAIAgent(new ChatClientAgentOptions

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

@@ -3,15 +3,12 @@
 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;
 
@@ -27,14 +24,6 @@ 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 = [];
@@ -64,17 +53,8 @@ public sealed class DefaultMcpToolHandler : IMcpToolHandler, IAsyncDisposable
         CancellationToken cancellationToken = default)
     {
         // TODO: Handle connectionName and server label appropriately when Hosted scenario supports them. For now, ignore
-        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());
+        McpClient client = await this.GetOrCreateClientAsync(serverUrl, serverLabel, headers, cancellationToken).ConfigureAwait(false);
 
         // Convert IDictionary to IReadOnlyDictionary for CallToolAsync
         IReadOnlyDictionary<string, object?>? readOnlyArguments = arguments is null
@@ -92,23 +72,6 @@ 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()
     {
@@ -220,16 +183,6 @@ 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
@@ -277,17 +230,6 @@ 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),
         };
     }
@@ -313,39 +255,4 @@ 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/HandoffWorkflowBuilder.cs

@@ -54,8 +54,6 @@ 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.
@@ -99,20 +97,6 @@ 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"/>
@@ -346,16 +330,7 @@ public class HandoffWorkflowBuilderCore<TBuilder> where TBuilder : HandoffWorkfl
             builder.AddEdge(start, executors[this._initialAgent.Id]);
         }
 
-        if (!string.IsNullOrWhiteSpace(this._name))
-        {
-            builder.WithName(this._name);
-        }
-
-        if (!string.IsNullOrWhiteSpace(this._description))
-        {
-            builder.WithDescription(this._description);
-        }
-
+        // Build the workflow.
         return builder.WithOutputFrom(end).Build();
     }
 }

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

@@ -1,6 +1,5 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-using System;
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 using System.Threading.Tasks;
@@ -141,15 +140,7 @@ public class MagenticWorkflowBuilder(AIAgent managerAgent)
     }
 
     /// <inheritdoc cref="WorkflowBuilder.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();
-    }
+    public Workflow Build() => this.ReduceToWorkflowBuilder().Build();
 
     private TaskLimits Limits => new(
         MaxRoundCount: this._maxRounds,

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

@@ -97,28 +97,6 @@ internal sealed class MessageMerger
         }
     }
 
-    private int CompareByDateTimeOffset(AgentResponse left, AgentResponse right)
-    {
-        const int LESS = -1, EQ = 0, GREATER = 1;
-
-        if (left.CreatedAt == right.CreatedAt)
-        {
-            return EQ;
-        }
-
-        if (!left.CreatedAt.HasValue)
-        {
-            return GREATER;
-        }
-
-        if (!right.CreatedAt.HasValue)
-        {
-            return LESS;
-        }
-
-        return left.CreatedAt.Value.CompareTo(right.CreatedAt.Value);
-    }
-
     public AgentResponse ComputeMerged(string primaryResponseId, string? primaryAgentId = null, string? primaryAgentName = null)
     {
         List<ChatMessage> messages = [];
@@ -126,6 +104,15 @@ internal sealed class MessageMerger
         HashSet<string> agentIds = [];
         HashSet<ChatFinishReason> finishReasons = [];
 
+        // Ordering contract (see docs/decisions/0026-message-merger-invariants.md):
+        // - Outer loop iterates ResponseIds in first-seen order, which preserves step
+        //   ordering: each agent invocation owns its own ResponseId, and successive
+        //   super-steps emit their first update only after the prior step's updates
+        //   have all arrived. Iterating Dictionary<,>.Keys preserves insertion order.
+        // - Inner loop iterates MessageIds in first-seen order, then appends dangling
+        //   updates last. This preserves emission order within an agent's block.
+        // We deliberately do NOT sort by CreatedAt: timestamps from concurrent agents
+        // or different clocks would interleave per-agent blocks and break Goal 1.
         foreach (string responseId in this._mergeStates.Keys)
         {
             ResponseMergeState mergeState = this._mergeStates[responseId];
@@ -136,14 +123,12 @@ internal sealed class MessageMerger
                 responseList.Add(mergeState.ComputeDangling());
             }
 
-            responseList.Sort(this.CompareByDateTimeOffset);
             responses[responseId] = responseList.Aggregate(MergeResponses);
             messages.AddRange(GetMessagesWithCreatedAt(responses[responseId]));
         }
 
         UsageDetails? usage = null;
         AdditionalPropertiesDictionary? additionalProperties = null;
-        HashSet<DateTimeOffset> createdTimes = [];
 
         foreach (AgentResponse response in responses.Values)
         {
@@ -152,11 +137,6 @@ internal sealed class MessageMerger
                 agentIds.Add(response.AgentId);
             }
 
-            if (response.CreatedAt.HasValue)
-            {
-                createdTimes.Add(response.CreatedAt.Value);
-            }
-
             if (response.FinishReason.HasValue)
             {
                 finishReasons.Add(response.FinishReason.Value);

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

@@ -433,6 +433,18 @@ internal sealed class HandoffAgentExecutor :
             FunctionCallContent handoffRequest = candidateRequests[candidateRequests.Count - 1];
             requestedHandoff = handoffRequest.Name;
 
+            // Stamp the synthetic "Transferred." tool-result update with the same
+            // ResponseId as the agent's preceding updates so it groups with the
+            // rest of this agent's step in MessageMerger (and therefore in
+            // RunAsync's merged AgentResponse and in chat history). Without this,
+            // the synthetic update goes to MessageMerger's null-ResponseId
+            // "dangling" bucket and surfaces after every keyed response, which
+            // re-orders multi-step handoff transcripts versus streaming output
+            // (issue #4544).
+            string? syntheticResponseId = updates
+                .Select(u => u.ResponseId)
+                .LastOrDefault(id => id is not null);
+
             await AddUpdateAsync(
                     new AgentResponseUpdate
                     {
@@ -441,6 +453,7 @@ internal sealed class HandoffAgentExecutor :
                         Contents = [CreateHandoffResult(handoffRequest.CallId)],
                         CreatedAt = DateTimeOffset.UtcNow,
                         MessageId = Guid.NewGuid().ToString("N"),
+                        ResponseId = syntheticResponseId,
                         Role = ChatRole.Tool,
                     },
                     cancellationToken

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

@@ -101,7 +101,6 @@ 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>(
@@ -110,7 +109,7 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
                 out this._planReviewPort);
     }
 
-    private ValueTask SubmitPlanReviewRequestAsync(MagenticTaskContext taskContext, IWorkflowContext workflowContext, bool replanAfterStall = false)
+    private ValueTask SubmitPlanReviewRequestAsync(MagenticTaskContext taskContext, IWorkflowContext workflowContext)
     {
         MagenticProgressLedger? progressLedger = taskContext.ProgressLedger;
         if (progressLedger?.IsStarted is not true)
@@ -118,7 +117,7 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
             progressLedger = null;
         }
 
-        MagenticPlanReviewRequest request = new(taskContext.TaskLedger!.CurrentPlan, progressLedger, replanAfterStall);
+        MagenticPlanReviewRequest request = new(taskContext.TaskLedger!.CurrentPlan, progressLedger, taskContext.IsStalled);
 
         return this._planReviewPort!.PostRequestAsync(request);
     }
@@ -147,7 +146,7 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
 
         if (this._taskContext.IsTerminated)
         {
-            throw new InvalidOperationException("This Magentic orchestration has already terminated. To process new messages, create a new workflow instance.");
+            throw new InvalidOperationException("Magentic Orchestration has already been terminated and cannot process new messages. Please start a new session.");
         }
 
         if (response.IsApproved)
@@ -162,7 +161,7 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
         }
     }
 
-    private async ValueTask UpdatePlanAndDelegateAsync(MagenticTaskContext taskContext, IWorkflowContext context, CancellationToken cancellationToken, bool replanAfterStall = false)
+    private async ValueTask UpdatePlanAndDelegateAsync(MagenticTaskContext taskContext, IWorkflowContext context, CancellationToken cancellationToken)
     {
         bool isReplan = taskContext.TaskLedger != null;
 
@@ -178,7 +177,7 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
 
         if (requirePlanSignoff)
         {
-            await this.SubmitPlanReviewRequestAsync(taskContext, context, replanAfterStall).ConfigureAwait(false);
+            await this.SubmitPlanReviewRequestAsync(taskContext, context).ConfigureAwait(false);
         }
         else
         {
@@ -188,22 +187,9 @@ internal class MagenticOrchestrator(AIAgent managerAgent, List<AIAgent> team, Ta
 
     protected override async ValueTask TakeTurnAsync(List<ChatMessage> messages, IWorkflowContext context, bool? emitEvents, CancellationToken cancellationToken = default)
     {
-        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);
-        }
+        // 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);
     }
 
     private ChatMessage? _fullTaskLedgerMessage;
@@ -302,11 +288,10 @@ 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, replanAfterStall: wasStalled).ConfigureAwait(false);
+        await this.UpdatePlanAndDelegateAsync(taskContext, context, cancellationToken).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,13 +36,9 @@ 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;
@@ -68,13 +64,8 @@ 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,11 +25,7 @@ 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)
-    {
-        Throw.IfNull(target, nameof(target));
-
-        return builder.ForwardMessage<TMessage>(source, [target], condition: null);
-    }
+        => 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
@@ -56,8 +52,6 @@ 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)!;
@@ -68,16 +62,14 @@ public static class WorkflowBuilderExtensions
         if (targets is ICollection<ExecutorBinding> { Count: 1 })
 #endif
         {
-            return builder.AddEdge(source, Throw.IfNull(targets.First(), nameof(targets)), predicate);
+            return builder.AddEdge(source, targets.First(), predicate);
         }
 
-        return builder.AddSwitch(source, (switch_) => switch_.AddCase(predicate, targets.Select(ValidateTarget)));
+        return builder.AddSwitch(source, (switch_) => switch_.AddCase(predicate, targets));
 
         // 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>
@@ -89,11 +81,7 @@ 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)
-    {
-        Throw.IfNull(target, nameof(target));
-
-        return builder.ForwardExcept<TMessage>(source, [target]);
-    }
+        => builder.ForwardExcept<TMessage>(source, [target]);
 
     /// <summary>
     /// Adds edges from the specified source to the provided executors, excluding messages of a specified type.
@@ -105,8 +93,6 @@ 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)!;
@@ -117,16 +103,14 @@ public static class WorkflowBuilderExtensions
         if (targets is ICollection<ExecutorBinding> { Count: 1 })
 #endif
         {
-            return builder.AddEdge(source, Throw.IfNull(targets.First(), nameof(targets)), predicate);
+            return builder.AddEdge(source, targets.First(), predicate);
         }
 
-        return builder.AddSwitch(source, (switch_) => switch_.AddCase(predicate, targets.Select(ValidateTarget)));
+        return builder.AddSwitch(source, (switch_) => switch_.AddCase(predicate, targets));
 
         // 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>
@@ -145,7 +129,6 @@ 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,7 +122,6 @@ 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();
@@ -158,12 +157,6 @@ 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)
             {
@@ -238,7 +231,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, rooted paths, or symbolic links.
+    /// Rejects paths that would escape the root via traversal or rooted paths.
     /// </summary>
     private string ResolveSafePath(string relativePath)
     {
@@ -257,55 +250,9 @@ 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/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(Skip = "Flaky in merge_group; see https://github.com/microsoft/agent-framework/issues/5845")]
+    [Fact]
     public async Task TestServerWithDevUI_ResolvesMixedAgentsAndWorkflows_AllRegistrationsAsync()
     {
         // Arrange

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

@@ -103,30 +103,6 @@ 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,475 +334,4 @@ 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.Workflows.Declarative.Mcp.UnitTests/DefaultMcpToolHandlerTests.cs

@@ -4,7 +4,6 @@ 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;
@@ -321,92 +320,6 @@ 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]
@@ -575,75 +488,5 @@ 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,44 +432,6 @@ 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/HandoffOrchestrationTests.cs

@@ -86,23 +86,6 @@ 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()
     {
@@ -321,6 +304,208 @@ public class HandoffOrchestrationTests
         Assert.DoesNotContain(capturedThirdAgentMessages, m => m.Role == ChatRole.Tool && m.Contents.Any(c => c is FunctionResultContent));
     }
 
+    [Fact]
+    public async Task Handoffs_MultipleTransfers_MergedMessagesPreserveStepOrderAsync()
+    {
+        // Regression test for https://github.com/microsoft/agent-framework/issues/4544
+        //
+        // Scenario: a multi-step handoff (A -> B -> C) is run through a workflow
+        // exposed as an AIAgent. When invoked via the non-streaming RunAsync
+        // entry-point, the merged AgentResponse.Messages must keep each step's
+        // messages contiguous — in particular, the "Transferred." tool result
+        // synthesized for a handoff function call must appear immediately after
+        // the function call that triggered it, before any messages from later
+        // steps. Streaming output already preserves this order; the bug
+        // manifested only after merging, where the synthesized tool results were
+        // bunched at the end of the response, far from their originating function
+        // calls (and consequently corrupted ChatHistory order).
+        //
+        // Each underlying agent response sets a real ResponseId — that is what
+        // causes MessageMerger to group its updates under that key. If the
+        // synthesized Tool update is emitted without that ResponseId, the merger
+        // routes it to the global "dangling" bucket and flushes it last,
+        // breaking per-step grouping.
+
+        var initialAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
+        {
+            string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
+            Assert.NotNull(transferFuncName);
+            return new(new ChatMessage(ChatRole.Assistant, [new TextContent("Routing to second agent"), new FunctionCallContent("call1", transferFuncName)]) { MessageId = "msg-initial" }) { ResponseId = "resp-initial" };
+        }), name: "initialAgent");
+
+        var secondAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
+        {
+            string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
+            Assert.NotNull(transferFuncName);
+            return new(new ChatMessage(ChatRole.Assistant, [new TextContent("Routing to third agent"), new FunctionCallContent("call2", transferFuncName)]) { MessageId = "msg-second" }) { ResponseId = "resp-second" };
+        }), name: "secondAgent", description: "The second agent");
+
+        var thirdAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
+            new(new ChatMessage(ChatRole.Assistant, "Hello from agent3") { MessageId = "msg-third" }) { ResponseId = "resp-third" }),
+            name: "thirdAgent",
+            description: "The third / final agent");
+
+        var workflow =
+            AgentWorkflowBuilder.CreateHandoffBuilderWith(initialAgent)
+            .WithHandoff(initialAgent, secondAgent)
+            .WithHandoff(secondAgent, thirdAgent)
+            .Build();
+
+        AIAgent hostAgent = workflow.AsAIAgent(name: "HandoffWorkflow");
+
+        AgentResponse response = await hostAgent.RunAsync("abc");
+
+        List<ChatMessage> result = response.Messages.ToList();
+
+        // Expected merged sequence keeps each step contiguous:
+        //   [0] Assistant (initialAgent): text + FunctionCall(call1)
+        //   [1] Tool (initialAgent): FunctionResult(call1, "Transferred.")
+        //   [2] Assistant (secondAgent): text + FunctionCall(call2)
+        //   [3] Tool (secondAgent): FunctionResult(call2, "Transferred.")
+        //   [4] Assistant (thirdAgent): "Hello from agent3"
+        //
+        // The bug surfaced as the two Tool messages being moved to the end of the
+        // list — after thirdAgent's reply — which broke chat-history ordering.
+        Assert.Equal(5, result.Count);
+
+        Assert.Equal(ChatRole.Assistant, result[0].Role);
+        Assert.Contains("initialAgent", result[0].AuthorName);
+        Assert.Contains(result[0].Contents, c => c is FunctionCallContent fcc && fcc.CallId == "call1");
+
+        Assert.Equal(ChatRole.Tool, result[1].Role);
+        Assert.Contains("initialAgent", result[1].AuthorName);
+        Assert.Contains(result[1].Contents, c => c is FunctionResultContent frc && frc.CallId == "call1");
+
+        Assert.Equal(ChatRole.Assistant, result[2].Role);
+        Assert.Contains("secondAgent", result[2].AuthorName);
+        Assert.Contains(result[2].Contents, c => c is FunctionCallContent fcc && fcc.CallId == "call2");
+
+        Assert.Equal(ChatRole.Tool, result[3].Role);
+        Assert.Contains("secondAgent", result[3].AuthorName);
+        Assert.Contains(result[3].Contents, c => c is FunctionResultContent frc && frc.CallId == "call2");
+
+        Assert.Equal(ChatRole.Assistant, result[4].Role);
+        Assert.Contains("thirdAgent", result[4].AuthorName);
+        Assert.Equal("Hello from agent3", result[4].Text);
+    }
+
+    [Fact]
+    public async Task Handoffs_CoordSpecCoordPingPong_MergedMessagesPreserveStepOrderAsync()
+    {
+        // Regression test for https://github.com/microsoft/agent-framework/issues/4544 /
+        // https://github.com/microsoft/agent-framework/issues/5720.
+        //
+        // Scenario mirrors the user-reported "Coord -> Spec -> Coord" ping-pong where
+        // the same coordinator agent is invoked twice (first to hand off to the
+        // specialist, then a final time to summarize). Additionally exercises the
+        // case where the specialist returns its assistant text and its handoff
+        // FunctionCall in two SEPARATE ChatMessages (i.e. different MessageIds),
+        // because real OpenAI streams sometimes split text and tool calls that way.
+        //
+        // The merged AgentResponse.Messages must preserve per-step grouping:
+        //   step 1 (Coord):  FunctionCall(call1) then synthesized FunctionResult(call1)
+        //   step 2 (Spec) :  TextContent "Here are recs" then FunctionCall(call2)
+        //                    then synthesized FunctionResult(call2)
+        //   step 3 (Coord):  TextContent "Here are recs"
+        // The bug previously bunched the FunctionResult ("Transferred.") tool messages
+        // at the very end, breaking the contiguity of each step's block.
+
+        int coordCallCount = 0;
+        int specCallCount = 0;
+        var coord = new ChatClientAgent(new MockChatClient((messages, options) =>
+        {
+            coordCallCount++;
+            if (coordCallCount == 1)
+            {
+                string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
+                Assert.NotNull(transferFuncName);
+                return new(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call_coord_1", transferFuncName)]) { MessageId = "coord-msg-1" })
+                {
+                    ResponseId = "resp-coord-1",
+                };
+            }
+
+            // Second (final) Coord turn: emit only assistant text - no tool call.
+            // The test asserts this turn does NOT emit a handoff_to_* FunctionCallContent
+            // and that the workflow terminates here (coordCallCount stays at 2).
+            return new(new ChatMessage(ChatRole.Assistant, "Here are two fake Excel course recommendations") { MessageId = "coord-msg-2" })
+            {
+                ResponseId = "resp-coord-2",
+            };
+        }), name: "Coord");
+
+        var spec = new ChatClientAgent(new MockChatClient((messages, options) =>
+        {
+            specCallCount++;
+            string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
+            Assert.NotNull(transferFuncName);
+
+            // Split text and FunctionCall into two separate ChatMessages (distinct MessageIds)
+            // to mirror the real-world streaming pattern where a specialist's narration
+            // and its handoff tool-call land in different ChatMessages.
+            return new(
+                [
+                    new ChatMessage(ChatRole.Assistant, "Here are two fake Excel course recommendations") { MessageId = "spec-msg-text" },
+                    new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call_spec_1", transferFuncName)]) { MessageId = "spec-msg-call" },
+                ])
+            {
+                ResponseId = "resp-spec-1",
+            };
+        }), name: "Spec", description: "The specialist agent");
+
+        var workflow =
+            AgentWorkflowBuilder.CreateHandoffBuilderWith(coord)
+            .WithHandoff(coord, spec)
+            .WithHandoff(spec, coord)
+            .Build();
+
+        AIAgent hostAgent = workflow.AsAIAgent(name: "HandoffWorkflow");
+
+        AgentResponse response = await hostAgent.RunAsync("Tell me about Excel courses.");
+
+        List<ChatMessage> result = response.Messages.ToList();
+
+        // Expected merged sequence keeps each step contiguous (6 messages):
+        //   [0] Assistant (Coord): FunctionCall(call_coord_1)
+        //   [1] Tool      (Coord): FunctionResult(call_coord_1, "Transferred.")
+        //   [2] Assistant (Spec) : TextContent "Here are recs"
+        //   [3] Assistant (Spec) : FunctionCall(call_spec_1)
+        //   [4] Tool      (Spec) : FunctionResult(call_spec_1, "Transferred.")
+        //   [5] Assistant (Coord): TextContent "Here are recs"
+        Assert.Equal(6, result.Count);
+
+        Assert.Equal(ChatRole.Assistant, result[0].Role);
+        Assert.Contains("Coord", result[0].AuthorName);
+        Assert.Contains(result[0].Contents, c => c is FunctionCallContent fcc && fcc.CallId == "call_coord_1");
+
+        Assert.Equal(ChatRole.Tool, result[1].Role);
+        Assert.Contains("Coord", result[1].AuthorName);
+        Assert.Contains(result[1].Contents, c => c is FunctionResultContent frc && frc.CallId == "call_coord_1");
+
+        Assert.Equal(ChatRole.Assistant, result[2].Role);
+        Assert.Contains("Spec", result[2].AuthorName);
+        Assert.Equal("Here are two fake Excel course recommendations", result[2].Text);
+
+        Assert.Equal(ChatRole.Assistant, result[3].Role);
+        Assert.Contains("Spec", result[3].AuthorName);
+        Assert.Contains(result[3].Contents, c => c is FunctionCallContent fcc && fcc.CallId == "call_spec_1");
+
+        Assert.Equal(ChatRole.Tool, result[4].Role);
+        Assert.Contains("Spec", result[4].AuthorName);
+        Assert.Contains(result[4].Contents, c => c is FunctionResultContent frc && frc.CallId == "call_spec_1");
+
+        Assert.Equal(ChatRole.Assistant, result[5].Role);
+        Assert.Contains("Coord", result[5].AuthorName);
+        Assert.Equal("Here are two fake Excel course recommendations", result[5].Text);
+
+        // Final Coord turn must emit ONLY assistant text - no further handoff/tool call.
+        Assert.DoesNotContain(result[5].Contents, c => c is FunctionCallContent);
+
+        // And the workflow must have terminated after that turn - no extra Coord/Spec re-invocations.
+        Assert.Equal(2, coordCallCount);
+        Assert.Equal(1, specCallCount);
+    }
+
     [Fact]
     public async Task Handoffs_FilteringNone_HandoffTargetReceivesAllMessagesIncludingToolCallsAsync()
     {

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

@@ -34,13 +34,7 @@ public sealed class InputWaiterTests : IDisposable
     [Fact]
     public async Task InputWaiter_WaitForInputAsync_BlocksUntilSignaledAsync()
     {
-        // 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);
+        Task waitTask = this._waiter.WaitForInputAsync(TimeSpan.FromSeconds(5));
 
         Task completedBeforeSignal = await Task.WhenAny(waitTask, Task.Delay(100));
         completedBeforeSignal.Should().NotBeSameAs(
@@ -106,21 +100,6 @@ 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/MessageMergerTests.cs

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System;
+using System.Linq;
 using FluentAssertions;
 using Microsoft.Extensions.AI;
 
@@ -42,6 +43,47 @@ public class MessageMergerTests
         response.FinishReason.Should().BeNull();
     }
 
+    [Fact]
+    public void Test_MessageMerger_PreservesFunctionCallOrderingWhenToolResultHasCreatedAt()
+    {
+        // Arrange
+        string responseId = Guid.NewGuid().ToString("N");
+        string functionCallMessageId = Guid.NewGuid().ToString("N");
+        string functionResultMessageId = Guid.NewGuid().ToString("N");
+        string callId = Guid.NewGuid().ToString("N");
+        DateTimeOffset toolResultCreatedAt = DateTimeOffset.UtcNow;
+
+        MessageMerger merger = new();
+
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseId,
+            MessageId = functionCallMessageId,
+            AgentId = TestAgentId1,
+            Role = ChatRole.Assistant,
+            Contents = [new FunctionCallContent(callId, "handoff_to_TestAgent2")],
+        });
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseId,
+            MessageId = functionResultMessageId,
+            AgentId = TestAgentId1,
+            CreatedAt = toolResultCreatedAt,
+            Role = ChatRole.Tool,
+            Contents = [new FunctionResultContent(callId, "Transferred.")],
+        });
+
+        // Act
+        AgentResponse response = merger.ComputeMerged(responseId);
+
+        // Assert
+        response.Messages.Should().HaveCount(2);
+        response.Messages[0].Role.Should().Be(ChatRole.Assistant);
+        response.Messages[0].Contents.Should().ContainSingle().Which.Should().BeOfType<FunctionCallContent>();
+        response.Messages[1].Role.Should().Be(ChatRole.Tool);
+        response.Messages[1].Contents.Should().ContainSingle().Which.Should().BeOfType<FunctionResultContent>();
+    }
+
     [Fact]
     public void Test_MessageMerger_PropagatesFinishReasonFromUpdates()
     {
@@ -71,4 +113,494 @@ public class MessageMergerTests
         // Assert - FinishReason from the update should propagate through
         response.FinishReason.Should().Be(ChatFinishReason.ContentFilter);
     }
+
+    #region Invariant 2: Output Order Preservation Tests
+
+    [Fact]
+    public void Test_MessageMerger_PreservesInsertionOrder_WhenNoTimestamps()
+    {
+        // Arrange: Multiple updates without CreatedAt, in specific order A, B, C
+        string responseId = Guid.NewGuid().ToString("N");
+        string messageIdA = Guid.NewGuid().ToString("N");
+        string messageIdB = Guid.NewGuid().ToString("N");
+        string messageIdC = Guid.NewGuid().ToString("N");
+
+        MessageMerger merger = new();
+
+        // Add updates without CreatedAt in order A, B, C
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseId,
+            MessageId = messageIdA,
+            Role = ChatRole.Assistant,
+            Contents = [new TextContent("Message A")],
+            // No CreatedAt
+        });
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseId,
+            MessageId = messageIdB,
+            Role = ChatRole.Assistant,
+            Contents = [new TextContent("Message B")],
+            // No CreatedAt
+        });
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseId,
+            MessageId = messageIdC,
+            Role = ChatRole.Assistant,
+            Contents = [new TextContent("Message C")],
+            // No CreatedAt
+        });
+
+        // Act
+        AgentResponse response = merger.ComputeMerged(responseId);
+
+        // Assert: Output order should be A, B, C (insertion order)
+        response.Messages.Should().HaveCount(3);
+        response.Messages[0].Text.Should().Be("Message A");
+        response.Messages[1].Text.Should().Be("Message B");
+        response.Messages[2].Text.Should().Be("Message C");
+    }
+
+    [Fact]
+    public void Test_MessageMerger_PreservesInsertionOrder_WhenMixedTimestamps()
+    {
+        // Arrange: Updates with OUT-OF-ORDER timestamps relative to emission order.
+        // Emission order: A, B, C.
+        // Timestamp order: C (oldest), A, B (newest) - reverse of emission.
+        // Per Invariant 2, emission order wins; timestamps are ignored for ordering.
+        string responseId = Guid.NewGuid().ToString("N");
+        string messageIdA = Guid.NewGuid().ToString("N");
+        string messageIdB = Guid.NewGuid().ToString("N");
+        string messageIdC = Guid.NewGuid().ToString("N");
+
+        DateTimeOffset timeOldest = DateTimeOffset.UtcNow.AddMinutes(-10);
+        DateTimeOffset timeMiddle = DateTimeOffset.UtcNow.AddMinutes(-5);
+        DateTimeOffset timeNewest = DateTimeOffset.UtcNow;
+
+        MessageMerger merger = new();
+
+        // Emit A first but stamp it with timeMiddle.
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseId,
+            MessageId = messageIdA,
+            Role = ChatRole.Assistant,
+            CreatedAt = timeMiddle,
+            Contents = [new TextContent("Message A")],
+        });
+        // Emit B second, without a timestamp.
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseId,
+            MessageId = messageIdB,
+            Role = ChatRole.Assistant,
+            // No CreatedAt
+            Contents = [new TextContent("Message B")],
+        });
+        // Emit C third but stamp it with timeOldest - if we sorted by timestamp,
+        // C would come first; the new merger MUST keep emission order (A, B, C).
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseId,
+            MessageId = messageIdC,
+            Role = ChatRole.Assistant,
+            CreatedAt = timeOldest,
+            Contents = [new TextContent("Message C")],
+        });
+        // Stamp a fourth message with the newest timestamp - it should still come last
+        // because it was emitted last, not because of its timestamp.
+        string messageIdD = Guid.NewGuid().ToString("N");
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseId,
+            MessageId = messageIdD,
+            Role = ChatRole.Assistant,
+            CreatedAt = timeNewest,
+            Contents = [new TextContent("Message D")],
+        });
+
+        // Act
+        AgentResponse response = merger.ComputeMerged(responseId);
+
+        // Assert: Emission order wins; CreatedAt is ignored for ordering.
+        response.Messages.Should().HaveCount(4);
+        response.Messages[0].Text.Should().Be("Message A");
+        response.Messages[1].Text.Should().Be("Message B");
+        response.Messages[2].Text.Should().Be("Message C");
+        response.Messages[3].Text.Should().Be("Message D");
+    }
+
+    [Fact]
+    public void Test_MessageMerger_ReproducibleOrdering_WithMixedTimestamps()
+    {
+        // Arrange: 3+ messages with mixed null/non-null CreatedAt values
+        // This tests that the same input sequence produces the same output
+        // (run-to-run reproducibility for a fixed input)
+        string responseId = Guid.NewGuid().ToString("N");
+        string messageIdA = Guid.NewGuid().ToString("N");
+        string messageIdB = Guid.NewGuid().ToString("N");
+        string messageIdC = Guid.NewGuid().ToString("N");
+
+        DateTimeOffset time10 = DateTimeOffset.UtcNow.AddSeconds(10);
+        DateTimeOffset time5 = DateTimeOffset.UtcNow.AddSeconds(5);
+
+        MessageMerger merger = new();
+
+        // A: CreatedAt = time10, idx=0
+        // B: CreatedAt = null, idx=1
+        // C: CreatedAt = time5, idx=2
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseId,
+            MessageId = messageIdA,
+            Role = ChatRole.Assistant,
+            CreatedAt = time10,
+            Contents = [new TextContent("Message A (T=10)")],
+        });
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseId,
+            MessageId = messageIdB,
+            Role = ChatRole.Assistant,
+            // No CreatedAt
+            Contents = [new TextContent("Message B (no timestamp)")],
+        });
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseId,
+            MessageId = messageIdC,
+            Role = ChatRole.Assistant,
+            CreatedAt = time5,
+            Contents = [new TextContent("Message C (T=5)")],
+        });
+
+        // Act - Run multiple times to verify reproducibility
+        AgentResponse response1 = merger.ComputeMerged(responseId);
+
+        // Create a fresh merger with same data to verify reproducibility
+        MessageMerger merger2 = new();
+        merger2.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseId,
+            MessageId = messageIdA,
+            Role = ChatRole.Assistant,
+            CreatedAt = time10,
+            Contents = [new TextContent("Message A (T=10)")],
+        });
+        merger2.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseId,
+            MessageId = messageIdB,
+            Role = ChatRole.Assistant,
+            Contents = [new TextContent("Message B (no timestamp)")],
+        });
+        merger2.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseId,
+            MessageId = messageIdC,
+            Role = ChatRole.Assistant,
+            CreatedAt = time5,
+            Contents = [new TextContent("Message C (T=5)")],
+        });
+        AgentResponse response2 = merger2.ComputeMerged(responseId);
+
+        // Assert: Result is reproducible and consistent across runs with same input order.
+        // Per Invariant 2, both runs must produce emission order (A, B, C) regardless
+        // of the messages' CreatedAt values.
+        response1.Messages.Should().HaveCount(3);
+        response2.Messages.Should().HaveCount(3);
+
+        response1.Messages.Select(m => m.Text).Should().ContainInOrder(
+            "Message A (T=10)", "Message B (no timestamp)", "Message C (T=5)");
+
+        // Both runs should produce identical ordering
+        for (int i = 0; i < 3; i++)
+        {
+            response1.Messages[i].Text.Should().Be(response2.Messages[i].Text);
+        }
+    }
+
+    #endregion
+
+    #region Invariant 3: Agent Message Grouping Tests
+
+    [Fact]
+    public void Test_MessageMerger_GroupsMessagesByResponseId_InMultiAgentScenario()
+    {
+        // Arrange: Interleaved updates from Agent1 (R1) and Agent2 (R2)
+        string responseIdR1 = Guid.NewGuid().ToString("N");
+        string responseIdR2 = Guid.NewGuid().ToString("N");
+        string messageIdA1M1 = Guid.NewGuid().ToString("N");
+        string messageIdA1M2 = Guid.NewGuid().ToString("N");
+        string messageIdA2M1 = Guid.NewGuid().ToString("N");
+        string messageIdA2M2 = Guid.NewGuid().ToString("N");
+
+        MessageMerger merger = new();
+
+        // Interleaved arrival: A1-msg1, A2-msg1, A1-msg2, A2-msg2
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseIdR1,
+            MessageId = messageIdA1M1,
+            AgentId = TestAgentId1,
+            Role = ChatRole.Assistant,
+            Contents = [new TextContent("Agent1 Message 1")],
+        });
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseIdR2,
+            MessageId = messageIdA2M1,
+            AgentId = TestAgentId2,
+            Role = ChatRole.Assistant,
+            Contents = [new TextContent("Agent2 Message 1")],
+        });
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseIdR1,
+            MessageId = messageIdA1M2,
+            AgentId = TestAgentId1,
+            Role = ChatRole.Assistant,
+            Contents = [new TextContent("Agent1 Message 2")],
+        });
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseIdR2,
+            MessageId = messageIdA2M2,
+            AgentId = TestAgentId2,
+            Role = ChatRole.Assistant,
+            Contents = [new TextContent("Agent2 Message 2")],
+        });
+
+        // Act
+        AgentResponse response = merger.ComputeMerged(responseIdR1);
+
+        // Assert: Messages should be grouped by ResponseId (which groups by agent)
+        // Output should be either [A1-msg1, A1-msg2, A2-msg1, A2-msg2] or [A2-msg1, A2-msg2, A1-msg1, A1-msg2]
+        // The key invariant: Agent1's messages are contiguous, Agent2's messages are contiguous
+        response.Messages.Should().HaveCount(4);
+
+        // Verify grouping - collect message texts and verify they're grouped by agent
+        var messageTexts = response.Messages.Select(m => m.Text).ToList();
+
+        // Find first Agent1 message index and first Agent2 message index
+        int firstA1Index = messageTexts.FindIndex(t => t.StartsWith("Agent1", StringComparison.Ordinal));
+        int firstA2Index = messageTexts.FindIndex(t => t.StartsWith("Agent2", StringComparison.Ordinal));
+
+        // Assert both indices are valid (messages were found)
+        firstA1Index.Should().BeGreaterThanOrEqualTo(0, "Agent1 messages should be present in response");
+        firstA2Index.Should().BeGreaterThanOrEqualTo(0, "Agent2 messages should be present in response");
+
+        // All Agent1 messages should be contiguous (either at start or after all Agent2 messages)
+        var a1Messages = messageTexts.Where(t => t.StartsWith("Agent1", StringComparison.Ordinal)).ToList();
+        var a2Messages = messageTexts.Where(t => t.StartsWith("Agent2", StringComparison.Ordinal)).ToList();
+
+        a1Messages.Should().HaveCount(2);
+        a2Messages.Should().HaveCount(2);
+
+        // Verify no interleaving: if A1 comes first, A2 should come after all A1 messages
+        if (firstA1Index < firstA2Index)
+        {
+            // A1 messages at indices 0, 1 and A2 messages at indices 2, 3
+            messageTexts[0].Should().StartWith("Agent1");
+            messageTexts[1].Should().StartWith("Agent1");
+            messageTexts[2].Should().StartWith("Agent2");
+            messageTexts[3].Should().StartWith("Agent2");
+        }
+        else
+        {
+            // A2 messages at indices 0, 1 and A1 messages at indices 2, 3
+            messageTexts[0].Should().StartWith("Agent2");
+            messageTexts[1].Should().StartWith("Agent2");
+            messageTexts[2].Should().StartWith("Agent1");
+            messageTexts[3].Should().StartWith("Agent1");
+        }
+    }
+
+    [Fact]
+    public void Test_MessageMerger_MaintainsAgentGrouping_WithDifferentResponseIds()
+    {
+        // Arrange: Agent1 uses ResponseId=R1, Agent2 uses ResponseId=R2
+        // Multiple messages per ResponseId to properly test contiguity
+        string responseIdR1 = Guid.NewGuid().ToString("N");
+        string responseIdR2 = Guid.NewGuid().ToString("N");
+        string messageIdA1M1 = Guid.NewGuid().ToString("N");
+        string messageIdA1M2 = Guid.NewGuid().ToString("N");
+        string messageIdA1M3 = Guid.NewGuid().ToString("N");
+        string messageIdA2M1 = Guid.NewGuid().ToString("N");
+        string messageIdA2M2 = Guid.NewGuid().ToString("N");
+        string messageIdA2M3 = Guid.NewGuid().ToString("N");
+
+        MessageMerger merger = new();
+
+        // Interleaved arrival: A1-1, A2-1, A1-2, A2-2, A1-3, A2-3
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseIdR1,
+            MessageId = messageIdA1M1,
+            AgentId = TestAgentId1,
+            Role = ChatRole.Assistant,
+            Contents = [new TextContent("Agent1 Response 1")],
+        });
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseIdR2,
+            MessageId = messageIdA2M1,
+            AgentId = TestAgentId2,
+            Role = ChatRole.Assistant,
+            Contents = [new TextContent("Agent2 Response 1")],
+        });
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseIdR1,
+            MessageId = messageIdA1M2,
+            AgentId = TestAgentId1,
+            Role = ChatRole.Assistant,
+            Contents = [new TextContent("Agent1 Response 2")],
+        });
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseIdR2,
+            MessageId = messageIdA2M2,
+            AgentId = TestAgentId2,
+            Role = ChatRole.Assistant,
+            Contents = [new TextContent("Agent2 Response 2")],
+        });
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseIdR1,
+            MessageId = messageIdA1M3,
+            AgentId = TestAgentId1,
+            Role = ChatRole.Assistant,
+            Contents = [new TextContent("Agent1 Response 3")],
+        });
+        merger.AddUpdate(new AgentResponseUpdate
+        {
+            ResponseId = responseIdR2,
+            MessageId = messageIdA2M3,
+            AgentId = TestAgentId2,
+            Role = ChatRole.Assistant,
+            Contents = [new TextContent("Agent2 Response 3")],
+        });
+
+        // Act
+        AgentResponse response = merger.ComputeMerged(responseIdR1);
+
+        // Assert: Messages from each agent are contiguous (not interleaved)
+        response.Messages.Should().HaveCount(6);
+
+        var messageTexts = response.Messages.Select(m => m.Text).ToList();
+
+        // Verify all messages are present
+        messageTexts.Should().Contain("Agent1 Response 1");
+        messageTexts.Should().Contain("Agent1 Response 2");
+        messageTexts.Should().Contain("Agent1 Response 3");
+        messageTexts.Should().Contain("Agent2 Response 1");
+        messageTexts.Should().Contain("Agent2 Response 2");
+        messageTexts.Should().Contain("Agent2 Response 3");
+
+        // Find indices to verify contiguity
+        int firstA1Index = messageTexts.FindIndex(t => t.StartsWith("Agent1", StringComparison.Ordinal));
+        int lastA1Index = messageTexts.FindLastIndex(t => t.StartsWith("Agent1", StringComparison.Ordinal));
+        int firstA2Index = messageTexts.FindIndex(t => t.StartsWith("Agent2", StringComparison.Ordinal));
+        int lastA2Index = messageTexts.FindLastIndex(t => t.StartsWith("Agent2", StringComparison.Ordinal));
+
+        // Assert indices are valid
+        firstA1Index.Should().BeGreaterThanOrEqualTo(0, "Agent1 messages should be present");
+        firstA2Index.Should().BeGreaterThanOrEqualTo(0, "Agent2 messages should be present");
+
+        // Verify contiguity: all Agent1 messages should span exactly 3 consecutive indices
+        (lastA1Index - firstA1Index).Should().Be(2, "Agent1 messages should be contiguous (3 messages spanning 2 index gaps)");
+        (lastA2Index - firstA2Index).Should().Be(2, "Agent2 messages should be contiguous (3 messages spanning 2 index gaps)");
+
+        // Verify no interleaving: ranges should not overlap
+        bool a1BeforeA2 = lastA1Index < firstA2Index;
+        bool a2BeforeA1 = lastA2Index < firstA1Index;
+        (a1BeforeA2 || a2BeforeA1).Should().BeTrue("Agent message blocks should not interleave");
+    }
+
+    #endregion
+
+    #region Step Ordering Tests (workflow goals)
+
+    [Fact]
+    public void Test_MessageMerger_OrdersStepsBeforeNextStep_AndGroupsAgentsWithinStep()
+    {
+        // Scenario mirroring the workflow ordering goals:
+        //   Step 1: Agent1 alone emits 2 updates.
+        //   Step 2: Agent1 and Agent2 emit updates interleaved (concurrent in the step).
+        //   Step 3: Agent2 alone emits 2 updates.
+        // Each agent invocation has its own ResponseId, so per-ResponseId grouping
+        // yields per-agent grouping. Steps are naturally serialized in emission
+        // order (the next step cannot emit until the prior step's updates arrive),
+        // so the first-seen-ResponseId ordering preserves step boundaries.
+        const string step1Agent1 = "step1-agent1";
+        const string step2Agent1 = "step2-agent1";
+        const string step2Agent2 = "step2-agent2";
+        const string step3Agent2 = "step3-agent2";
+
+        MessageMerger merger = new();
+
+        // Step 1: Agent1 emits 2 messages.
+        AddSimpleUpdate(merger, step1Agent1, TestAgentId1, "S1-A1-m1");
+        AddSimpleUpdate(merger, step1Agent1, TestAgentId1, "S1-A1-m2");
+
+        // Step 2: Agent1 and Agent2 emit interleaved (A1, A2, A1, A2).
+        AddSimpleUpdate(merger, step2Agent1, TestAgentId1, "S2-A1-m1");
+        AddSimpleUpdate(merger, step2Agent2, TestAgentId2, "S2-A2-m1");
+        AddSimpleUpdate(merger, step2Agent1, TestAgentId1, "S2-A1-m2");
+        AddSimpleUpdate(merger, step2Agent2, TestAgentId2, "S2-A2-m2");
+
+        // Step 3: Agent2 emits 2 messages.
+        AddSimpleUpdate(merger, step3Agent2, TestAgentId2, "S3-A2-m1");
+        AddSimpleUpdate(merger, step3Agent2, TestAgentId2, "S3-A2-m2");
+
+        // Act
+        AgentResponse response = merger.ComputeMerged(step1Agent1);
+
+        // Assert: expected output order
+        //   Step 1 block (Agent1):  S1-A1-m1, S1-A1-m2
+        //   Step 2 Agent1 block:    S2-A1-m1, S2-A1-m2
+        //   Step 2 Agent2 block:    S2-A2-m1, S2-A2-m2
+        //   Step 3 block (Agent2):  S3-A2-m1, S3-A2-m2
+        response.Messages.Should().HaveCount(8);
+        var texts = response.Messages.Select(m => m.Text).ToList();
+        texts.Should().ContainInOrder(
+            "S1-A1-m1", "S1-A1-m2",
+            "S2-A1-m1", "S2-A1-m2",
+            "S2-A2-m1", "S2-A2-m2",
+            "S3-A2-m1", "S3-A2-m2");
+
+        // Step boundaries: no step-2 or step-3 message may appear before the last step-1 message.
+        int lastStep1Index = texts.FindLastIndex(t => t.StartsWith("S1-", StringComparison.Ordinal));
+        int firstStep2Index = texts.FindIndex(t => t.StartsWith("S2-", StringComparison.Ordinal));
+        int lastStep2Index = texts.FindLastIndex(t => t.StartsWith("S2-", StringComparison.Ordinal));
+        int firstStep3Index = texts.FindIndex(t => t.StartsWith("S3-", StringComparison.Ordinal));
+        lastStep1Index.Should().BeLessThan(firstStep2Index, "all step-1 messages precede step-2");
+        lastStep2Index.Should().BeLessThan(firstStep3Index, "all step-2 messages precede step-3");
+
+        // Within step 2 (multi-agent), per-agent blocks must be contiguous.
+        int firstS2A1 = texts.FindIndex(t => t.StartsWith("S2-A1", StringComparison.Ordinal));
+        int lastS2A1 = texts.FindLastIndex(t => t.StartsWith("S2-A1", StringComparison.Ordinal));
+        int firstS2A2 = texts.FindIndex(t => t.StartsWith("S2-A2", StringComparison.Ordinal));
+        int lastS2A2 = texts.FindLastIndex(t => t.StartsWith("S2-A2", StringComparison.Ordinal));
+        (lastS2A1 - firstS2A1).Should().Be(1, "Agent1 step-2 messages should be contiguous");
+        (lastS2A2 - firstS2A2).Should().Be(1, "Agent2 step-2 messages should be contiguous");
+        (lastS2A1 < firstS2A2 || lastS2A2 < firstS2A1).Should().BeTrue("agent blocks within a step must not interleave");
+
+        static void AddSimpleUpdate(MessageMerger m, string responseId, string agentId, string text)
+        {
+            m.AddUpdate(new AgentResponseUpdate
+            {
+                ResponseId = responseId,
+                MessageId = Guid.NewGuid().ToString("N"),
+                AgentId = agentId,
+                Role = ChatRole.Assistant,
+                Contents = [new TextContent(text)],
+            });
+        }
+    }
+
+    #endregion
 }

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]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     public async Task CreatesWorkflowEndToEndActivities_WithCorrectName_DefaultAsync()
     {
         await this.TestWorkflowEndToEndActivitiesAsync("Default");
     }
 
-    [Fact]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     public async Task CreatesWorkflowEndToEndActivities_WithCorrectName_OffThreadAsync()
     {
         await this.TestWorkflowEndToEndActivitiesAsync("OffThread");
     }
 
-    [Fact]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     public async Task CreatesWorkflowEndToEndActivities_WithCorrectName_ConcurrentAsync()
     {
         await this.TestWorkflowEndToEndActivitiesAsync("Concurrent");
     }
 
-    [Fact]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     public async Task CreatesWorkflowEndToEndActivities_WithCorrectName_LockstepAsync()
     {
         await this.TestWorkflowEndToEndActivitiesAsync("Lockstep");
     }
 
-    [Fact]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     public async Task CreatesWorkflowActivities_WithCorrectNameAsync()
     {
         // Arrange
@@ -182,7 +182,7 @@ public sealed class ObservabilityTests : IDisposable
         tags.Should().ContainKey(Tags.WorkflowDefinition);
     }
 
-    [Fact]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     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]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     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]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     public async Task DisableWorkflowBuild_PreventsWorkflowBuildActivityAsync()
     {
         // Arrange
@@ -255,7 +255,7 @@ public sealed class ObservabilityTests : IDisposable
             "WorkflowBuild activity should be disabled.");
     }
 
-    [Fact]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     public async Task DisableWorkflowRun_PreventsWorkflowRunActivityAsync()
     {
         // Arrange
@@ -285,7 +285,7 @@ public sealed class ObservabilityTests : IDisposable
             "Other activities should still be created.");
     }
 
-    [Fact]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     public async Task DisableExecutorProcess_PreventsExecutorProcessActivityAsync()
     {
         // Arrange
@@ -312,7 +312,7 @@ public sealed class ObservabilityTests : IDisposable
             "Other activities should still be created.");
     }
 
-    [Fact]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     public async Task DisableEdgeGroupProcess_PreventsEdgeGroupProcessActivityAsync()
     {
         // Arrange
@@ -333,7 +333,7 @@ public sealed class ObservabilityTests : IDisposable
             "Other activities should still be created.");
     }
 
-    [Fact]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     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]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     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]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     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]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     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]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     public async Task EnableSensitiveData_Disabled_DoesNotLogMessageContentAsync()
     {
         // Arrange

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

@@ -1,546 +0,0 @@
-// 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,7 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System;
-using System.Collections.Generic;
 using FluentAssertions;
 
 namespace Microsoft.Agents.AI.Workflows.UnitTests;
@@ -158,301 +157,4 @@ 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;
 }

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

@@ -67,7 +67,7 @@ public sealed class WorkflowRunActivityStopTests : IDisposable
     /// Bug: The Activity created by LockstepRunEventStream.TakeEventStreamAsync is never
     /// disposed because yield break in async iterators does not trigger using disposal.
     /// </summary>
-    [Fact]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     public async Task WorkflowRunActivity_IsStopped_LockstepAsync()
     {
         // Arrange
@@ -111,7 +111,7 @@ public sealed class WorkflowRunActivityStopTests : IDisposable
     /// Verifies that the workflow_invoke Activity is stopped when using the OffThread (Default)
     /// execution environment (StreamingRunEventStream).
     /// </summary>
-    [Fact]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     public async Task WorkflowRunActivity_IsStopped_OffThreadAsync()
     {
         // Arrange
@@ -156,7 +156,7 @@ public sealed class WorkflowRunActivityStopTests : IDisposable
     /// (StreamingRun.WatchStreamAsync) with the OffThread execution environment.
     /// This matches the exact usage pattern described in the issue.
     /// </summary>
-    [Fact]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     public async Task WorkflowRunActivity_IsStopped_Streaming_OffThreadAsync()
     {
         // Arrange
@@ -203,7 +203,7 @@ public sealed class WorkflowRunActivityStopTests : IDisposable
     /// streaming invocation, even when using the same workflow in a multi-turn pattern,
     /// and that each session gets its own session activity.
     /// </summary>
-    [Fact]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     public async Task WorkflowRunActivity_IsStopped_Streaming_OffThread_MultiTurnAsync()
     {
         // Arrange
@@ -264,7 +264,7 @@ public sealed class WorkflowRunActivityStopTests : IDisposable
     /// Verifies that all started activities (not just workflow_invoke) are properly stopped.
     /// This ensures no spans are "leaked" without being exported.
     /// </summary>
-    [Fact]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     public async Task AllActivities_AreStopped_AfterWorkflowCompletionAsync()
     {
         // Arrange
@@ -305,7 +305,7 @@ public sealed class WorkflowRunActivityStopTests : IDisposable
     /// be parented under the workflow session span. The run activity should
     /// still nest correctly under the session.
     /// </summary>
-    [Fact]
+    [Fact(Skip = "Flaky test - temporarily disabled.")]
     public async Task Lockstep_SessionActivity_DoesNotLeak_IntoCaller_ActivityCurrentAsync()
     {
         // Arrange

python/CHANGELOG.md

@@ -7,27 +7,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [1.4.0] - 2026-05-14
-
-### Added
-- **agent-framework-core**: Forward MCP tool call metadata ([#5815](https://github.com/microsoft/agent-framework/pull/5815))
-- **agent-framework-core**: Support `list[str]` arguments for file-based skill scripts ([#5850](https://github.com/microsoft/agent-framework/pull/5850))
-- **agent-framework-core**: Strip server-issued response item IDs under storage ([#5690](https://github.com/microsoft/agent-framework/pull/5690))
-- **agent-framework-ag-ui**: Add tool result display channel ([#5762](https://github.com/microsoft/agent-framework/pull/5762))
-- **agent-framework-ag-ui**: Promote to release candidate stage ([#5844](https://github.com/microsoft/agent-framework/pull/5844))
-- **agent-framework-devui**: Improvements for DevUI ([#5840](https://github.com/microsoft/agent-framework/pull/5840))
-
-### Changed
-- **agent-framework-core**: [BREAKING — experimental skills API] Align file skill folder discovery with agentskills.io spec ([#5807](https://github.com/microsoft/agent-framework/pull/5807))
-- **agent-framework-core**: [BREAKING — experimental skills API] Extract skill spec metadata into `SkillFrontmatter` ([#5775](https://github.com/microsoft/agent-framework/pull/5775))
-- **agent-framework-devui**: [BREAKING] Tighten default access controls and CORS posture ([#5740](https://github.com/microsoft/agent-framework/pull/5740))
-- **agent-framework-a2a**: [BREAKING] Migrate to a2a-sdk v1.0 ([#5752](https://github.com/microsoft/agent-framework/pull/5752))
-
-### Fixed
-- **agent-framework-a2a**: Fix A2A v1.0 non-streaming response and sample runtime issues ([#5849](https://github.com/microsoft/agent-framework/pull/5849))
-- **agent-framework-foundry-hosting**: Reject path-traversal context IDs in checkpoint storage ([#5851](https://github.com/microsoft/agent-framework/pull/5851))
-- **agent-framework-core**: Prevent MCP message_handler deadlock on notification reload ([#4866](https://github.com/microsoft/agent-framework/pull/4866))
-
 ## [1.3.0] - 2026-05-07
 
 ### Added
@@ -1071,9 +1050,7 @@ Release candidate for **agent-framework-core** and **agent-framework-azure-ai**
 
 For more information, see the [announcement blog post](https://devblogs.microsoft.com/foundry/introducing-microsoft-agent-framework-the-open-source-engine-for-agentic-ai-apps/).
 
-[Unreleased]: https://github.com/microsoft/agent-framework/compare/python-1.4.0...HEAD
-[1.4.0]: https://github.com/microsoft/agent-framework/compare/python-1.3.0...python-1.4.0
-[1.3.0]: https://github.com/microsoft/agent-framework/compare/python-1.2.2...python-1.3.0
+[Unreleased]: https://github.com/microsoft/agent-framework/compare/python-1.2.2...HEAD
 [1.2.2]: https://github.com/microsoft/agent-framework/compare/python-1.2.1...python-1.2.2
 [1.2.1]: https://github.com/microsoft/agent-framework/compare/python-1.2.0...python-1.2.1
 [1.2.0]: https://github.com/microsoft/agent-framework/compare/python-1.1.1...python-1.2.0

python/PACKAGE_STATUS.md

@@ -16,7 +16,7 @@ Status is grouped into these buckets:
 | --- | --- | --- |
 | `agent-framework` | `python/` | `released` |
 | `agent-framework-a2a` | `python/packages/a2a` | `beta` |
-| `agent-framework-ag-ui` | `python/packages/ag-ui` | `rc` |
+| `agent-framework-ag-ui` | `python/packages/ag-ui` | `beta` |
 | `agent-framework-anthropic` | `python/packages/anthropic` | `beta` |
 | `agent-framework-azure-contentunderstanding` | `python/packages/azure-contentunderstanding` | `alpha` |
 | `agent-framework-azure-ai-search` | `python/packages/azure-ai-search` | `beta` |

python/packages/a2a/AGENTS.md

@@ -42,7 +42,7 @@ request_handler = DefaultRequestHandler(
 app = Starlette(
     routes=[
         *create_agent_card_routes(my_agent_card),
-        *create_jsonrpc_routes(request_handler, "/"),
+        *create_jsonrpc_routes(request_handler),
     ]
 )
 ```

python/packages/a2a/agent_framework_a2a/_a2a_executor.py

@@ -78,7 +78,7 @@ class A2AExecutor(AgentExecutor):
             app = Starlette(
                 routes=[
                     *create_agent_card_routes(public_agent_card),
-                    *create_jsonrpc_routes(request_handler, "/"),
+                    *create_jsonrpc_routes(request_handler),
                 ],
             )
 

python/packages/a2a/agent_framework_a2a/_agent.py

@@ -365,10 +365,6 @@ class A2AAgent(AgentTelemetryLayer, BaseAgent):
 
         all_updates: list[AgentResponseUpdate] = []
         streamed_artifact_ids_by_task: dict[str, set[str]] = {}
-        # In non-streaming mode, accumulate intermediate status content so it
-        # can be surfaced when the terminal event arrives (mirroring v0.3.x
-        # behavior where the full Task history was available at completion).
-        pending_updates_by_task: dict[str, list[AgentResponseUpdate]] = {}
         async for item in a2a_stream:
             payload_type = item.WhichOneof("payload")
             if payload_type == "message":
@@ -395,55 +391,27 @@ class A2AAgent(AgentTelemetryLayer, BaseAgent):
                 )
                 if task.status.state in TERMINAL_TASK_STATES:
                     streamed_artifact_ids_by_task.pop(task.id, None)
-                    # If the terminal Task has no content, flush accumulated updates
-                    if not updates or all(not u.contents for u in updates):
-                        pending = pending_updates_by_task.pop(task.id, [])
-                        for update in pending:
-                            all_updates.append(update)
-                            yield update
-                    else:
-                        pending_updates_by_task.pop(task.id, None)
                 for update in updates:
                     all_updates.append(update)
                     yield update
             elif payload_type == "status_update":
                 status_event = item.status_update
                 updates = self._updates_from_task_update_event(status_event)
-                is_terminal = status_event.status.state in TERMINAL_TASK_STATES
                 if emit_intermediate:
                     for update in updates:
                         all_updates.append(update)
                         yield update
-                elif is_terminal:
-                    if updates:
-                        # Terminal event with content — discard accumulated intermediates
-                        pending_updates_by_task.pop(status_event.task_id, None)
-                        for update in updates:
-                            all_updates.append(update)
-                            yield update
-                    else:
-                        # Terminal event with NO content — flush accumulated updates
-                        pending = pending_updates_by_task.pop(status_event.task_id, [])
-                        for update in pending:
-                            all_updates.append(update)
-                            yield update
-                else:
-                    # Non-streaming intermediate: accumulate for later
-                    if updates:
-                        pending_updates_by_task.setdefault(status_event.task_id, []).extend(updates)
             elif payload_type == "artifact_update":
                 artifact_event = item.artifact_update
                 updates = self._updates_from_task_update_event(artifact_event)
-                # Always yield artifact updates — they carry actual response
-                # content (files, data).  Track IDs so that a subsequent
-                # terminal Task doesn't duplicate the same artifacts.
                 if updates:
                     streamed_artifact_ids_by_task.setdefault(artifact_event.task_id, set()).add(
                         artifact_event.artifact.artifact_id
                     )
-                for update in updates:
-                    all_updates.append(update)
-                    yield update
+                if emit_intermediate:
+                    for update in updates:
+                        all_updates.append(update)
+                        yield update
             else:
                 raise NotImplementedError(f"Unsupported StreamResponse payload: {payload_type}")
 

python/packages/a2a/pyproject.toml

@@ -4,7 +4,7 @@ description = "A2A integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260514"
+version = "1.0.0b260507"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.4.0,<2",
+    "agent-framework-core>=1.3.0,<2",
     "a2a-sdk>=1.0.0,<2",
 ]
 

python/packages/a2a/tests/test_a2a_agent.py

@@ -1570,102 +1570,4 @@ async def test_none_metadata_leaves_additional_properties_empty(
     assert not response.additional_properties
 
 
-async def test_non_streaming_terminal_status_update_surfaces_content(
-    a2a_agent: A2AAgent, mock_a2a_client: MockA2AClient
-) -> None:
-    """Non-streaming run() should surface content from terminal status_update events."""
-    completed_msg = A2AMessage(
-        message_id="msg-complete",
-        role=A2ARole.ROLE_AGENT,
-        parts=[Part(text="Done! Here is your answer.")],
-    )
-    status = TaskStatus(state=TaskState.TASK_STATE_COMPLETED, message=completed_msg)
-    event = TaskStatusUpdateEvent(task_id="task-ts", context_id="ctx-ts", status=status)
-    mock_a2a_client.responses.append(StreamResponse(status_update=event))
-
-    response = await a2a_agent.run("Hello")
-
-    assert len(response.messages) == 1
-    assert response.messages[0].text == "Done! Here is your answer."
-
-
-async def test_non_streaming_accumulates_working_content_for_empty_terminal(
-    a2a_agent: A2AAgent, mock_a2a_client: MockA2AClient
-) -> None:
-    """Non-streaming run() accumulates WORKING content and flushes on empty terminal event."""
-    # Intermediate WORKING event with content
-    working_msg = A2AMessage(
-        message_id="msg-working",
-        role=A2ARole.ROLE_AGENT,
-        parts=[Part(text="Here is your answer from working state.")],
-    )
-    working_status = TaskStatus(state=TaskState.TASK_STATE_WORKING, message=working_msg)
-    working_event = TaskStatusUpdateEvent(task_id="task-acc", context_id="ctx-acc", status=working_status)
-    mock_a2a_client.responses.append(StreamResponse(status_update=working_event))
-
-    # Terminal COMPLETED event with NO content
-    completed_status = TaskStatus(state=TaskState.TASK_STATE_COMPLETED)
-    completed_event = TaskStatusUpdateEvent(task_id="task-acc", context_id="ctx-acc", status=completed_status)
-    mock_a2a_client.responses.append(StreamResponse(status_update=completed_event))
-
-    response = await a2a_agent.run("Hello")
-
-    # The accumulated WORKING content is flushed when terminal arrives empty
-    assert len(response.messages) == 1
-    assert response.messages[0].text == "Here is your answer from working state."
-
-
-async def test_non_streaming_intermediate_discarded_when_terminal_has_content(
-    a2a_agent: A2AAgent, mock_a2a_client: MockA2AClient
-) -> None:
-    """Non-streaming: if terminal event has content, intermediate content is discarded."""
-    # Intermediate WORKING event
-    working_msg = A2AMessage(
-        message_id="msg-working",
-        role=A2ARole.ROLE_AGENT,
-        parts=[Part(text="Still thinking...")],
-    )
-    working_status = TaskStatus(state=TaskState.TASK_STATE_WORKING, message=working_msg)
-    working_event = TaskStatusUpdateEvent(task_id="task-wi", context_id="ctx-wi", status=working_status)
-    mock_a2a_client.responses.append(StreamResponse(status_update=working_event))
-
-    # Terminal COMPLETED event WITH content
-    completed_msg = A2AMessage(
-        message_id="msg-final",
-        role=A2ARole.ROLE_AGENT,
-        parts=[Part(text="Final answer")],
-    )
-    completed_status = TaskStatus(state=TaskState.TASK_STATE_COMPLETED, message=completed_msg)
-    completed_event = TaskStatusUpdateEvent(task_id="task-wi", context_id="ctx-wi", status=completed_status)
-    mock_a2a_client.responses.append(StreamResponse(status_update=completed_event))
-
-    response = await a2a_agent.run("Hello")
-
-    # Terminal content supersedes accumulated intermediates
-    assert len(response.messages) == 1
-    assert response.messages[0].text == "Final answer"
-
-
-async def test_non_streaming_artifact_update_surfaces_content(
-    a2a_agent: A2AAgent, mock_a2a_client: MockA2AClient
-) -> None:
-    """Non-streaming run() should surface content from artifact_update events."""
-    artifact = Artifact(
-        artifact_id="art-ns",
-        parts=[Part(text="Artifact content")],
-    )
-    event = TaskArtifactUpdateEvent(task_id="task-anu", context_id="ctx-anu", artifact=artifact, append=False)
-    mock_a2a_client.responses.append(StreamResponse(artifact_update=event))
-
-    # Terminal task with the same artifact ID — should be deduped
-    mock_a2a_client.add_task_response("task-anu", [{"id": "art-ns", "content": "Artifact content"}])
-
-    response = await a2a_agent.run("Hello")
-
-    # Artifact update + terminal task with same artifact ID = content emitted once from
-    # the artifact_update, then the duplicate from the task is filtered by streamed_artifact_ids
-    assert len(response.messages) == 1
-    assert response.messages[0].text == "Artifact content"
-
-
 # endregion

python/packages/ag-ui/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-framework-ag-ui"
-version = "1.0.0rc1"
+version = "1.0.0b260507"
 description = "AG-UI protocol integration for Agent Framework"
 readme = "README.md"
 license-files = ["LICENSE"]
@@ -22,7 +22,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.4.0,<2",
+    "agent-framework-core>=1.3.0,<2",
     "ag-ui-protocol>=0.1.16,<0.2",
     "fastapi>=0.115.0,<0.133.1",
     "uvicorn[standard]>=0.30.0,<0.42.0"

python/packages/anthropic/pyproject.toml

@@ -4,7 +4,7 @@ description = "Anthropic integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260514"
+version = "1.0.0b260507"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.4.0,<2",
+    "agent-framework-core>=1.3.0,<2",
     "anthropic>=0.80.0,<0.80.1",
 ]
 

python/packages/azure-ai-search/pyproject.toml

@@ -4,7 +4,7 @@ description = "Azure AI Search integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260514"
+version = "1.0.0b260507"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.4.0,<2",
+    "agent-framework-core>=1.3.0,<2",
     "azure-search-documents>=11.7.0b2,<11.7.0b3",
 ]
 

python/packages/azure-contentunderstanding/pyproject.toml

@@ -4,7 +4,7 @@ description = "Azure Content Understanding integration for Microsoft Agent Frame
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com" }]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0a260514"
+version = "1.0.0a260507"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,8 +23,8 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.4.0,<2",
-    "agent-framework-foundry>=1.4.0,<2",
+    "agent-framework-core>=1.3.0,<2",
+    "agent-framework-foundry>=1.3.0,<2",
     "azure-ai-contentunderstanding>=1.0.1,<1.1",
     "aiohttp>=3.9,<4",
     "filetype>=1.2,<2",

python/packages/azure-cosmos/pyproject.toml

@@ -4,7 +4,7 @@ description = "Azure Cosmos DB history provider integration for Microsoft Agent
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260514"
+version = "1.0.0b260507"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.4.0,<2",
+    "agent-framework-core>=1.3.0,<2",
     "azure-cosmos>=4.3.0,<5",
 ]
 

python/packages/azurefunctions/pyproject.toml

@@ -4,7 +4,7 @@ description = "Azure Functions integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260514"
+version = "1.0.0b260507"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -22,7 +22,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.4.0,<2",
+    "agent-framework-core>=1.3.0,<2",
     "agent-framework-durabletask",
     "azure-functions>=1.24.0,<2",
     "azure-functions-durable>=1.3.1,<2",

python/packages/bedrock/pyproject.toml

@@ -4,7 +4,7 @@ description = "Amazon Bedrock integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260514"
+version = "1.0.0b260507"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.4.0,<2",
+    "agent-framework-core>=1.3.0,<2",
     "boto3>=1.35.0,<2.0.0",
     "botocore>=1.35.0,<2.0.0",
 ]

python/packages/chatkit/agent_framework_chatkit/_converter.py

@@ -21,7 +21,6 @@ from chatkit.types import (
     HiddenContextItem,
     ImageAttachment,
     SDKHiddenContextItem,
-    StructuredInputItem,
     TaskItem,
     ThreadItem,
     UserMessageItem,
@@ -528,9 +527,6 @@ class ThreadItemConverter:
             case GeneratedImageItem():
                 # TODO(evmattso): Implement generated image handling in a future PR
                 return []
-            case StructuredInputItem():
-                # TODO(evmattso): Implement structured input handling in a future PR
-                return []
             case _:
                 assert_never(item)
 

python/packages/chatkit/pyproject.toml

@@ -4,7 +4,7 @@ description = "OpenAI ChatKit integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260514"
+version = "1.0.0b260507"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -22,7 +22,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.4.0,<2",
+    "agent-framework-core>=1.3.0,<2",
     "openai-chatkit>=1.4.1,<2.0.0",
 ]
 

python/packages/claude/pyproject.toml

@@ -4,7 +4,7 @@ description = "Claude Agent SDK integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260514"
+version = "1.0.0b260507"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.4.0,<2",
+    "agent-framework-core>=1.3.0,<2",
     "claude-agent-sdk>=0.1.36,<0.1.49",
 ]
 

python/packages/copilotstudio/pyproject.toml

@@ -4,7 +4,7 @@ description = "Copilot Studio integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260514"
+version = "1.0.0b260507"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.4.0,<2",
+    "agent-framework-core>=1.3.0,<2",
     "microsoft-agents-copilotstudio-client>=0.3.1,<0.3.2",
 ]
 

python/packages/core/agent_framework/_mcp.py

@@ -261,7 +261,6 @@ class MCPTool:
         self.request_timeout = request_timeout
         self.client = client
         self._functions: list[FunctionTool] = []
-        self._tool_call_meta_by_name: dict[str, dict[str, Any]] = {}
         self.is_connected: bool = False
         self._tools_loaded: bool = False
         self._prompts_loaded: bool = False
@@ -1027,7 +1026,6 @@ class MCPTool:
 
         # Track existing function names to prevent duplicates
         existing_names = {func.name for func in self._functions}
-        self._tool_call_meta_by_name.clear()
 
         params: types.PaginatedRequestParams | None = None
         while True:
@@ -1037,9 +1035,6 @@ class MCPTool:
             tool_list = await self.session.list_tools(params=params)  # type: ignore[union-attr]
 
             for tool in tool_list.tools:
-                if tool.meta is not None:
-                    self._tool_call_meta_by_name[tool.name] = dict(tool.meta)
-
                 normalized_name = _normalize_mcp_name(tool.name)
                 local_name = _build_prefixed_mcp_name(normalized_name, self.tool_name_prefix)
 
@@ -1190,15 +1185,14 @@ class MCPTool:
             }
         }
 
-        # Some MCP proxies require their tools/list metadata to be echoed on tools/call.
-        tool_meta = self._tool_call_meta_by_name.get(tool_name)
-        meta = _inject_otel_into_mcp_meta(dict(tool_meta) if tool_meta is not None else None)
+        # Inject OpenTelemetry trace context into MCP _meta for distributed tracing.
+        otel_meta = _inject_otel_into_mcp_meta()
 
         parser = self.parse_tool_results or self._parse_tool_result_from_mcp
         # Try the operation, reconnecting once if the connection is closed
         for attempt in range(2):
             try:
-                result = await self.session.call_tool(tool_name, arguments=filtered_kwargs, meta=meta)  # type: ignore
+                result = await self.session.call_tool(tool_name, arguments=filtered_kwargs, meta=otel_meta)  # type: ignore
                 if result.isError:
                     parsed = parser(result)
                     text = (

python/packages/core/agent_framework/_skills.py

@@ -289,15 +289,13 @@ class SkillScript(ABC):
         return None
 
     @abstractmethod
-    async def run(self, skill: Skill, args: dict[str, Any] | list[str] | None = None, **kwargs: Any) -> Any:
+    async def run(self, skill: Skill, args: dict[str, Any] | None = None, **kwargs: Any) -> Any:
         """Run this script.
 
         Args:
             skill: The skill that owns this script.
-            args: Optional arguments for the script, provided by the
-                agent/LLM.  May be a ``dict`` (named keyword arguments
-                for inline scripts) or a ``list[str]`` (positional CLI
-                arguments for file-based scripts).
+            args: Optional keyword arguments for the script, provided by the
+                agent/LLM.
             **kwargs: Runtime keyword arguments forwarded only to script
                 functions that accept ``**kwargs``.
 
@@ -363,31 +361,19 @@ class InlineSkillScript(SkillScript):
             self._parameters_schema_resolved = True
         return self._parameters_schema
 
-    async def run(self, skill: Skill, args: dict[str, Any] | list[str] | None = None, **kwargs: Any) -> Any:
+    async def run(self, skill: Skill, args: dict[str, Any] | None = None, **kwargs: Any) -> Any:
         """Run the script by invoking the callable in-process.
 
         Args:
             skill: The skill that owns this script.
             args: Optional keyword arguments for the script, provided by the
-                agent/LLM.  Must be a ``dict`` or ``None``; passing a
-                ``list`` raises :class:`TypeError` because inline scripts
-                bind arguments by keyword name.
+                agent/LLM.
             **kwargs: Runtime keyword arguments forwarded only to script
                 functions that accept ``**kwargs``.
 
         Returns:
             The script execution result.
-
-        Raises:
-            TypeError: If ``args`` is a ``list`` (array-style arguments
-                are only supported for file-based scripts).
         """
-        if isinstance(args, list):
-            raise TypeError(
-                f"Inline script '{self.name}' requires keyword arguments (dict), "
-                f"but received a list. Array-style arguments are only supported "
-                f"for file-based scripts."
-            )
         if self._accepts_kwargs:  # noqa: SIM108
             result = self.function(**(args or {}), **kwargs)
         else:
@@ -445,23 +431,13 @@ class FileSkillScript(SkillScript):
         self.full_path = full_path
         self._runner = runner
 
-    @property
-    def parameters_schema(self) -> dict[str, Any] | None:
-        """JSON Schema advertising that file scripts accept a string array.
-
-        Returns a fixed schema ``{"type": "array", "items": {"type": "string"}}``
-        so that the LLM knows to pass positional CLI arguments as a JSON array
-        of strings.
-        """
-        return {"type": "array", "items": {"type": "string"}}
-
-    async def run(self, skill: Skill, args: dict[str, Any] | list[str] | None = None, **kwargs: Any) -> Any:
+    async def run(self, skill: Skill, args: dict[str, Any] | None = None, **kwargs: Any) -> Any:
         """Run the script by delegating to the configured runner.
 
         Args:
             skill: The skill that owns this script.  Must be a
                 :class:`FileSkill`.
-            args: Optional arguments for the script.
+            args: Optional keyword arguments for the script.
             **kwargs: Additional runtime keyword arguments (unused).
 
         Returns:
@@ -1372,7 +1348,6 @@ class FileSkill(Skill):
         self.path = path
         self._resources: list[SkillResource] = list(resources) if resources is not None else []
         self._scripts: list[SkillScript] = list(scripts) if scripts is not None else []
-        self._cached_content: str | None = None
 
     @property
     def frontmatter(self) -> SkillFrontmatter:
@@ -1381,23 +1356,8 @@ class FileSkill(Skill):
 
     @property
     def content(self) -> str:
-        """The skill content with appended scripts block.
-
-        When scripts are present, a ``<scripts>`` XML block is appended
-        to the raw SKILL.md content so that the LLM can discover each
-        script's ``<parameters_schema>``.
-
-        The result is cached after the first access.  Adding scripts
-        after the first access will not be reflected.
-        """
-        if self._cached_content is not None:
-            return self._cached_content
-        if not self._scripts:
-            self._cached_content = self._content
-        else:
-            script_lines = "\n".join(_create_script_element(s) for s in self._scripts)
-            self._cached_content = f"{self._content}\n\n<scripts>\n{script_lines}\n</scripts>"
-        return self._cached_content
+        """The skill content provided at construction time."""
+        return self._content
 
     @property
     def resources(self) -> list[SkillResource]:
@@ -1432,9 +1392,7 @@ class SkillScriptRunner(Protocol):
     satisfies this protocol.
     """
 
-    def __call__(
-        self, skill: FileSkill, script: FileSkillScript, args: dict[str, Any] | list[str] | None = None
-    ) -> Any:
+    def __call__(self, skill: FileSkill, script: FileSkillScript, args: dict[str, Any] | None = None) -> Any:
         """Run a skill script.
 
         The :class:`SkillsProvider` resolves skill and script names
@@ -1444,7 +1402,7 @@ class SkillScriptRunner(Protocol):
         Args:
             skill: The file-based skill that owns the script.
             script: The file-based script to run.
-            args: Optional arguments for the script.
+            args: Optional keyword arguments for the script.
 
         Returns:
             The result. May be any type; the framework
@@ -1472,13 +1430,6 @@ DEFAULT_RESOURCE_EXTENSIONS: Final[tuple[str, ...]] = (
 )
 DEFAULT_SCRIPT_EXTENSIONS: Final[tuple[str, ...]] = (".py",)
 
-# "." means the skill directory root itself (files directly in the skill folder).
-ROOT_DIRECTORY_INDICATOR: Final[str] = "."
-
-# Standard subdirectory names per https://agentskills.io/specification#directory-structure
-DEFAULT_RESOURCE_DIRECTORIES: Final[tuple[str, ...]] = ("references", "assets")
-DEFAULT_SCRIPT_DIRECTORIES: Final[tuple[str, ...]] = ("scripts",)
-
 # region Patterns and prompt template
 
 # Matches YAML frontmatter delimited by "---" lines.
@@ -1699,8 +1650,6 @@ class SkillsProvider(ContextProvider):
         script_runner: SkillScriptRunner | None = None,
         resource_extensions: tuple[str, ...] | None = None,
         script_extensions: tuple[str, ...] | None = None,
-        resource_directories: Sequence[str] | None = None,
-        script_directories: Sequence[str] | None = None,
         instruction_template: str | None = None,
         require_script_approval: bool = False,
         disable_caching: bool = False,
@@ -1723,15 +1672,6 @@ class SkillsProvider(ContextProvider):
                 ``(".md", ".json", ".yaml", ".yml", ".csv", ".xml", ".txt")``.
             script_extensions: File extensions recognized as discoverable
                 scripts.  Defaults to ``(".py",)``.
-            resource_directories: Relative directory paths to scan for
-                resource files within each skill directory.  Use ``"."``
-                to include files at the skill root level.  Defaults to
-                ``("references", "assets")`` per the agentskills.io
-                specification.
-            script_directories: Relative directory paths to scan for
-                script files within each skill directory.  Use ``"."``
-                to include files at the skill root level.  Defaults to
-                ``("scripts",)`` per the agentskills.io specification.
             instruction_template: Custom system-prompt template for
                 advertising skills.  Must contain a ``{skills}`` placeholder.
                 Uses a built-in template when ``None``.
@@ -1761,8 +1701,6 @@ class SkillsProvider(ContextProvider):
                 script_runner=script_runner,
                 resource_extensions=resource_extensions,
                 script_extensions=script_extensions,
-                resource_directories=resource_directories,
-                script_directories=script_directories,
             )
         )
         return cls(
@@ -2024,7 +1962,7 @@ class SkillsProvider(ContextProvider):
         if include_script_runner_tool:
 
             async def _run_script(
-                skill_name: str, script_name: str, args: dict[str, Any] | list[str] | None = None, **kwargs: Any
+                skill_name: str, script_name: str, args: dict[str, Any] | None = None, **kwargs: Any
             ) -> Any:
                 return await self._run_skill_script(skills, skill_name, script_name, args, **kwargs)
 
@@ -2047,31 +1985,12 @@ class SkillsProvider(ContextProvider):
                                 ),
                             },
                             "args": {
-                                "oneOf": [
-                                    {
-                                        "type": "object",
-                                        "additionalProperties": True,
-                                        "description": (
-                                            "Named arguments as key-value pairs "
-                                            '(e.g. {"length": 24, "uppercase": true}).'
-                                        ),
-                                    },
-                                    {
-                                        "type": "array",
-                                        "items": {"type": "string"},
-                                        "description": (
-                                            "Positional CLI arguments as a string array "
-                                            '(e.g. ["input.docx", "--output", "result.idx"]).'
-                                        ),
-                                    },
-                                    {"type": "null"},
-                                ],
+                                "type": ["object", "null"],
+                                "additionalProperties": True,
                                 "default": None,
                                 "description": (
-                                    "Arguments to pass to the script. "
-                                    "Use an array of strings for CLI-style positional arguments "
-                                    '(e.g. ["input.docx", "--output", "result.idx"]), '
-                                    "or an object for named parameters "
+                                    "Arguments to pass to the script as key-value pairs. "
+                                    "Use parameter names as keys without leading dashes "
                                     '(e.g. {"length": 24, "uppercase": true}). '
                                     "How these values are mapped to the underlying script "
                                     "is determined by the script implementation or configured runner."
@@ -2121,7 +2040,7 @@ class SkillsProvider(ContextProvider):
         skills: Sequence[Skill],
         skill_name: str,
         script_name: str,
-        args: dict[str, Any] | list[str] | None = None,
+        args: dict[str, Any] | None = None,
         **kwargs: Any,
     ) -> Any:
         """Run a named script from a skill.
@@ -2133,8 +2052,9 @@ class SkillsProvider(ContextProvider):
             skills: The skills to look up the skill from.
             skill_name: The name of the owning skill.
             script_name: The script name to look up (case-insensitive).
-            args: Optional arguments for the script, provided by the
-                agent/LLM.
+            args: Optional keyword arguments for the script, provided by the
+                agent/LLM.  These are mapped to the function's declared
+                parameters.
             **kwargs: Runtime keyword arguments forwarded only to script
                 functions that accept ``**kwargs`` (e.g. arguments passed via
                 ``agent.run(user_id="123")``).
@@ -2266,15 +2186,7 @@ class FileSkillsSource(SkillsSource):
 
     Recursively scans the configured *skill_paths* directories for
     ``SKILL.md`` files (up to 2 levels deep), parses their YAML frontmatter,
-    and discovers associated resource and script files from spec-defined
-    subdirectories.
-
-    By default, resources are discovered from ``references/`` and ``assets/``
-    subdirectories, and scripts from ``scripts/``, per the
-    `agentskills.io specification
-    <https://agentskills.io/specification>`_.  Use *resource_directories*
-    and *script_directories* to customize which subdirectories are scanned.
-    Pass ``"."`` to include files at the skill root level.
+    and discovers associated resource and script files from subdirectories.
 
     Security: file-based metadata is XML-escaped before prompt injection,
     and resource reads are guarded against path traversal and symlink escape.
@@ -2288,15 +2200,14 @@ class FileSkillsSource(SkillsSource):
             source = FileSkillsSource(skill_paths="./skills")
             skills = await source.get_skills()
 
-        With a script runner and custom directories:
+        With a script runner and custom extensions:
 
         .. code-block:: python
 
             source = FileSkillsSource(
                 skill_paths=["./skills", "./more-skills"],
                 script_runner=my_runner,
-                resource_directories=[".", "references", "assets"],
-                script_directories=["scripts"],
+                script_extensions=(".py", ".sh"),
             )
     """
 
@@ -2307,14 +2218,12 @@ class FileSkillsSource(SkillsSource):
         script_runner: SkillScriptRunner | None = None,
         resource_extensions: tuple[str, ...] | None = None,
         script_extensions: tuple[str, ...] | None = None,
-        resource_directories: Sequence[str] | None = None,
-        script_directories: Sequence[str] | None = None,
     ) -> None:
         """Initialize a FileSkillsSource.
 
         Args:
             skill_paths: One or more directory paths to search for file-based
-                skills.  Each path may point to an individual skill directory
+                skills.  Each path may point to an individual skill folder
                 (containing ``SKILL.md``) or to a parent that contains skill
                 subdirectories.
 
@@ -2328,18 +2237,6 @@ class FileSkillsSource(SkillsSource):
                 ``(".md", ".json", ".yaml", ".yml", ".csv", ".xml", ".txt")``.
             script_extensions: File extensions recognized as discoverable
                 scripts.  Defaults to ``(".py",)``.
-            resource_directories: Relative directory paths to scan for
-                resource files within each skill directory.  Use ``"."``
-                to include files at the skill root level.  Defaults to
-                ``("references", "assets")`` per the
-                `agentskills.io specification
-                <https://agentskills.io/specification>`_.
-            script_directories: Relative directory paths to scan for
-                script files within each skill directory.  Use ``"."``
-                to include files at the skill root level.  Defaults to
-                ``("scripts",)`` per the
-                `agentskills.io specification
-                <https://agentskills.io/specification>`_.
         """
         if isinstance(skill_paths, (str, Path)):
             self._skill_paths: list[str] = [str(skill_paths)]
@@ -2350,17 +2247,6 @@ class FileSkillsSource(SkillsSource):
         self._resource_extensions = resource_extensions or DEFAULT_RESOURCE_EXTENSIONS
         self._script_extensions = script_extensions or DEFAULT_SCRIPT_EXTENSIONS
 
-        self._resource_directories: tuple[str, ...] = (
-            tuple(FileSkillsSource._validate_and_normalize_directory_names(resource_directories))
-            if resource_directories is not None
-            else DEFAULT_RESOURCE_DIRECTORIES
-        )
-        self._script_directories: tuple[str, ...] = (
-            tuple(FileSkillsSource._validate_and_normalize_directory_names(script_directories))
-            if script_directories is not None
-            else DEFAULT_SCRIPT_DIRECTORIES
-        )
-
     async def get_skills(self) -> list[Skill]:
         """Discover and return all file-based skills from configured paths.
 
@@ -2398,16 +2284,12 @@ class FileSkillsSource(SkillsSource):
             )
 
             # Discover and attach file-based resources
-            for rn in FileSkillsSource._discover_resource_files(
-                skill_path, self._resource_extensions, self._resource_directories
-            ):
+            for rn in FileSkillsSource._discover_resource_files(skill_path, self._resource_extensions):
                 resource_full_path = FileSkillsSource._get_validated_resource_path(skill_path, rn)
                 file_skill.resources.append(_FileSkillResource(name=rn, full_path=resource_full_path))
 
             # Discover and attach file-based scripts as SkillScript instances
-            for sn in FileSkillsSource._discover_script_files(
-                skill_path, self._script_extensions, self._script_directories
-            ):
+            for sn in FileSkillsSource._discover_script_files(skill_path, self._script_extensions):
                 script_full_path = os.path.normpath(os.path.join(skill_path, sn))  # noqa: ASYNC240
                 file_skill.scripts.append(
                     FileSkillScript(name=sn, full_path=script_full_path, runner=self._script_runner)
@@ -2487,274 +2369,116 @@ class FileSkillsSource(SkillsSource):
                 return True
         return False
 
-    @staticmethod
-    def _validate_and_normalize_directory_names(
-        directories: Sequence[str],
-    ) -> list[str]:
-        """Validate and normalize relative directory names.
-
-        Ensures each entry is a safe relative path.  The ``"."`` root indicator
-        is passed through unchanged.  Entries containing ``..`` segments or
-        representing absolute paths are rejected with a warning and skipped.
-        Empty or whitespace-only entries raise :class:`ValueError`.
-
-        Args:
-            directories: Sequence of relative directory names to validate.
-
-        Returns:
-            A list of validated, normalized directory names.
-
-        Raises:
-            ValueError: If any entry is empty or whitespace-only.
-        """
-        result: list[str] = []
-        for directory in directories:
-            if not directory or not directory.strip():
-                raise ValueError("Directory names must not be empty or whitespace.")
-
-            # Normalize separators: backslash → forward slash, strip leading ./ and trailing /
-            normalized = PurePosixPath(directory.replace("\\", "/")).as_posix()
-
-            # "." and "./" both normalize to "." — treat as root indicator
-            if normalized == ROOT_DIRECTORY_INDICATOR:
-                result.append(ROOT_DIRECTORY_INDICATOR)
-                continue
-
-            # Reject absolute paths (check both POSIX and Windows-style roots
-            # so validation is consistent regardless of the host OS)
-            if (
-                os.path.isabs(directory)
-                or normalized.startswith("/")
-                or re.match(r"^[A-Za-z]:[/\\]", directory)
-            ):
-                logger.warning(
-                    "Skipping directory '%s': absolute paths are not allowed.",
-                    directory,
-                )
-                continue
-
-            # Reject paths containing ".." segments
-            if any(segment == ".." for segment in normalized.split("/")):
-                logger.warning(
-                    "Skipping directory '%s': parent traversal ('..') is not allowed.",
-                    directory,
-                )
-                continue
-
-            result.append(normalized)
-        return result
-
     @staticmethod
     def _discover_resource_files(
         skill_dir_path: str,
         extensions: tuple[str, ...] = DEFAULT_RESOURCE_EXTENSIONS,
-        directories: tuple[str, ...] = DEFAULT_RESOURCE_DIRECTORIES,
     ) -> list[str]:
-        """Scan configured subdirectories for resource files matching *extensions*.
+        """Scan a skill directory for resource files matching *extensions*.
 
-        Scans each directory in *directories* within *skill_dir_path* for files
-        whose extension is in *extensions*, excluding ``SKILL.md`` itself.
-        Use ``"."`` in *directories* to include files at the skill root level.
-        Each candidate is validated against path-traversal and symlink-escape
-        checks; unsafe files are skipped with a warning.
+        Recursively walks *skill_dir_path* and collects files whose extension
+        is in *extensions*, excluding ``SKILL.md`` itself.  Each candidate is
+        validated against path-traversal and symlink-escape checks; unsafe
+        files are skipped with a warning.
 
         Args:
             skill_dir_path: Absolute path to the skill directory to scan.
             extensions: Tuple of allowed file extensions (e.g. ``(".md", ".json")``).
-            directories: Relative subdirectory paths to scan for resources.
 
         Returns:
-            Sorted relative resource paths (forward-slash-separated) for every
+            Relative resource paths (forward-slash-separated) for every
             discovered file that passes security checks.
         """
         skill_dir = Path(skill_dir_path).absolute()
         root_directory_path = str(skill_dir)
         resources: list[str] = []
         normalized_extensions = {e.lower() for e in extensions}
-        seen_directories: set[str] = set()
 
-        for directory in directories:
-            is_root = directory == ROOT_DIRECTORY_INDICATOR
-            target_dir = skill_dir if is_root else (skill_dir / directory)
-
-            # Deduplicate after resolving to avoid scanning the same directory twice.
-            # Use normcase for case-insensitive dedup on case-insensitive filesystems.
-            resolved_target = str(Path(os.path.normpath(target_dir)).absolute())
-            dedup_key = os.path.normcase(resolved_target)
-            if dedup_key in seen_directories:
-                continue
-            seen_directories.add(dedup_key)
-
-            if not target_dir.is_dir():
+        for resource_file in skill_dir.rglob("*"):
+            if not resource_file.is_file():
                 continue
 
-            # Directory-level containment and symlink checks for non-root directories
-            if not is_root:
-                if not FileSkillsSource._is_path_within_directory(resolved_target, root_directory_path):
-                    logger.warning(
-                        "Skipping resource directory '%s': resolves outside skill directory '%s'",
-                        directory,
-                        skill_dir_path,
-                    )
-                    continue
+            if resource_file.name.upper() == SKILL_FILE_NAME.upper():
+                continue
 
-                if FileSkillsSource._has_symlink_in_path(resolved_target, root_directory_path):
-                    logger.warning(
-                        "Skipping resource directory '%s': symlink detected in path under skill directory '%s'",
-                        directory,
-                        skill_dir_path,
-                    )
-                    continue
+            if resource_file.suffix.lower() not in normalized_extensions:
+                continue
 
-            # Scan top-level files only (non-recursive) within this directory
-            try:
-                entries = list(target_dir.iterdir())
-            except OSError:
+            resource_full_path = str(Path(os.path.normpath(resource_file)).absolute())
+
+            if not FileSkillsSource._is_path_within_directory(resource_full_path, root_directory_path):
                 logger.warning(
-                    "Failed to list resource directory '%s' in skill directory '%s'; skipping.",
-                    directory,
+                    "Skipping resource '%s': resolves outside skill directory '%s'",
+                    resource_file,
                     skill_dir_path,
                 )
                 continue
 
-            for resource_file in entries:
-                if not resource_file.is_file():
-                    continue
+            if FileSkillsSource._has_symlink_in_path(resource_full_path, root_directory_path):
+                logger.warning(
+                    "Skipping resource '%s': symlink detected in path under skill directory '%s'",
+                    resource_file,
+                    skill_dir_path,
+                )
+                continue
 
-                if resource_file.name.upper() == SKILL_FILE_NAME.upper():
-                    continue
+            rel_path = resource_file.relative_to(skill_dir)
+            resources.append(FileSkillsSource._normalize_resource_path(str(rel_path)))
 
-                if resource_file.suffix.lower() not in normalized_extensions:
-                    continue
-
-                resource_full_path = str(Path(os.path.normpath(resource_file)).absolute())
-
-                # Containment check: file must resolve within the target directory
-                if not FileSkillsSource._is_path_within_directory(resource_full_path, resolved_target):
-                    logger.warning(
-                        "Skipping resource '%s': resolves outside target directory '%s'",
-                        resource_file,
-                        directory,
-                    )
-                    continue
-
-                if FileSkillsSource._has_symlink_in_path(resource_full_path, root_directory_path):
-                    logger.warning(
-                        "Skipping resource '%s': symlink detected in path under skill directory '%s'",
-                        resource_file,
-                        skill_dir_path,
-                    )
-                    continue
-
-                rel_path = resource_file.relative_to(skill_dir)
-                resources.append(FileSkillsSource._normalize_resource_path(str(rel_path)))
-
-        resources.sort()
         return resources
 
     @staticmethod
     def _discover_script_files(
         skill_dir_path: str,
         extensions: tuple[str, ...] = DEFAULT_SCRIPT_EXTENSIONS,
-        directories: tuple[str, ...] = DEFAULT_SCRIPT_DIRECTORIES,
     ) -> list[str]:
-        """Scan configured subdirectories for script files matching *extensions*.
+        """Scan a skill directory for script files matching *extensions*.
 
-        Scans each directory in *directories* within *skill_dir_path* for files
-        whose extension is in *extensions*.  Use ``"."`` in *directories* to
-        include files at the skill root level.  Each candidate is validated
-        against path-traversal and symlink-escape checks; unsafe files are
-        skipped with a warning.
+        Recursively walks *skill_dir_path* and collects files whose extension
+        is in *extensions*.  Each candidate is validated against path-traversal
+        and symlink-escape checks; unsafe files are skipped with a warning.
 
         Args:
             skill_dir_path: Absolute path to the skill directory to scan.
             extensions: Tuple of allowed script extensions (e.g. ``(".py",)``).
-            directories: Relative subdirectory paths to scan for scripts.
 
         Returns:
-            Sorted relative script paths (forward-slash-separated) for every
+            Relative script paths (forward-slash-separated) for every
             discovered file that passes security checks.
         """
         skill_dir = Path(skill_dir_path).absolute()
         root_directory_path = str(skill_dir)
         scripts: list[str] = []
         normalized_extensions = {e.lower() for e in extensions}
-        seen_directories: set[str] = set()
 
-        for directory in directories:
-            is_root = directory == ROOT_DIRECTORY_INDICATOR
-            target_dir = skill_dir if is_root else (skill_dir / directory)
-
-            # Deduplicate after resolving to avoid scanning the same directory twice.
-            # Use normcase for case-insensitive dedup on case-insensitive filesystems.
-            resolved_target = str(Path(os.path.normpath(target_dir)).absolute())
-            dedup_key = os.path.normcase(resolved_target)
-            if dedup_key in seen_directories:
-                continue
-            seen_directories.add(dedup_key)
-
-            if not target_dir.is_dir():
+        for script_file in skill_dir.rglob("*"):
+            if not script_file.is_file():
                 continue
 
-            # Directory-level containment and symlink checks for non-root directories
-            if not is_root:
-                if not FileSkillsSource._is_path_within_directory(resolved_target, root_directory_path):
-                    logger.warning(
-                        "Skipping script directory '%s': resolves outside skill directory '%s'",
-                        directory,
-                        skill_dir_path,
-                    )
-                    continue
+            if script_file.suffix.lower() not in normalized_extensions:
+                continue
 
-                if FileSkillsSource._has_symlink_in_path(resolved_target, root_directory_path):
-                    logger.warning(
-                        "Skipping script directory '%s': symlink detected in path under skill directory '%s'",
-                        directory,
-                        skill_dir_path,
-                    )
-                    continue
+            script_full_path = str(Path(os.path.normpath(script_file)).absolute())
 
-            # Scan top-level files only (non-recursive) within this directory
-            try:
-                entries = list(target_dir.iterdir())
-            except OSError:
+            if not FileSkillsSource._is_path_within_directory(script_full_path, root_directory_path):
                 logger.warning(
-                    "Failed to list script directory '%s' in skill directory '%s'; skipping.",
-                    directory,
+                    "Skipping script '%s': resolves outside skill directory '%s'",
+                    script_file,
                     skill_dir_path,
                 )
                 continue
 
-            for script_file in entries:
-                if not script_file.is_file():
-                    continue
+            if FileSkillsSource._has_symlink_in_path(script_full_path, root_directory_path):
+                logger.warning(
+                    "Skipping script '%s': symlink detected in path under skill directory '%s'",
+                    script_file,
+                    skill_dir_path,
+                )
+                continue
 
-                if script_file.suffix.lower() not in normalized_extensions:
-                    continue
+            rel_path = script_file.relative_to(skill_dir)
+            scripts.append(FileSkillsSource._normalize_resource_path(str(rel_path)))
 
-                script_full_path = str(Path(os.path.normpath(script_file)).absolute())
-
-                # Containment check: file must resolve within the target directory
-                if not FileSkillsSource._is_path_within_directory(script_full_path, resolved_target):
-                    logger.warning(
-                        "Skipping script '%s': resolves outside target directory '%s'",
-                        script_file,
-                        directory,
-                    )
-                    continue
-
-                if FileSkillsSource._has_symlink_in_path(script_full_path, root_directory_path):
-                    logger.warning(
-                        "Skipping script '%s': symlink detected in path under skill directory '%s'",
-                        script_file,
-                        skill_dir_path,
-                    )
-                    continue
-
-                rel_path = script_file.relative_to(skill_dir)
-                scripts.append(FileSkillsSource._normalize_resource_path(str(rel_path)))
-
-        scripts.sort()
         return scripts
 
     @staticmethod

python/packages/core/pyproject.toml

@@ -4,7 +4,7 @@ description = "Microsoft Agent Framework for building AI Agents with Python. Thi
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.4.0"
+version = "1.3.0"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"

python/packages/core/tests/core/test_mcp.py

@@ -4194,57 +4194,6 @@ async def test_mcp_tool_call_tool_otel_meta(use_span, expect_traceparent, span_e
             assert meta is None
 
 
-async def test_mcp_tool_call_tool_forwards_tool_list_meta():
-    """call_tool echoes per-tool metadata returned by tools/list."""
-    from opentelemetry import trace
-
-    tool_meta = {
-        "tool_configuration": {
-            "name": "WorkIQSharePoint.readSmallBinaryFile",
-            "type": "foundry_toolbox",
-        }
-    }
-
-    class TestServer(MCPTool):
-        async def connect(self):
-            self.session = Mock(spec=ClientSession)
-            self.session.list_tools = AsyncMock(
-                return_value=types.ListToolsResult(
-                    tools=[
-                        types.Tool(
-                            name="WorkIQSharePoint.readSmallBinaryFile",
-                            description="Read a binary file",
-                            inputSchema={
-                                "type": "object",
-                                "properties": {"fileId": {"type": "string"}},
-                                "required": ["fileId"],
-                            },
-                            _meta=tool_meta,
-                        )
-                    ]
-                )
-            )
-            self.session.call_tool = AsyncMock(
-                return_value=types.CallToolResult(content=[types.TextContent(type="text", text="result")])
-            )
-            self.session.list_prompts = AsyncMock(
-                return_value=types.ListPromptsResult(prompts=[])
-            )
-
-        def get_mcp_client(self) -> _AsyncGeneratorContextManager[Any, None]:
-            return None
-
-    server = TestServer(name="test_server")
-    async with server:
-        await server.load_tools()
-        await server.load_prompts()
-
-        with trace.use_span(trace.NonRecordingSpan(trace.INVALID_SPAN_CONTEXT)):
-            await server.call_tool("WorkIQSharePoint.readSmallBinaryFile", fileId="file-1")
-
-        assert server.session.call_tool.call_args.kwargs["meta"] == tool_meta
-
-
 async def test_mcp_streamable_http_tool_hook_not_duplicated_on_repeated_get_mcp_client():
     """Test that calling get_mcp_client multiple times does not accumulate duplicate hooks."""
     tool = MCPStreamableHTTPTool(

python/packages/core/tests/workflow/test_full_conversation.py

@@ -429,12 +429,7 @@ class _FullHistoryReplayCoordinator(Executor):
 
 
 @pytest.mark.xfail(
-    reason=(
-        "Tracks the executor-layer half of #3295: AgentExecutor should clear service_session_id "
-        "when handed a full prior conversation. The wire-level 'Duplicate item' API error is "
-        "already closed by the chat-client strip in #3295; this xfail covers the defense-in-depth "
-        "follow-up that makes the executor wiring reflect intent."
-    ),
+    reason="reset_service_session support not yet implemented — see #4047",
     strict=True,
 )
 async def test_run_request_with_full_history_clears_service_session_id() -> None:

python/packages/declarative/pyproject.toml

@@ -4,7 +4,7 @@ description = "Declarative specification support for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260514"
+version = "1.0.0b260507"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -22,7 +22,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.4.0,<2",
+    "agent-framework-core>=1.3.0,<2",
     "httpx>=0.27,<1",
     "powerfx>=0.0.32,<0.0.35; python_version < '3.14'",
     "pyyaml>=6.0,<7.0",

python/packages/devui/AGENTS.md

@@ -34,12 +34,6 @@ devui ./agents
 devui --entities my_agent.py
 ```
 
-## Security Posture
-
-DevUI is a development-only sample app, not a production hosting surface. Authentication is enabled by default.
-Unauthenticated mode is allowed only on `localhost` / `127.0.0.1`; `0.0.0.0`, LAN IPs, and hostnames require
-`DEVUI_AUTH_TOKEN` or `--auth-token`.
-
 ## Import Path
 
 ```python

python/packages/devui/README.md

@@ -47,9 +47,6 @@ devui ./agents --port 8080
 # → API: http://localhost:8080/v1/*
 ```
 
-DevUI is auth-enabled by default. Localhost starts with a generated development token logged at startup; pass it as
-`Authorization: Bearer <token>` for direct API calls.
-
 When DevUI starts with no discovered entities, it displays a **sample entity gallery** with curated examples from the Agent Framework repository. You can download these samples, review them, and run them locally to get started quickly.
 
 ## Using MCP Tools
@@ -140,14 +137,12 @@ For convenience, DevUI provides an OpenAI Responses backend API. This means you
 ```bash
 # Simple - use your entity name as the entity_id in metadata
 curl -X POST http://localhost:8080/v1/responses \
-  -H "Authorization: Bearer <devui-token>" \
   -H "Content-Type: application/json" \
   -d @- << 'EOF'
 {
   "metadata": {"entity_id": "weather_agent"},
   "input": "Hello world"
 }
-EOF
 ```
 
 Or use the OpenAI Python SDK:
@@ -157,7 +152,7 @@ from openai import OpenAI
 
 client = OpenAI(
     base_url="http://localhost:8080/v1",
-    api_key="<devui-token>"
+    api_key="not-needed"  # API key not required for local DevUI
 )
 
 response = client.responses.create(
@@ -206,7 +201,6 @@ DevUI provides an **OpenAI Proxy** feature for testing OpenAI models directly th
 
 ```bash
 curl -X POST http://localhost:8080/v1/responses \
-  -H "Authorization: Bearer <devui-token>" \
   -H "X-Proxy-Backend: openai" \
   -d '{"model": "gpt-4.1-mini", "input": "Hello"}'
 ```
@@ -220,14 +214,14 @@ devui [directory] [options]
 
 Options:
   --port, -p      Port (default: 8080)
-  --host          Host (default: 127.0.0.1; non-loopback hosts require auth)
+  --host          Host (default: 127.0.0.1)
   --headless      API only, no UI
   --no-open       Don't automatically open browser
   --instrumentation  Enable OpenTelemetry instrumentation
   --reload        Enable auto-reload
   --mode          developer|user (default: developer)
-  --no-auth       Disable auth for loopback-only local development
-  --auth-token    Custom authentication token (required for non-loopback hosts unless DEVUI_AUTH_TOKEN is set)
+  --auth          Enable Bearer token authentication
+  --auth-token    Custom authentication token
 ```
 
 ### UI Modes
@@ -239,8 +233,8 @@ Options:
 # Development
 devui ./agents
 
-# Local-only no-auth development
-devui ./agents --no-auth
+# Production (user-facing)
+devui ./agents --mode user --auth
 ```
 
 ## Key Endpoints
@@ -342,39 +336,28 @@ These custom extensions are clearly namespaced and can be safely ignored by stan
 
 ## Security
 
-DevUI is designed as a **sample application for local development** and is not intended for production use. For
-production, or for features beyond this sample app, build a custom interface and API server using the Agent Framework SDK.
+DevUI is designed as a **sample application for local development** and should not be exposed to untrusted networks without proper authentication.
 
-Auth is enabled by default. Unauthenticated mode is allowed only when DevUI is bound to `localhost` or `127.0.0.1`.
-Network-reachable binds such as `0.0.0.0`, LAN IPs, and hostnames require Bearer token authentication with an explicit
-token.
-
-**For shared development hosts:**
+**For production deployments:**
 
 ```bash
-# Set a token explicitly before binding beyond loopback
-DEVUI_AUTH_TOKEN="<secure-dev-token>" devui ./agents --mode user --host 0.0.0.0
-
-# Or pass the token on the command line
-devui ./agents --mode user --host 0.0.0.0 --auth-token "<secure-dev-token>"
+# User mode with authentication (recommended)
+devui ./agents --mode user --auth --host 0.0.0.0
 ```
 
-Do not use `--no-auth` with `0.0.0.0`, LAN IPs, or hostnames. That configuration fails closed before startup.
+This restricts developer APIs (reload, deployment, entity details) and requires Bearer token authentication.
 
 **Security features:**
 
 - User mode restricts developer-facing APIs
-- Bearer token authentication is enabled by default
-- Unauthenticated mode is loopback-only (`localhost` / `127.0.0.1`)
-- Non-loopback binds require `DEVUI_AUTH_TOKEN` or `--auth-token`
+- Optional Bearer token authentication via `--auth`
 - Only loads entities from local directories or in-memory registration
 - No remote code execution capabilities
 - Binds to localhost (127.0.0.1) by default
 
 **Best practices:**
 
-- Do not use DevUI as a production deployment surface
-- Use `--mode user` plus `DEVUI_AUTH_TOKEN` or `--auth-token` for shared development hosts
+- Use `--mode user --auth` for any deployment exposed to end users
 - Review all agent/workflow code before running
 - Only load entities from trusted sources
 - Use `.env` files for sensitive credentials (never commit them)

python/packages/devui/agent_framework_devui/__init__.py

@@ -96,7 +96,7 @@ def serve(
     ui_enabled: bool = True,
     instrumentation_enabled: bool = False,
     mode: str = "developer",
-    auth_enabled: bool = True,
+    auth_enabled: bool = False,
     auth_token: str | None = None,
 ) -> None:
     """Launch Agent Framework DevUI with simple API.
@@ -126,6 +126,52 @@ def serve(
     if not isinstance(port, int) or not (1 <= port <= 65535):
         raise ValueError(f"Invalid port: {port}. Must be integer between 1 and 65535")
 
+    # Security check: Warn if network-exposed without authentication
+    if host not in ("127.0.0.1", "localhost") and not auth_enabled:
+        logger.warning("⚠️  WARNING: Exposing DevUI to network without authentication!")
+        logger.warning("⚠️  This is INSECURE - anyone on your network can access your agents")
+        logger.warning("💡 For network exposure, add --auth flag: devui --host 0.0.0.0 --auth")
+
+    # Handle authentication configuration
+    if auth_enabled:
+        import os
+        import secrets
+
+        # Check if token is in environment variable first
+        if not auth_token:
+            auth_token = os.environ.get("DEVUI_AUTH_TOKEN")
+
+        # Auto-generate token if STILL not provided
+        if not auth_token:
+            # Check if we're in a production-like environment
+            is_production = (
+                host not in ("127.0.0.1", "localhost")  # Exposed to network
+                or os.environ.get("CI") == "true"  # Running in CI
+                or os.environ.get("KUBERNETES_SERVICE_HOST")  # Running in k8s
+            )
+
+            if is_production:
+                # REFUSE to start without explicit token
+                logger.error("❌ Authentication enabled but no token provided")
+                logger.error("❌ Auto-generated tokens are NOT secure for network-exposed deployments")
+                logger.error("💡 Set token: export DEVUI_AUTH_TOKEN=<your-secure-token>")
+                logger.error("💡 Or pass: serve(entities=[...], auth_token='your-token')")
+                raise ValueError("DEVUI_AUTH_TOKEN required when host is not localhost")
+
+            # Development mode: auto-generate and show
+            auth_token = secrets.token_urlsafe(32)
+            logger.info("🔒 Authentication enabled with auto-generated token")
+            logger.info("\n" + "=" * 70)
+            logger.info("🔑 DEV TOKEN (localhost only, shown once):")
+            logger.info(f"   {auth_token}")
+            logger.info("=" * 70 + "\n")
+        else:
+            logger.info("🔒 Authentication enabled with provided token")
+
+        # Set environment variable for server to use
+        os.environ["AUTH_REQUIRED"] = "true"
+        os.environ["DEVUI_AUTH_TOKEN"] = auth_token
+
     # Enable instrumentation if requested
     if instrumentation_enabled:
         from agent_framework.observability import enable_instrumentation
@@ -141,8 +187,6 @@ def serve(
         cors_origins=cors_origins,
         ui_enabled=ui_enabled,
         mode=mode,
-        auth_enabled=auth_enabled,
-        auth_token=auth_token,
     )
 
     # Register in-memory entities if provided

python/packages/devui/agent_framework_devui/_cli.py

@@ -79,17 +79,15 @@ Examples:
     )
 
     parser.add_argument(
-        "--no-auth",
+        "--auth",
         action="store_true",
-        help=(
-            "Disable Bearer token authentication for loopback-only local development. Non-loopback hosts require auth."
-        ),
+        help="Enable authentication via Bearer token (required for deployed environments)",
     )
 
     parser.add_argument(
         "--auth-token",
         type=str,
-        help="Custom Bearer token. Required for non-loopback hosts when DEVUI_AUTH_TOKEN is not set.",
+        help="Custom authentication token (auto-generated if not provided with --auth)",
     )
 
     parser.add_argument("--version", action="version", version=f"Agent Framework DevUI {get_version()}")
@@ -186,7 +184,7 @@ def main() -> None:
             ui_enabled=ui_enabled,
             instrumentation_enabled=args.instrumentation,
             mode=mode,
-            auth_enabled=not args.no_auth,
+            auth_enabled=args.auth,
             auth_token=args.auth_token,  # Pass through explicit token only
         )