.NET: [BREAKING] Graduate todo and agent mode providers out of experimental

[westey-m]

Motivation & Context

The HarnessAgent is being prepared for release, but several of the features it
depends on are still marked experimental. This PR graduates the Todo and
Agent Mode providers (and their related types) out of experimental so they
can ship as part of the harness. These are features that are on by default when
using the harness, so they must be released rather than left behind an
experimental opt-in.

Part of the broader effort to release the harness dependencies.

Description & Review Guide

• What are the major changes?

  • Removed [Experimental(MAAI001)] from TodoProvider, AgentModeProvider,
    and their related todo/mode types. TodoCompletionLoopEvaluator remains
    experimental because it ships with the still-experimental Loop feature.
  • Renamed AgentMode.Description → AgentMode.Instructions, since the value is
    LLM instructions for the mode rather than a human-facing description.
  • Made the AgentSession parameters non-nullable (with Throw.IfNull) on
    TodoProvider.GetAllTodosAsync/GetRemainingTodosAsync and the mode helpers —
    a null session was effectively a no-op and only invited misuse.
  • Added per-session locking to AgentModeProvider (mirroring TodoProvider) so
    concurrent reads/mutations of the mode state on the same session are serialized.
    This made the public helpers async: GetMode/SetMode are now
    GetModeAsync/SetModeAsync.
  • Propagated the async change through the internal consumer
    (TodoCompletionLoopEvaluator) and the Harness console samples, and updated the
    affected unit tests.

• What is the impact of these changes?

  • The Todo and Agent Mode providers are now part of the stable (non-experimental)
    surface.
  • Breaking (experimental surface): AgentModeProvider.GetMode/SetMode are
    renamed to async GetModeAsync/SetModeAsync, and AgentMode.Description is
    renamed to Instructions. These types were experimental, but the change is
    flagged as breaking so preview users are notified.

• What do you want reviewers to focus on?

  • The per-session locking pattern on AgentModeProvider matches TodoProvider.

Related Issue

Related to #6964

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

Pull request overview

This PR graduates the .NET Harness Todo and Agent Mode providers from experimental to stable API surface, aligning them with the HarnessAgent’s default-on dependencies and tightening their concurrency and null-session behaviors.

Changes:

• Removed experimental annotations from Todo/AgentMode providers and related state/options types to make them part of the stable surface.
• Renamed AgentMode.Description → AgentMode.Instructions and propagated the rename through provider instruction rendering and tests/samples.
• Added per-session locking and async public helpers for Agent Mode (GetModeAsync/SetModeAsync), propagated async usage through the loop evaluator and console harness samples.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
dotnet/tests/Microsoft.Agents.AI.UnitTests/Harness/Loop/TodoCompletionLoopEvaluatorTests.cs	Updates tests to use async Agent Mode helpers.
dotnet/tests/Microsoft.Agents.AI.UnitTests/Harness/AgentMode/AgentModeProviderTests.cs	Updates tests for async mode helpers and renamed mode field.
dotnet/src/Microsoft.Agents.AI/Harness/Todo/TodoState.cs	Removes experimental annotation from todo state.
dotnet/src/Microsoft.Agents.AI/Harness/Todo/TodoProviderOptions.cs	Removes experimental annotation from todo options.
dotnet/src/Microsoft.Agents.AI/Harness/Todo/TodoProvider.cs	Makes session parameters non-nullable for public todo read APIs and updates diagnostics usage.
dotnet/src/Microsoft.Agents.AI/Harness/Todo/TodoItemInput.cs	Removes experimental annotation from todo tool input type.
dotnet/src/Microsoft.Agents.AI/Harness/Todo/TodoItem.cs	Removes experimental annotation from todo item type.
dotnet/src/Microsoft.Agents.AI/Harness/Todo/TodoCompleteInput.cs	Removes experimental annotation from todo completion input type.
dotnet/src/Microsoft.Agents.AI/Harness/Loop/TodoCompletionLoopEvaluator.cs	Switches evaluator mode read to async mode helper.
dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeState.cs	Removes experimental annotation from mode state.
dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProviderOptions.cs	Renames mode “Description” to “Instructions” and removes experimental annotation.
dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProvider.cs	Adds per-session locking, async public helpers, and updates tool/state handling accordingly.
dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/PlanningOutputObserver.cs	Updates observer to async mode reads/writes and async run-option configuration.
dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/ConsoleObserver.cs	Makes run option configuration async-friendly via ValueTask.
dotnet/samples/02-agents/Harness/Harness_Shared_Console/HarnessConsole.cs	Retrieves initial mode via async helper.
dotnet/samples/02-agents/Harness/Harness_Shared_Console/HarnessAgentRunner.cs	Propagates async observer configuration and async mode reads through the run loop.
dotnet/samples/02-agents/Harness/Harness_Shared_Console/Commands/ModeCommandHandler.cs	Updates /mode command to use async mode helpers.

[github-actions]

Automated Code Review

Reviewers: 4 | Confidence: 91% | Result: All clear

Reviewed: Correctness, Security Reliability, Test Coverage, Failure Modes

---

Automated review by westey-m's agents

[rogerbarreto]

I see a big breaking change accompanied by a removal, should we keep it experimental on the new API before graduating with a big change right away?

[westey-m]

I see a big breaking change accompanied by a removal, should we keep it experimental on the new API before graduating with a big change right away?

For graduation it's good to consider the public surface changes, and the change I made to the public surface is just about making all the methods async so I can await SemaphoreSlims. So while the change touches many files, it's conceptually not a significant change. It's also arguably more future safe to have async methods, so generally just an improvement.