.NET: Hosting.Channels surface - Phase 1

[rogerbarreto]

Scope

Port the Python feature/python-hosting work (the "hosting channels" surface) to .NET. Tracks the staged delivery onto the existing microsoft/agent-framework:feature/dotnet-hosting-channels integration branch.

Spec: docs/specs/003-dotnet-hosting-channels.md (lands with the first PR).

Why

Today every wire format (Responses, A2A, AG-UI, Functions, Foundry hosting) has its own Map* extension and its own state-and-identity story bolted on. As more transports land (Telegram, Discord, Slack, Activity Protocol), the surface area multiplies and cross-channel scenarios (link a Telegram identity to a Responses session, fan a response out to multiple destinations, etc.) have no consistent place to live.

The hosting-channels surface introduces a single composable seam — one AgentFrameworkHost per target, many Channels mounted side-by-side — with shared infrastructure for authorization, identity linking, link policies, host-execution state, durable push, and response-target routing. Python locked the design first; this issue tracks the literal .NET port.

Posture

Translate, not redesign. Python is canonical. Names, taxonomy, wire-level behaviors mirror Python; ASP.NET Core mechanics only where they have to. Net-new in v1; existing Hosting.OpenAI / Hosting.A2A / Hosting.AGUI.AspNetCore / Hosting.AzureFunctions / Foundry.Hosting packages stay untouched.

Delivery plan

Staged PRs against feature/dotnet-hosting-channels.

1. Core scaffold — Microsoft.Agents.AI.Hosting.Channels (Channel, ChannelContribution, capability interfaces, ChannelRequest, ResponseTarget, HostedRunResult, HostedStreamItem, AgentFrameworkHost + AuthorizeAsync pipeline, IAgentFrameworkHostBuilder, Map/AddAgentFrameworkHost extensions, IsolationKeys).
2. Identity + state + runner — IIdentityAllowlist family + combinators + AuthorizationProfile, IIdentityLinker, ILinkPolicy + 4 built-ins, IHostStateStore + InMemory and File impls, IDurableTaskRunner + InProcessDurableTaskRunner, OneTimeCodeIdentityLinker, ResponseRouter (registers hosting.push, walks response targets, fans out, runs per-destination hooks, echo idempotency).
3. Channel: Invocations — Microsoft.Agents.AI.Hosting.Channels.Invocations. JSON POST /invocations/invoke + background + polling. WorkflowRunResult rendered as awaiting_input / completed / failed.
4. Workflow runner — drives InProcessExecution.RunStreamingAsync, persists resume tokens on IHostStateStore, resumes via ExternalResponse.
5. Channel: Telegram — Microsoft.Agents.AI.Hosting.Channels.Telegram. Polling + webhook over raw HTTP. IChannelPush. ConversationScope (PerUser / PerUserPerConversation / PerConversation). AcceptInGroup (MentionOnly default for groups). DM-redirect link challenge. setMyCommands at startup.
6. Sample + unit tests — one sample per channel under samples/04-hosting/HostingChannels/. Microsoft.Agents.AI.Hosting.Channels.UnitTests covering response target / allowlists / state store / linker / durable runner.
7. Fast-follow (separate issues): Microsoft.Agents.AI.Hosting.Channels.Responses (Responses wire-compat), FoundryHostedAgentRunner in Microsoft.Agents.AI.Foundry.Hosting, IsolationKeysMiddleware (ASP.NET Core header lifting), workflow-runner durability across process restarts, per-channel IChannelPushCodec (for JSON-payload durable runners), .DurableTask / .Discord / .Activity / .EntraId packages.

Active PRs

• #6151 — draft scaffold (commits 1–6 above)

Out of scope (v1)

• Rewriting any existing Map* extension to delegate to the new builder. Tier-2 migration ships as a separate, fast-follow release once v1 is stable.
• Any hard break in alpha or shipped packages.

References

• Python source branch: feature/python-hosting
• Python Discord channel PR (fast-follow reference): Python: add agent-framework-hosting-discord channel #6081
• Python hosting spec (the spec this .NET work ports): docs/specs/002-python-hosting-channels.md on the Python branch

[rogerbarreto]

Realigned to the ADR split now on main:

• ADR-0027 (minimal hosting core + pluggable channels) is the scope of PR .NET: Hosting.Channels minimal core + Responses channel (ADR-0027) #6151: host core + the Responses channel + samples + tests. Mirrors the Python slice in Python: Add hosting core and Responses channel #6580.
• ADR-0028 (linking / authorization / multicast / push / background / durable runners) is deferred to follow-up PRs.

PR #6151 was reduced from the earlier broad draft accordingly (net roughly -4k lines). The removed ADR-0028 .NET code is preserved on a local branch and will seed the 0028 follow-up PR.