[dotnet-port-api] Align agentmode session helpers

[Michelle Clayton (michelle-clayton-work)]

Summary

Add explicit session-first AgentMode helper APIs by introducing (*agentmode.Provider).GetModeForSession and SetModeForSession, then keep the existing option-based GetMode and SetMode methods as compatibility wrappers.

This ports the narrow public API portion of the upstream AgentMode graduation work so Go callers can read and update mode state directly from an *agent.Session, matching the current .NET usage model without forcing a breaking rename of the existing Go helpers.

Upstream reference:

• microsoft/agent-framework@e57f046 - Graduate mode and todo providers
  microsoft/agent-framework@e57f046

Ported .NET PRs

• .NET: [BREAKING] Graduate todo and agent mode providers out of experimental agent-framework#7052 - graduate mode and todo providers

Breaking Changes

No.

Tests and Examples

• go test ./agent/harness/agentmode -count=1
• go test ./agent/... -count=1
• Added focused coverage for GetModeForSession and SetModeForSession
• Updated the external mode-change tests to exercise the new session-based helpers
• Updated docs/dotnet-go-sdk-feature-comparison.md
• No examples changed

Notes

• The existing option-based GetMode and SetMode APIs remain available and now delegate to the new session-first helpers.
• This PR intentionally ports only the AgentMode session-helper surface from .NET: [BREAKING] Graduate todo and agent mode providers out of experimental agent-framework#7052; broader todo-provider graduation work was left out to keep the nightly change narrowly scoped.
• Existing workflow items already cover nearby tool-approval and workflow-behavior changes, so they were intentionally not bundled here.
• Upstream head inspected during candidate selection was upstream-agent-framework/main at 7c6b1e975.

Generated by .NET to Go API Porting Agent · 876.6 AIC · ⌖ 39 AIC · ⊞ 21.7K · ◷

Closes #568

[Copilot]

🟢 Approval recommended

The change is additive with compatibility wrappers preserved, and the updated tests/docs support the intended session-first API shape.

Pull request overview

Adds explicit session-first AgentMode helper APIs so callers can read/write mode state directly from an *agent.Session, while keeping the existing option-based helpers as compatibility wrappers (aligning the Go surface with the .NET usage model without breaking changes).

Changes:

• Introduces (*agentmode.Provider).GetModeForSession and SetModeForSession, and refactors internal state/lock helpers to accept a session directly.
• Keeps GetMode / SetMode as wrappers delegating to the new session-first APIs.
• Updates harness docs and adjusts/extends tests to cover the new helper methods.

File summaries

File	Description
agent/harness/agentmode/agentmode.go	Adds session-first mode helpers and refactors lock/state helpers; preserves existing option-based API via wrappers.
agent/harness/agentmode/agentmode_test.go	Adds focused tests for GetModeForSession / SetModeForSession and updates external mode-change tests to use session-first helpers.
docs/dotnet-go-sdk-feature-comparison.md	Updates feature matrix text to mention AgentMode session helper API alignment.

Review details

Suppressed comments (2)

agent/harness/agentmode/agentmode_test.go:333

• session, _ := agent.GetOption(...) ignores the ok flag, which can mask missing-session option regressions and make the test pass/fail for the wrong reason. Add an assertion that the session option is present and non-nil.

	opts := sessionOpts()
	session, _ := agent.GetOption(opts, agent.WithSession)
	msgs := newMessages("hi")

agent/harness/agentmode/agentmode_test.go:365

• session, _ := agent.GetOption(...) ignores the ok flag, so a missing session option could be silently treated as nil and make this test assert the wrong behavior. Assert ok and non-nil session before calling SetModeForSession.

	opts := sessionOpts()
	session, _ := agent.GetOption(opts, agent.WithSession)
	msgs := newMessages("hi")

• Files reviewed: 3/3 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

Generated by Go API Consistency Review Agent for #1004 · copilot · auto · 55.5 AIC · ⌖ 7.36 AIC · ⊞ 9.5K

[Michelle Clayton (michelle-clayton-work)]

Copilot address PR feedback

[Copilot]

Copilot address PR feedback

The session-option assertions are present in all three cited tests in a2b04a2; go test ./agent/harness/agentmode -count=1 passes.

[Quim Muntal (qmuntal)]

Don't use the Get prefix.

[Quim Muntal (qmuntal)]

Remove this function.

[Quim Muntal (qmuntal)]

Remove this function.

[github-actions]

Generated by Go API Consistency Review Agent for #1004 · copilot · auto · 128.6 AIC · ⌖ 6.38 AIC · ⊞ 9.6K

[Quim Muntal (qmuntal)]

Copilot resolve the merge conflicts in this pull request

[Copilot]

Copilot resolve the merge conflicts in this pull request

Resolved the merge conflict and merged the current main into this branch in aacfb3e.

[github-actions]

Go API Consistency Review

• Scope: public API, user-visible behavior
• Changed Go contract: agent/harness/agentmode — Provider.GetMode(opts ...agent.Option) string and Provider.SetMode(mode string, opts ...agent.Option) error are removed and replaced by new session-first methods Provider.ModeForSession(session *agent.Session) string and Provider.SetModeForSession(session *agent.Session, mode string) error. Internal helpers getSessionLock/loadState/saveState were refactored to delegate to new session-typed variants (getSessionLockForSession, loadStateForSession, saveStateForSession); this refactor itself is fine.
• Upstream evidence reviewed:
  • microsoft/agent-framework#7052 — "[BREAKING] Graduate todo and agent mode providers out of experimental" (PR)
  • dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProvider.cs — renames GetMode/SetMode to async GetModeAsync/SetModeAsync, adds per-session locking, and this rename is explicitly flagged as breaking (PR title [BREAKING], PR body: "Breaking (experimental surface): AgentModeProvider.GetMode/SetMode are renamed... These types were experimental, but the change is flagged as breaking so preview users are notified.")
  • Compare with the companion Go PR [dotnet-port-api] Add TodoProvider session helpers #1003 (agent/harness/todo), which ported the same upstream commit for TodoProvider and similarly renamed GetAllItems/GetRemainingItems → AllTodos/RemainingTodos without keeping compatibility wrappers, but that PR's description accurately said this was additive/non-breaking only because upstream's TodoProvider helpers were being added fresh in Go (no prior Go equivalent existed at that name).
• Result: findings reported.

Summary

The PR body states "Breaking Changes: No" and explicitly claims "The existing option-based GetMode and SetMode APIs remain available and now delegate to the new session-first helpers." However, the diff for agent/harness/agentmode/agentmode.go shows GetMode and SetMode are deleted outright — I could not find any remaining method named GetMode or SetMode on *Provider, nor a wrapper that delegates to ModeForSession/SetModeForSession. This is a real, unflagged breaking change to previously-stable Go public API (the Go agentmode package carries no experimental marker), left inline on the removed methods with a suggested fix (keep thin compatibility wrappers, or correct the PR description and explicitly document the break).

Aside from this compatibility gap, the session-first API shape (ModeForSession(session), SetModeForSession(session, mode)) is a reasonable and idiomatic Go parallel to upstream's GetModeAsync(session, ct)/SetModeAsync(session, mode, ct), and the per-session locking behavior already existed in Go via getSessionLock prior to this PR, so no divergence there. The docs/dotnet-go-sdk-feature-comparison.md update accurately reflects the new session helpers.

Generated by Go API Consistency Review Agent for #1004 · copilot · auto · 107.8 AIC · ⌖ 5.89 AIC · ⊞ 9.6K · ◷

[github-actions]

Generated by Go API Consistency Review Agent for #1004 · copilot · auto · 107.8 AIC · ⌖ 5.89 AIC · ⊞ 9.6K