Python: [BREAKING] Graduate harness todo & mode providers from experimental

[westey-m]

Motivation & Context

The Microsoft Agent Framework harness depends on several building-block features
that are still marked experimental. As part of releasing those dependencies (see
#6964), the todo and mode context providers are now stable enough to
graduate out of experimental status so downstream users can rely on them without
opting into experimental warnings.

While graduating the mode provider, its mode_descriptions parameter was also
renamed to mode_instructions, which more accurately reflects that the mapping
holds per-mode instructions (when and how to use each mode) that are injected as
instructions into the LLM.

Description & Review Guide

• What are the major changes?

  • Removed the @experimental(feature_id=ExperimentalFeature.HARNESS) decorators
    from the graduated todo types (TodoItem, TodoInput, TodoCompleteInput,
    TodoStore, TodoSessionStore, TodoProvider) and all mode symbols
    (AgentModeProvider, get_agent_mode, set_agent_mode).
  • Kept TodoFileStore experimental — it is opt-in (the default store is
    TodoSessionStore) and not yet ready to graduate.
  • De-exported TodoInput from the public API — it is an internal coercion type
    (the tool signatures use private TypedDicts), consistent with the already
    non-exported TodoCompleteInput.
  • Renamed AgentModeProvider's mode_descriptions parameter/attribute to
    mode_instructions, and the internal default map constant
    DEFAULT_MODE_DESCRIPTIONS to DEFAULT_MODE_MAP.
  • Updated the harness todo/mode tests to assert the graduated types carry no
    experimental metadata (while TodoFileStore stays experimental).

• What is the impact of these changes?

  • The todo and mode providers no longer emit experimental warnings.
  • Breaking (experimental surface only): TodoInput is no longer importable
    from agent_framework, and AgentModeProvider(mode_descriptions=...) must now
    be called as AgentModeProvider(mode_instructions=...). These affect preview
    users of the experimental harness API only; no released API is broken.
  • The shared ExperimentalFeature.HARNESS id is intentionally retained (still
    referenced by TodoFileStore and other harness symbols).

• What do you want reviewers to focus on?

  • That keeping TodoFileStore experimental while graduating the rest of the
    todo surface is the desired scope.

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 Python harness “todo” and “mode” context providers from experimental status so downstream users can rely on them without opting into experimental warnings, while keeping the file-backed todo store experimental. It also renames the AgentModeProvider configuration mapping from mode_descriptions to mode_instructions to better reflect its purpose.

Changes:

• Removed HARNESS experimental decorators/metadata from the graduated todo surface (TodoItem, TodoStore, TodoSessionStore, TodoProvider) and mode surface (AgentModeProvider, get_agent_mode, set_agent_mode).
• Renamed AgentModeProvider(mode_descriptions=...) to AgentModeProvider(mode_instructions=...) and updated the internal default mapping constant to DEFAULT_MODE_MAP.
• Updated tests to assert the graduated symbols carry no experimental metadata, while TodoFileStore remains experimental; also removed TodoInput from the public API exports.

Reviewed changes

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

Show a summary per file

File	Description
python/packages/core/tests/core/test_harness_todo.py	Updates tests for graduated todo types; imports TodoInput from internal module and keeps TodoFileStore experimental assertions.
python/packages/core/tests/core/test_harness_mode.py	Updates mode tests for the mode_instructions rename and removal of experimental metadata checks.
python/packages/core/agent_framework/_harness/_todo.py	Removes experimental decoration from graduated todo classes/providers while leaving TodoFileStore experimental.
python/packages/core/agent_framework/_harness/_mode.py	Removes experimental decoration from mode helpers/provider and renames configuration and default mapping constant.
python/packages/core/agent_framework/init.pyi	Removes TodoInput from public type exports.
python/packages/core/agent_framework/init.py	Removes TodoInput from runtime public exports.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework/_harness
_mode.py	98	1	98%	96
_todo.py	307	27	91%	87, 89, 91, 93, 139, 152, 154, 160–161, 172, 174, 207, 210, 216, 219, 359, 370–371, 382, 384, 393, 407, 411, 413, 507, 533, 565
TOTAL	44127	5265	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
8842	33 💤	0 ❌	0 🔥	2m 19s ⏱️

[github-actions]

Automated Code Review

Reviewers: 5 | Confidence: 92% | Result: All clear

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

---

Automated review by westey-m's agents