Add trust-model XML docs to AgentSessionStore, InMemoryAgentSessionStore, MapAGUI, A2A entry points

Agent-Logs-Url: https://github.com/microsoft/agent-framework/sessions/e466c53a-faad-40a8-8b5f-83cf0dce0b1d

Co-authored-by: lokitoth <6936551+lokitoth@users.noreply.github.com>

dotnet/src/Microsoft.Agents.AI.Hosting.A2A/A2AServerServiceCollectionExtensions.cs

@@ -28,6 +28,23 @@ public static class A2AServerServiceCollectionExtensions
     /// <param name="agentBuilder">The agent builder whose name identifies the agent.</param>
     /// <param name="configureOptions">An optional callback to configure <see cref="A2AServerRegistrationOptions"/>.</param>
     /// <returns>The <paramref name="agentBuilder"/> for chaining.</returns>
+    /// <remarks>
+    /// <para>
+    /// <strong>Trust model.</strong> The A2A <c>contextId</c> arrives from the wire
+    /// and is treated as a chain-resume identifier — <em>not</em> as an authorization
+    /// token. The <see cref="AgentSessionStore"/> contract carries no principal/owner
+    /// dimension, so when a persistent store is registered any caller who knows or
+    /// guesses another caller's <c>contextId</c> can resume that other caller's
+    /// persisted thread. Hosts that serve more than one user must compose a principal
+    /// dimension into the lookup key — typically by calling
+    /// <c>UseClaimsBasedSessionIsolation(...)</c> from
+    /// <c>Microsoft.Agents.AI.Hosting.AspNetCore</c> (or by registering a custom
+    /// <see cref="SessionIsolationKeyProvider"/>). When no isolation provider is
+    /// registered, behavior is unchanged — the bare <c>contextId</c> is used as the
+    /// conversation identifier, which is appropriate for first-run / single-user /
+    /// prototyping scenarios but unsafe for multi-user hosts.
+    /// </para>
+    /// </remarks>
     public static IHostedAgentBuilder AddA2AServer(this IHostedAgentBuilder agentBuilder, Action<A2AServerRegistrationOptions>? configureOptions = null)
     {
         ArgumentNullException.ThrowIfNull(agentBuilder);
@@ -46,6 +63,13 @@ public static class A2AServerServiceCollectionExtensions
     /// <param name="agentName">The name of the agent to create an A2A server for.</param>
     /// <param name="configureOptions">An optional callback to configure <see cref="A2AServerRegistrationOptions"/>.</param>
     /// <returns>The <paramref name="builder"/> for chaining.</returns>
+    /// <remarks>
+    /// See the trust-model remarks on <see cref="AddA2AServer(IHostedAgentBuilder, Action{A2AServerRegistrationOptions}?)"/>
+    /// for guidance on multi-user hosts (the wire <c>contextId</c> is a chain-resume
+    /// identifier, not an authorization token; multi-user hosts must compose a
+    /// principal dimension via <c>UseClaimsBasedSessionIsolation(...)</c> or a custom
+    /// <see cref="SessionIsolationKeyProvider"/>).
+    /// </remarks>
     public static IHostApplicationBuilder AddA2AServer(this IHostApplicationBuilder builder, string agentName, Action<A2AServerRegistrationOptions>? configureOptions = null)
     {
         ArgumentNullException.ThrowIfNull(builder);
@@ -65,6 +89,13 @@ public static class A2AServerServiceCollectionExtensions
     /// <param name="agent">The agent instance to create an A2A server for.</param>
     /// <param name="configureOptions">An optional callback to configure <see cref="A2AServerRegistrationOptions"/>.</param>
     /// <returns>The <paramref name="builder"/> for chaining.</returns>
+    /// <remarks>
+    /// See the trust-model remarks on <see cref="AddA2AServer(IHostedAgentBuilder, Action{A2AServerRegistrationOptions}?)"/>
+    /// for guidance on multi-user hosts (the wire <c>contextId</c> is a chain-resume
+    /// identifier, not an authorization token; multi-user hosts must compose a
+    /// principal dimension via <c>UseClaimsBasedSessionIsolation(...)</c> or a custom
+    /// <see cref="SessionIsolationKeyProvider"/>).
+    /// </remarks>
     public static IHostApplicationBuilder AddA2AServer(this IHostApplicationBuilder builder, AIAgent agent, Action<A2AServerRegistrationOptions>? configureOptions = null)
     {
         ArgumentNullException.ThrowIfNull(builder);
@@ -83,6 +114,13 @@ public static class A2AServerServiceCollectionExtensions
     /// <param name="agentName">The name of the agent to create an A2A server for.</param>
     /// <param name="configureOptions">An optional callback to configure <see cref="A2AServerRegistrationOptions"/>.</param>
     /// <returns>The <paramref name="services"/> for chaining.</returns>
+    /// <remarks>
+    /// See the trust-model remarks on <see cref="AddA2AServer(IHostedAgentBuilder, Action{A2AServerRegistrationOptions}?)"/>
+    /// for guidance on multi-user hosts (the wire <c>contextId</c> is a chain-resume
+    /// identifier, not an authorization token; multi-user hosts must compose a
+    /// principal dimension via <c>UseClaimsBasedSessionIsolation(...)</c> or a custom
+    /// <see cref="SessionIsolationKeyProvider"/>).
+    /// </remarks>
     public static IServiceCollection AddA2AServer(this IServiceCollection services, string agentName, Action<A2AServerRegistrationOptions>? configureOptions = null)
     {
         ArgumentNullException.ThrowIfNull(services);
@@ -114,6 +152,13 @@ public static class A2AServerServiceCollectionExtensions
     /// <param name="agent">The agent instance to create an A2A server for.</param>
     /// <param name="configureOptions">An optional callback to configure <see cref="A2AServerRegistrationOptions"/>.</param>
     /// <returns>The <paramref name="services"/> for chaining.</returns>
+    /// <remarks>
+    /// See the trust-model remarks on <see cref="AddA2AServer(IHostedAgentBuilder, Action{A2AServerRegistrationOptions}?)"/>
+    /// for guidance on multi-user hosts (the wire <c>contextId</c> is a chain-resume
+    /// identifier, not an authorization token; multi-user hosts must compose a
+    /// principal dimension via <c>UseClaimsBasedSessionIsolation(...)</c> or a custom
+    /// <see cref="SessionIsolationKeyProvider"/>).
+    /// </remarks>
     public static IServiceCollection AddA2AServer(this IServiceCollection services, AIAgent agent, Action<A2AServerRegistrationOptions>? configureOptions = null)
     {
         ArgumentNullException.ThrowIfNull(services);

dotnet/src/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore/AGUIEndpointRouteBuilderExtensions.cs

@@ -73,6 +73,26 @@ public static class AGUIEndpointRouteBuilderExtensions
     /// it will be used to persist conversation sessions across requests using the AG-UI thread ID as the
     /// conversation identifier. If no session store is registered, sessions are ephemeral (not persisted).
     /// </para>
+    /// <para>
+    /// <strong>Trust model.</strong> The AG-UI <c>RunAgentInput.ThreadId</c> arrives
+    /// from the wire and is treated as a chain-resume identifier — <em>not</em> as an
+    /// authorization token. The <see cref="AgentSessionStore"/> contract carries no
+    /// principal/owner dimension, so when a persistent store is registered any caller
+    /// who knows or guesses another caller's <c>ThreadId</c> can resume that other
+    /// caller's persisted thread. Hosts that serve more than one user must compose a
+    /// principal dimension into the lookup key. The recommended way is to wrap the
+    /// keyed <see cref="AgentSessionStore"/> in
+    /// <see cref="IsolationKeyScopedAgentSessionStore"/>, typically by calling
+    /// <c>UseClaimsBasedSessionIsolation(...)</c> from
+    /// <c>Microsoft.Agents.AI.Hosting.AspNetCore</c> (or by registering a custom
+    /// <see cref="SessionIsolationKeyProvider"/>) and registering the store via the
+    /// <c>WithSessionStore(...)</c> / <c>WithInMemorySessionStore(...)</c> helpers on
+    /// <see cref="IHostedAgentBuilder"/> so that the wrapper is applied. When no
+    /// isolation provider is registered, behavior is unchanged — the bare
+    /// <c>ThreadId</c> is used as the conversation identifier, which is appropriate
+    /// for first-run / single-user / prototyping scenarios but unsafe for
+    /// multi-user hosts.
+    /// </para>
     /// </remarks>
     public static IEndpointConventionBuilder MapAGUI(
         this IEndpointRouteBuilder endpoints,

dotnet/src/Microsoft.Agents.AI.Hosting/AgentSessionStore.cs

@@ -11,9 +11,39 @@ namespace Microsoft.Agents.AI.Hosting;
 /// Defines the contract for storing and retrieving agent conversation threads.
 /// </summary>
 /// <remarks>
+/// <para>
 /// Implementations of this interface enable persistent storage of conversation threads,
 /// allowing conversations to be resumed across HTTP requests, application restarts,
 /// or different service instances in hosted scenarios.
+/// </para>
+/// <para>
+/// <strong>Trust model.</strong> The <c>conversationId</c> passed to
+/// <see cref="GetSessionAsync"/> and <see cref="SaveSessionAsync"/> typically originates
+/// from the wire (for example, an AG-UI <c>RunAgentInput.ThreadId</c> or an A2A
+/// <c>contextId</c>). It is a chain-resume identifier, <em>not</em> an authorization
+/// token, and the <c>(agent, conversationId)</c> tuple carries no principal/owner
+/// dimension. Hosts that serve more than one user from the same registered store must
+/// therefore compose a principal dimension into the lookup key, otherwise any caller
+/// who knows or guesses another caller's <c>conversationId</c> can resume
+/// that other caller's persisted thread. The framework provides
+/// <see cref="IsolationKeyScopedAgentSessionStore"/> as a decorator that rewrites
+/// <c>conversationId</c> to include an isolation key resolved from a
+/// <see cref="SessionIsolationKeyProvider"/> (for example, the ASP.NET Core
+/// <c>ClaimsIdentitySessionIsolationKeyProvider</c> wired up via
+/// <c>UseClaimsBasedSessionIsolation(...)</c>). When no provider is registered, the
+/// store behaves as a single-namespace persistence layer — appropriate for
+/// single-user / first-run / prototyping scenarios but unsafe for multi-user hosts.
+/// </para>
+/// <para>
+/// <strong>Implementer guidance.</strong> Implementations should treat
+/// <c>conversationId</c> as opaque: do not parse it, do not impose length
+/// or character-set constraints on it, and do not assume it round-trips to the value
+/// the caller originally supplied (decorators such as
+/// <see cref="IsolationKeyScopedAgentSessionStore"/> may rewrite it before forwarding).
+/// Be aware that any logging, telemetry, or audit sink that surfaces
+/// <c>conversationId</c> will also surface the isolation prefix when a
+/// scoping decorator is in the chain.
+/// </para>
 /// </remarks>
 public abstract class AgentSessionStore
 {

dotnet/src/Microsoft.Agents.AI.Hosting/Local/InMemoryAgentSessionStore.cs

@@ -24,6 +24,20 @@ namespace Microsoft.Agents.AI.Hosting;
 /// For production use with multiple instances or persistence across restarts, use a durable storage implementation
 /// such as Redis, SQL Server, or Azure Cosmos DB.
 /// </para>
+/// <para>
+/// <strong>Multi-user warning.</strong> This store keys threads by
+/// <c>(agent.Id, conversationId)</c> only — it has no principal/owner dimension. When
+/// the conversation identifier originates from the wire (for example, an AG-UI
+/// <c>RunAgentInput.ThreadId</c> or an A2A <c>contextId</c>), any caller who knows
+/// or guesses another caller's identifier can resume that other caller's persisted
+/// thread. Multi-user hosts must wrap this store in
+/// <see cref="IsolationKeyScopedAgentSessionStore"/> (typically by calling
+/// <c>UseClaimsBasedSessionIsolation(...)</c> from
+/// <c>Microsoft.Agents.AI.Hosting.AspNetCore</c> or by registering a custom
+/// <see cref="SessionIsolationKeyProvider"/>) so that the conversation namespace is
+/// scoped per principal. See the trust-model remarks on
+/// <see cref="AgentSessionStore"/> for the full background.
+/// </para>
 /// </remarks>
 public sealed class InMemoryAgentSessionStore : AgentSessionStore
 {