[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]

Scope: public API, user-visible behavior

Changed Go contract: agent/harness/agentmode package — new exported (*agentmode.Provider).GetModeForSession(session *agent.Session) string and SetModeForSession(session *agent.Session, mode string) error; existing GetMode(opts ...agent.Option) string and SetMode(mode string, opts ...agent.Option) error retained as option-based compatibility wrappers that now delegate to the session-first helpers.

Upstream evidence reviewed:

• .NET: [BREAKING] Graduate todo and agent mode providers out of experimental agent-framework#7052 (dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProvider.cs, GetModeAsync(AgentSession session, CancellationToken) / SetModeAsync(AgentSession session, string mode, CancellationToken), lines ~173–230)
• dotnet/tests/Microsoft.Agents.AI.UnitTests/Harness/AgentMode/AgentModeProviderTests.cs

Result: findings reported (one inline comment)

Summary: The Go PR correctly narrows the port to the session-first helper surface and keeps naming aligned (GetModeForSession/SetModeForSession vs. GetModeAsync/SetModeAsync, Async suffix omitted as an expected Go idiom since Go uses synchronous mutex-based locking here rather than SemaphoreSlim). Per-session locking parity with TodoProvider-style locking is preserved via getSessionLockForSession. However, upstream made the session parameter non-nullable for both getter and setter (Throw.IfNull(session) in both GetModeAsync and SetModeAsync), while the Go port only rejects nil sessions in SetModeForSession — GetModeForSession silently falls back to the default mode for a nil session, which is an inconsistent, divergent contract from upstream and from its own sibling setter. See inline comment for details and a suggested resolution.

No examples/ changes were included or expected for this narrowly-scoped API surface change.

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

[github-actions]

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

[github-actions]

Parity finding: Upstream AgentModeProvider.GetModeAsync(AgentSession session, ...) (dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProvider.cs, lines ~180-194) calls Throw.IfNull(session) and throws ArgumentNullException when the session is null — the upstream port explicitly made the session parameter non-nullable/required for both GetModeAsync and SetModeAsync as part of graduating this API (microsoft/agent-framework#7052).

Go's new GetModeForSession(session *agent.Session) silently accepts a nil session and falls back to the configured default mode (via getSessionLockForSession/loadStateForSession returning the null-session lock and default state) instead of returning an error. This is inconsistent with the sibling SetModeForSession, which does return fmt.Errorf("agentmode: no session available") for a nil session, and it diverges from the upstream contract that requires a non-null session for both getters and setters.

Suggested resolution: either (a) have GetModeForSession return an error (or panic, consistent with Go idioms for programmer errors) when session == nil, mirroring SetModeForSession and the upstream non-nullable contract, or (b) if the permissive nil-session default-mode fallback is an intentional Go-specific ergonomic choice, document that divergence explicitly in the doc comment so it is not mistaken for an oversight.

[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.