.NET: Add Hosted-MemoryAgent sample with isolation key plumbing (#5692) (#5702)

* .NET: Add Hosted-MemoryAgent sample with isolation key plumbing (#5692)

Adds HostedSessionContext + HostedSessionIsolationKeyProvider in Microsoft.Agents.AI.Foundry.Hosting so AIContextProviders (notably FoundryMemoryProvider) can scope per user via the platform's x-agent-user-isolation-key / x-agent-chat-isolation-key headers.

- New types: HostedSessionContext (sealed), HostedSessionContextExtensions (public Get, internal Set), abstract HostedSessionIsolationKeyProvider (async), internal PlatformHostedSessionIsolationKeyProvider mapping ResponseContext.Isolation.

- AgentFrameworkResponseHandler now resolves the provider, tags fresh sessions, and validates resumed sessions against the live request (strict 403 'Hosted session identity context mismatch' on any mismatch; 500 on null keys).

- New shared sample project Hosted_Shared_Contributor_Setup hosts DevTemporaryTokenCredential and DevTemporaryLocalSessionIsolationKeyProvider plus AddDevTemporaryLocalContributorSetup. All 9 existing responses samples migrated to consume it so local runs keep working under the strict isolation contract.

- New Hosted-MemoryAgent sample: travel assistant wired through FoundryMemoryProvider with stateInitializer reading session.GetHostedContext().UserId. Includes Dockerfile, smoke.ps1, agent.yaml/manifest.

- New IT scenario 'memory' in Foundry.Hosting.IntegrationTests + MemoryHostedAgentFixture + MemoryHostedAgentTests. Verified end to end against the tao Foundry project.

- ADR 0026 captures the design tree.

* Address PR review feedback

- Dockerfile: add header noting it targets NuGet builds; contributors must use Dockerfile.contributor for ProjectReference source builds.

- PlatformHostedSessionIsolationKeyProvider: doc said 'returns context with empty values'; corrected to 'returns null' which the handler treats as 500.

- FakeHostedSessionIsolationKeyProvider: doc clarifies that null configurations are allowed for testing the handler error path.

- HostedSessionContextExtensions.SetHostedContext: enforce write-once with InvalidOperationException; doc + xml exception updated.

- AgentFrameworkResponseHandler: cache PlatformHostedSessionIsolationKeyProvider as static readonly to avoid per-request allocation.

- MemoryHostedAgentTests: tighten waits from 20s to 5s (FoundryMemoryProvider defaults UpdateDelay=0; ingestion ~3s).

- Sample Program.cs imports reordered to satisfy IDE0005.

* Add HostedFoundryMemoryProviderScopes built-in helpers (#5692)

Addresses review feedback from @lokitoth on Hosted-MemoryAgent/Program.cs:54.

- New HostedFoundryMemoryProviderScopes static class with PerUser, PerChat, PerUserAndChat factories returning Func<AgentSession?, FoundryMemoryProvider.State>.

- All helpers throw InvalidOperationException when GetHostedContext() is null, with a message pointing at writing a custom stateInitializer for non-hosted scenarios.

- New HostedFoundryMemoryScope enum and AddHostedFoundryMemoryProvider DI extension (two overloads: explicit AIProjectClient and DI-resolved). Singleton lifetime. Default scope = PerUser.

- Hosted-MemoryAgent sample and the memory IT scenario container both swap their inline lambdas for HostedFoundryMemoryProviderScopes.PerUser().

- 14 new unit tests (241/241 hosting unit tests pass).

* Replace HostedFoundryMemoryScope enum with Func<...> parameter (#5692)

Address PR review feedback from @westey-m: enums are a breaking-change hazard when extended, and the enum was redundant with the existing HostedFoundryMemoryProviderScopes static class.

- Delete HostedFoundryMemoryScope.cs.

- AddHostedFoundryMemoryProvider DI extensions now take Func<AgentSession?, FoundryMemoryProvider.State>? stateInitializer = null. When null, default to HostedFoundryMemoryProviderScopes.PerUser().

- Callers pick a built-in helper (PerUser/PerChat/PerUserAndChat) or pass a custom delegate. New built-ins are a single static method addition with zero impact on existing callers.

- Tests updated; 244/244 hosting unit tests pass.

* Fix isolation context resume for externally-created conversations (#5692)

Branch on the session's existing hosted-context (not on conversation_id presence) so a conversation provisioned externally (e.g. via conversations.CreateProjectConversationAsync) is treated as fresh on first hosted-agent request and stamped, rather than rejected with 403 hosted_session_identity_mismatch. Strict equality is preserved on real resume of an already-stamped session.

Also tighten dotnet/global.json to version 10.0.204 + rollForward latestPatch so local builds match the CI Docker image SDK and avoid 10.0.300 dotnet format stripping required usings.

* Revert global.json SDK pin to upstream (#5692)

The 10.0.204 + latestPatch pin from the previous commit broke the dotnet-format CI job (hostfxr_resolve_sdk2 could not find a compatible SDK in the mcr.microsoft.com/dotnet/sdk:10.0 image). Restore upstream 10.0.200 + minor; local Release builds with SDK 10.0.300 should set GITHUB_ACTIONS=true to bypass the auto-format-on-build target.

dotnet/tests/Foundry.Hosting.IntegrationTests.TestContainer/Program.cs

@@ -7,6 +7,7 @@ using Azure.Identity;
 using Azure.Search.Documents;
 using Azure.Search.Documents.Models;
 using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry;
 using Microsoft.Agents.AI.Foundry.Hosting;
 using Microsoft.Extensions.AI;
 
@@ -34,6 +35,7 @@ AIAgent agent = scenario switch
     "tool-calling-approval" => CreateToolCallingApprovalAgent(projectClient, deployment),
     "mcp-toolbox" => CreateMcpToolboxAgent(projectClient, deployment),
     "custom-storage" => CreateCustomStorageAgent(projectClient, deployment),
+    "memory" => await CreateMemoryAgentAsync(projectClient, deployment).ConfigureAwait(false),
     "azure-search-rag" => CreateAzureSearchRagAgent(projectClient, deployment),
     "session-files" => CreateSessionFilesAgent(projectClient, deployment),
     _ => throw new InvalidOperationException($"Unknown IT_SCENARIO '{scenario}'.")
@@ -179,6 +181,34 @@ static AIAgent CreateSessionFilesAgent(AIProjectClient client, string deployment
             AIFunctionFactory.Create(ReadFile)
         ]);
 
+// Memory scenario. The agent uses FoundryMemoryProvider scoped per user via the
+// HostedSessionContext that the hosting layer applies from the platform isolation headers.
+// In production the platform sets the headers; here we rely on the default
+// PlatformHostedSessionIsolationKeyProvider that AgentFrameworkResponseHandler resolves.
+static async Task<AIAgent> CreateMemoryAgentAsync(AIProjectClient client, string deployment)
+{
+    var embedding = Environment.GetEnvironmentVariable("AZURE_AI_EMBEDDING_DEPLOYMENT_NAME") ?? "text-embedding-ada-002";
+    var memoryStoreName = Environment.GetEnvironmentVariable("IT_MEMORY_STORE_ID") ?? "it-memory-store";
+
+    var memoryProvider = new FoundryMemoryProvider(
+        client,
+        memoryStoreName,
+        stateInitializer: HostedFoundryMemoryProviderScopes.PerUser());
+
+    await memoryProvider.EnsureMemoryStoreCreatedAsync(deployment, embedding, "Memory store for hosted-memory IT scenario.").ConfigureAwait(false);
+
+    return client.AsAIAgent(new ChatClientAgentOptions
+    {
+        Name = "memory-agent",
+        ChatOptions = new ChatOptions
+        {
+            ModelId = deployment,
+            Instructions = "You are a friendly travel assistant. Use known memories about the user when responding, and do not invent details."
+        },
+        AIContextProviders = [memoryProvider]
+    });
+}
+
 [Description("Returns the current UTC date and time as an ISO 8601 string.")]
 static string GetUtcNow() => DateTime.UtcNow.ToString("o");
 

dotnet/tests/Foundry.Hosting.IntegrationTests/Fixtures/MemoryHostedAgentFixture.cs

@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+
+namespace Foundry.Hosting.IntegrationTests.Fixtures;
+
+/// <summary>
+/// Provisions a hosted agent that runs the test container in <c>IT_SCENARIO=memory</c> mode.
+/// Used by tests that exercise <see cref="Microsoft.Agents.AI.Foundry.FoundryMemoryProvider"/>
+/// running inside the Foundry hosted agent. The memory store name is randomised per fixture
+/// instance so concurrent test runs do not share state.
+/// </summary>
+public sealed class MemoryHostedAgentFixture : HostedAgentFixture
+{
+    protected override string ScenarioName => "memory";
+
+    /// <summary>
+    /// Memory store name passed to the test container via <c>IT_MEMORY_STORE_ID</c> so that each
+    /// fixture instance gets a fresh, isolated bucket of memories.
+    /// </summary>
+    public string MemoryStoreId { get; } = $"it-memory-{Guid.NewGuid():N}";
+
+    protected override void ConfigureEnvironment(IDictionary<string, string> environment)
+    {
+        environment["IT_MEMORY_STORE_ID"] = this.MemoryStoreId;
+    }
+}

dotnet/tests/Foundry.Hosting.IntegrationTests/MemoryHostedAgentTests.cs

@@ -0,0 +1,79 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Threading.Tasks;
+using Foundry.Hosting.IntegrationTests.Fixtures;
+using Microsoft.Agents.AI;
+
+#pragma warning disable OPENAI001 // Experimental Responses API surfaces
+
+namespace Foundry.Hosting.IntegrationTests;
+
+/// <summary>
+/// Validates the Hosted-MemoryAgent end-to-end against a deployed test container running the
+/// <c>IT_SCENARIO=memory</c> scenario. Asserts that <see cref="Microsoft.Agents.AI.Foundry.FoundryMemoryProvider"/>
+/// scoped via <see cref="Microsoft.Agents.AI.Foundry.Hosting.HostedSessionContext"/> recalls user
+/// preferences across multiple turns of a conversation.
+/// </summary>
+[Trait("Category", "FoundryHostedAgents")]
+public sealed class MemoryHostedAgentTests(MemoryHostedAgentFixture fixture) : IClassFixture<MemoryHostedAgentFixture>
+{
+    private readonly MemoryHostedAgentFixture _fixture = fixture;
+
+    [Fact]
+    public async Task Memory_RecallsAcrossTurnsAsync()
+    {
+        // Arrange
+        var agent = this._fixture.Agent;
+        var session = await agent.CreateSessionAsync();
+
+        // Act: teach the agent two pieces of information about the user.
+        var first = await agent.RunAsync("My name is Taylor and I am planning a hiking trip to Patagonia in November.", session);
+        Assert.False(string.IsNullOrWhiteSpace(first.Text));
+
+        var second = await agent.RunAsync("I am travelling with my sister and we love finding scenic viewpoints.", session);
+        Assert.False(string.IsNullOrWhiteSpace(second.Text));
+
+        // FoundryMemoryProvider defaults to UpdateDelay=0 (immediate trigger). Server-side ingestion
+        // typically completes within ~3 seconds; allow a small margin.
+        await Task.Delay(TimeSpan.FromSeconds(5));
+
+        var recall = await agent.RunAsync("What do you already know about my upcoming trip?", session);
+
+        // Assert
+        Assert.Contains("Patagonia", recall.Text, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact(Skip = "Foundry Memory write propagation is eventually consistent and the in-container WhenUpdatesCompletedAsync flush hook is not callable from the test process; this scenario is exercised manually via the sample's smoke.ps1.")]
+    public async Task Memory_PersistsAcrossSessionsForSameUserAsync()
+    {
+        // Arrange: drive a session that establishes some user-private memory. Foundry Memory
+        // extracts memories more reliably from multi-turn conversations than from a single
+        // imperative utterance, so mirror the sample's two-turn teaching pattern.
+        var agent = this._fixture.Agent;
+        var teachingSession = await agent.CreateSessionAsync();
+        await agent.RunAsync("My preferred airline is Iberia and I always fly business class.", teachingSession);
+        await agent.RunAsync("I also prefer aisle seats whenever they are available.", teachingSession);
+
+        // FoundryMemoryProvider defaults to UpdateDelay=0 (immediate trigger). Server-side
+        // ingestion typically completes within ~3 seconds; poll a fresh-session recall a few
+        // times before failing so the test does not flake on cold caches.
+        AgentResponse recall = null!;
+        const int MaxAttempts = 6;
+        for (var attempt = 1; attempt <= MaxAttempts; attempt++)
+        {
+            await Task.Delay(TimeSpan.FromSeconds(5));
+
+            var freshSession = await agent.CreateSessionAsync();
+            recall = await agent.RunAsync("Which airline do I prefer? Reply with just the airline name.", freshSession);
+
+            if (recall.Text.Contains("Iberia", StringComparison.OrdinalIgnoreCase))
+            {
+                break;
+            }
+        }
+
+        // Assert
+        Assert.Contains("Iberia", recall.Text, StringComparison.OrdinalIgnoreCase);
+    }
+}

dotnet/tests/Foundry.Hosting.IntegrationTests/scripts/it-bootstrap-agents.ps1

@@ -45,6 +45,7 @@ $Scenarios = @(
     'tool-calling-approval',
     'mcp-toolbox',
     'custom-storage',
+    'memory',
     'azure-search-rag',
     'session-files'
 )

dotnet/tests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests/AgentFrameworkResponseHandlerTelemetryTests.cs

@@ -47,6 +47,7 @@ public class AgentFrameworkResponseHandlerTelemetryTests
         var services = new ServiceCollection();
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
         services.AddSingleton<AIAgent>(agent);
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
@@ -75,6 +76,7 @@ public class AgentFrameworkResponseHandlerTelemetryTests
         var services = new ServiceCollection();
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
         services.AddKeyedSingleton<AIAgent>("keyed-agent", agent);
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
@@ -116,6 +118,7 @@ public class AgentFrameworkResponseHandlerTelemetryTests
         var services = new ServiceCollection();
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
         services.AddSingleton(preWrapped);
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
@@ -147,6 +150,7 @@ public class AgentFrameworkResponseHandlerTelemetryTests
         var services = new ServiceCollection();
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
         services.AddSingleton<AIAgent>(agent);
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);

dotnet/tests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests/AgentFrameworkResponseHandlerTests.cs

@@ -29,6 +29,7 @@ public class AgentFrameworkResponseHandlerTests
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
         services.AddSingleton<AIAgent>(agent);
         services.AddSingleton<ILogger<AgentFrameworkResponseHandler>>(NullLogger<AgentFrameworkResponseHandler>.Instance);
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
@@ -67,6 +68,7 @@ public class AgentFrameworkResponseHandlerTests
         var services = new ServiceCollection();
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
         services.AddKeyedSingleton<AIAgent>("my-agent", agent);
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
@@ -102,6 +104,7 @@ public class AgentFrameworkResponseHandlerTests
         // Arrange
         var services = new ServiceCollection();
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
@@ -151,6 +154,7 @@ public class AgentFrameworkResponseHandlerTests
         var services = new ServiceCollection();
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
         services.AddKeyedSingleton<AIAgent>("my-agent", agent);
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
@@ -188,6 +192,7 @@ public class AgentFrameworkResponseHandlerTests
         var services = new ServiceCollection();
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
         services.AddKeyedSingleton<AIAgent>("entity-agent", agent);
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
@@ -228,6 +233,7 @@ public class AgentFrameworkResponseHandlerTests
         var services = new ServiceCollection();
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
         services.AddSingleton<AIAgent>(agent);
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
@@ -263,6 +269,7 @@ public class AgentFrameworkResponseHandlerTests
         // Arrange
         var services = new ServiceCollection();
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
@@ -297,6 +304,7 @@ public class AgentFrameworkResponseHandlerTests
         // Arrange
         var services = new ServiceCollection();
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
@@ -331,6 +339,7 @@ public class AgentFrameworkResponseHandlerTests
         // Arrange
         var services = new ServiceCollection();
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
@@ -376,6 +385,7 @@ public class AgentFrameworkResponseHandlerTests
         var services = new ServiceCollection();
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
         services.AddSingleton<AIAgent>(agent);
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
@@ -424,6 +434,7 @@ public class AgentFrameworkResponseHandlerTests
         var services = new ServiceCollection();
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
         services.AddSingleton<AIAgent>(agent);
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
@@ -467,6 +478,7 @@ public class AgentFrameworkResponseHandlerTests
         var services = new ServiceCollection();
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
         services.AddSingleton<AIAgent>(agent);
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
@@ -506,6 +518,7 @@ public class AgentFrameworkResponseHandlerTests
         var services = new ServiceCollection();
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
         services.AddSingleton<AIAgent>(agent);
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
@@ -548,6 +561,7 @@ public class AgentFrameworkResponseHandlerTests
         var services = new ServiceCollection();
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
         services.AddSingleton<AIAgent>(agent);
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
@@ -589,6 +603,7 @@ public class AgentFrameworkResponseHandlerTests
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
         services.AddKeyedSingleton<AIAgent>("agent-1", agent1);
         services.AddKeyedSingleton<AIAgent>("agent-2", agent2);
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
@@ -626,6 +641,7 @@ public class AgentFrameworkResponseHandlerTests
         var services = new ServiceCollection();
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
         services.AddSingleton<AIAgent>(agent);
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
@@ -663,6 +679,7 @@ public class AgentFrameworkResponseHandlerTests
         var services = new ServiceCollection();
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
         services.AddSingleton<AIAgent>(agent);
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);

dotnet/tests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests/AgentFrameworkResponseHandlerWorkflowTests.cs

@@ -144,6 +144,7 @@ public class AgentFrameworkResponseHandlerWorkflowTests
         var services = new ServiceCollection();
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
         services.AddKeyedSingleton("my-workflow", workflowAgent);
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
@@ -166,6 +167,7 @@ public class AgentFrameworkResponseHandlerWorkflowTests
         services.AddSingleton<AgentSessionStore>(new InMemoryAgentSessionStore());
         services.AddSingleton(agent);
         services.AddSingleton<ILogger<AgentFrameworkResponseHandler>>(NullLogger<AgentFrameworkResponseHandler>.Instance);
+        services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);

dotnet/tests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests/FakeHostedSessionIsolationKeyProvider.cs

@@ -0,0 +1,35 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Threading;
+using System.Threading.Tasks;
+using Azure.AI.AgentServer.Responses;
+using Azure.AI.AgentServer.Responses.Models;
+
+namespace Microsoft.Agents.AI.Foundry.Hosting.UnitTests;
+
+/// <summary>
+/// Test fake that returns a non-null <see cref="HostedSessionContext"/> by default, allowing tests
+/// that were written before the strict isolation-key contract to keep passing without each test
+/// having to stub <c>ResponseContext.Isolation</c>. The constructor also accepts <see langword="null"/>
+/// values so individual tests can exercise the handler's null-key error path.
+/// </summary>
+internal sealed class FakeHostedSessionIsolationKeyProvider : HostedSessionIsolationKeyProvider
+{
+    public const string DefaultUserId = "test-user-isolation";
+    public const string DefaultChatId = "test-chat-isolation";
+
+    private readonly HostedSessionContext? _context;
+
+    public FakeHostedSessionIsolationKeyProvider(string? userId = DefaultUserId, string? chatId = DefaultChatId)
+    {
+        this._context = userId is null || chatId is null
+            ? null
+            : new HostedSessionContext(userId, chatId);
+    }
+
+    public override ValueTask<HostedSessionContext?> GetKeysAsync(
+        ResponseContext context,
+        CreateResponse request,
+        CancellationToken cancellationToken)
+        => new(this._context);
+}

dotnet/tests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests/HostedFoundryMemoryProviderScopesTests.cs

@@ -0,0 +1,114 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+
+namespace Microsoft.Agents.AI.Foundry.Hosting.UnitTests;
+
+/// <summary>
+/// Tests for <see cref="HostedFoundryMemoryProviderScopes"/> built-in stateInitializer factories.
+/// </summary>
+public class HostedFoundryMemoryProviderScopesTests
+{
+    private const string TestUserId = "user-isolation-key-1";
+    private const string TestChatId = "chat-isolation-key-1";
+
+    [Fact]
+    public void PerUser_UsesUserIdAsScope()
+    {
+        // Arrange
+        var session = CreateTaggedSession(TestUserId, TestChatId);
+        var initializer = HostedFoundryMemoryProviderScopes.PerUser();
+
+        // Act
+        var state = initializer(session);
+
+        // Assert
+        Assert.NotNull(state);
+        Assert.Equal(TestUserId, state.Scope.Scope);
+    }
+
+    [Fact]
+    public void PerChat_UsesChatIdAsScope()
+    {
+        // Arrange
+        var session = CreateTaggedSession(TestUserId, TestChatId);
+        var initializer = HostedFoundryMemoryProviderScopes.PerChat();
+
+        // Act
+        var state = initializer(session);
+
+        // Assert
+        Assert.NotNull(state);
+        Assert.Equal(TestChatId, state.Scope.Scope);
+    }
+
+    [Fact]
+    public void PerUserAndChat_ComposesUserAndChatWithColon()
+    {
+        // Arrange
+        var session = CreateTaggedSession(TestUserId, TestChatId);
+        var initializer = HostedFoundryMemoryProviderScopes.PerUserAndChat();
+
+        // Act
+        var state = initializer(session);
+
+        // Assert
+        Assert.NotNull(state);
+        Assert.Equal($"{TestUserId}:{TestChatId}", state.Scope.Scope);
+    }
+
+    [Fact]
+    public void PerUser_NullSession_Throws()
+    {
+        // Arrange
+        var initializer = HostedFoundryMemoryProviderScopes.PerUser();
+
+        // Act & Assert
+        var ex = Assert.Throws<InvalidOperationException>(() => initializer(null));
+        Assert.Contains(nameof(HostedSessionContext), ex.Message);
+    }
+
+    [Fact]
+    public void PerChat_NullSession_Throws()
+    {
+        // Arrange
+        var initializer = HostedFoundryMemoryProviderScopes.PerChat();
+
+        // Act & Assert
+        Assert.Throws<InvalidOperationException>(() => initializer(null));
+    }
+
+    [Fact]
+    public void PerUserAndChat_NullSession_Throws()
+    {
+        // Arrange
+        var initializer = HostedFoundryMemoryProviderScopes.PerUserAndChat();
+
+        // Act & Assert
+        Assert.Throws<InvalidOperationException>(() => initializer(null));
+    }
+
+    [Fact]
+    public void PerUser_SessionWithoutHostedContext_Throws()
+    {
+        // Arrange
+        var session = new BareAgentSession();
+        var initializer = HostedFoundryMemoryProviderScopes.PerUser();
+
+        // Act & Assert
+        var ex = Assert.Throws<InvalidOperationException>(() => initializer(session));
+        Assert.Contains(nameof(HostedFoundryMemoryProviderScopes), ex.Message);
+    }
+
+    private static BareAgentSession CreateTaggedSession(string userId, string chatId)
+    {
+        var session = new BareAgentSession();
+        session.SetHostedContext(new HostedSessionContext(userId, chatId));
+        return session;
+    }
+
+    private sealed class BareAgentSession : AgentSession
+    {
+        public BareAgentSession() : base(new AgentSessionStateBag()) { }
+    }
+}

dotnet/tests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests/HostedFoundryMemoryProviderServiceCollectionExtensionsTests.cs

@@ -0,0 +1,118 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace Microsoft.Agents.AI.Foundry.Hosting.UnitTests;
+
+/// <summary>
+/// Tests for <see cref="HostedFoundryMemoryProviderServiceCollectionExtensions"/>.
+/// </summary>
+public class HostedFoundryMemoryProviderServiceCollectionExtensionsTests
+{
+    private const string TestUserId = "ext-user-1";
+    private const string TestChatId = "ext-chat-1";
+    private const string MemoryStoreName = "test-memory-store";
+
+    [Fact]
+    public void AddHostedFoundryMemoryProvider_ExplicitClient_RegistersSingleton()
+    {
+        // Arrange
+        var services = new ServiceCollection();
+        var client = CreateClient();
+
+        // Act
+        services.AddHostedFoundryMemoryProvider(client, MemoryStoreName);
+        var sp = services.BuildServiceProvider();
+
+        // Assert
+        var first = sp.GetRequiredService<FoundryMemoryProvider>();
+        var second = sp.GetRequiredService<FoundryMemoryProvider>();
+        Assert.Same(first, second);
+    }
+
+    [Fact]
+    public void AddHostedFoundryMemoryProvider_DiResolvedClient_RegistersSingleton()
+    {
+        // Arrange
+        var services = new ServiceCollection();
+        services.AddSingleton(CreateClient());
+
+        // Act
+        services.AddHostedFoundryMemoryProvider(MemoryStoreName);
+        var sp = services.BuildServiceProvider();
+
+        // Assert
+        var first = sp.GetRequiredService<FoundryMemoryProvider>();
+        var second = sp.GetRequiredService<FoundryMemoryProvider>();
+        Assert.Same(first, second);
+    }
+
+    [Fact]
+    public void AddHostedFoundryMemoryProvider_DiResolvedClient_MissingClient_Throws()
+    {
+        // Arrange
+        var services = new ServiceCollection();
+
+        // Act
+        services.AddHostedFoundryMemoryProvider(MemoryStoreName);
+        var sp = services.BuildServiceProvider();
+
+        // Assert
+        Assert.Throws<InvalidOperationException>(() => sp.GetRequiredService<FoundryMemoryProvider>());
+    }
+
+    [Fact]
+    public void AddHostedFoundryMemoryProvider_NullStateInitializer_DefaultsToPerUser()
+    {
+        // Arrange
+        var session = CreateTaggedSession();
+
+        // Act
+        var services = new ServiceCollection();
+        services.AddHostedFoundryMemoryProvider(CreateClient(), MemoryStoreName);
+        var provider = services.BuildServiceProvider().GetRequiredService<FoundryMemoryProvider>();
+
+        // Assert
+        Assert.NotNull(provider);
+        var defaultInitializer = HostedFoundryMemoryProviderScopes.PerUser();
+        var state = defaultInitializer(session);
+        Assert.Equal(TestUserId, state.Scope.Scope);
+    }
+
+    [Fact]
+    public void AddHostedFoundryMemoryProvider_CustomStateInitializer_IsHonored()
+    {
+        // Arrange
+        var session = CreateTaggedSession();
+        static FoundryMemoryProvider.State Custom(AgentSession? _)
+            => new(new FoundryMemoryProviderScope("custom-scope"));
+
+        // Act
+        var services = new ServiceCollection();
+        services.AddHostedFoundryMemoryProvider(CreateClient(), MemoryStoreName, Custom);
+        var provider = services.BuildServiceProvider().GetRequiredService<FoundryMemoryProvider>();
+
+        // Assert
+        Assert.NotNull(provider);
+        var state = Custom(session);
+        Assert.Equal("custom-scope", state.Scope.Scope);
+    }
+
+    private static AIProjectClient CreateClient()
+        => new(new Uri("https://example.services.ai.azure.com/api/projects/test"), new DefaultAzureCredential());
+
+    private static BareAgentSession CreateTaggedSession()
+    {
+        var session = new BareAgentSession();
+        session.SetHostedContext(new HostedSessionContext(TestUserId, TestChatId));
+        return session;
+    }
+
+    private sealed class BareAgentSession : AgentSession
+    {
+        public BareAgentSession() : base(new AgentSessionStateBag()) { }
+    }
+}

dotnet/tests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests/HostedOutboundUserAgentTests.cs

@@ -101,6 +101,7 @@ public sealed class HostedOutboundUserAgentTests : IAsyncDisposable
         AIAgent agent = new ChatClientAgent(chatClient);
 
         builder.Services.AddFoundryResponses(agent);
+        builder.Services.AddSingleton<HostedSessionIsolationKeyProvider>(new FakeHostedSessionIsolationKeyProvider());
         builder.Services.AddLogging();
 
         this._app = builder.Build();

dotnet/tests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests/HostedSessionIdentityContextTests.cs

@@ -0,0 +1,364 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+using Azure.AI.AgentServer.Responses;
+using Azure.AI.AgentServer.Responses.Models;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging.Abstractions;
+using Moq;
+
+namespace Microsoft.Agents.AI.Foundry.Hosting.UnitTests;
+
+/// <summary>
+/// Tests covering the per-session identity context that <see cref="AgentFrameworkResponseHandler"/>
+/// applies via the registered <see cref="HostedSessionIsolationKeyProvider"/>.
+/// </summary>
+public class HostedSessionIdentityContextTests
+{
+    private const string TestUserId = "user-isolation-key-1";
+    private const string TestChatId = "chat-isolation-key-1";
+
+    [Fact]
+    public void HostedSessionContext_RejectsNullOrWhitespaceKeys()
+    {
+        // Assert
+        Assert.Throws<ArgumentNullException>(() => new HostedSessionContext(null!, TestChatId));
+        Assert.Throws<ArgumentNullException>(() => new HostedSessionContext(TestUserId, null!));
+        Assert.Throws<ArgumentException>(() => new HostedSessionContext(string.Empty, TestChatId));
+        Assert.Throws<ArgumentException>(() => new HostedSessionContext(TestUserId, "   "));
+    }
+
+    [Fact]
+    public async Task PlatformProvider_MapsIsolationContextValuesAsync()
+    {
+        // Arrange
+        var provider = new PlatformHostedSessionIsolationKeyProvider();
+        var mockContext = new Mock<ResponseContext>("resp_" + new string('0', 46)) { CallBase = true };
+        mockContext.Setup(x => x.Isolation).Returns(new IsolationContext(TestUserId, TestChatId));
+        var request = new CreateResponse { Model = "test" };
+
+        // Act
+        var result = await provider.GetKeysAsync(mockContext.Object, request, CancellationToken.None);
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.Equal(TestUserId, result.UserId);
+        Assert.Equal(TestChatId, result.ChatId);
+    }
+
+    [Fact]
+    public async Task PlatformProvider_ReturnsNullWhenIsolationKeysAreEmptyAsync()
+    {
+        // Arrange
+        var provider = new PlatformHostedSessionIsolationKeyProvider();
+        var mockContext = new Mock<ResponseContext>("resp_" + new string('0', 46)) { CallBase = true };
+        // CallBase delegates to ResponseContext.Isolation default which is IsolationContext.Empty.
+        var request = new CreateResponse { Model = "test" };
+
+        // Act
+        var result = await provider.GetKeysAsync(mockContext.Object, request, CancellationToken.None);
+
+        // Assert
+        Assert.Null(result);
+    }
+
+    [Fact]
+    public async Task Handler_FreshSession_AppliesContextFromCustomProviderAsync()
+    {
+        // Arrange
+        var capturingAgent = new HostedContextCapturingAgent();
+        var fakeProvider = new FakeHostedSessionIsolationKeyProvider("alice", "chat-A");
+        var handler = BuildHandler(capturingAgent, fakeProvider);
+
+        var (request, mockContext) = BuildFreshRequest();
+
+        // Act
+        await DrainAsync(handler.CreateAsync(request, mockContext.Object, CancellationToken.None));
+
+        // Assert
+        Assert.NotNull(capturingAgent.LastSession);
+        var ctx = capturingAgent.LastSession.GetHostedContext();
+        Assert.NotNull(ctx);
+        Assert.Equal("alice", ctx.UserId);
+        Assert.Equal("chat-A", ctx.ChatId);
+    }
+
+    [Fact]
+    public async Task Handler_NullKeysFromProvider_ThrowsInvalidOperationAsync()
+    {
+        // Arrange
+        var capturingAgent = new HostedContextCapturingAgent();
+        var fakeProvider = new FakeHostedSessionIsolationKeyProvider(userId: null, chatId: null);
+        var handler = BuildHandler(capturingAgent, fakeProvider);
+
+        var (request, mockContext) = BuildFreshRequest();
+
+        // Act & Assert
+        var ex = await Assert.ThrowsAsync<InvalidOperationException>(() => DrainAsync(handler.CreateAsync(request, mockContext.Object, CancellationToken.None)));
+        Assert.Contains(nameof(HostedSessionIsolationKeyProvider), ex.Message);
+    }
+
+    [Fact]
+    public async Task Handler_ResumeSession_MatchingKeys_PassesAsync()
+    {
+        // Arrange
+        var capturingAgent = new HostedContextCapturingAgent();
+        var fakeProvider = new FakeHostedSessionIsolationKeyProvider("alice", "chat-A");
+        var sessionStore = new InMemoryAgentSessionStore();
+        var handler = BuildHandler(capturingAgent, fakeProvider, sessionStore);
+
+        // Step 1: drive a fresh request to populate the session store with a tagged session.
+        var (freshRequest, freshContext) = BuildFreshRequest();
+        await DrainAsync(handler.CreateAsync(freshRequest, freshContext.Object, CancellationToken.None));
+        Assert.NotNull(capturingAgent.LastSession);
+
+        // Step 2: persist the session under a known conversation id (mimics what the handler does
+        // when it has a conversation id; here we plant it directly so we can drive a resume request).
+        const string ConversationId = "resume-chat-id";
+        await sessionStore.SaveSessionAsync(capturingAgent, ConversationId, capturingAgent.LastSession, CancellationToken.None);
+
+        // Step 3: drive a resume request with the same isolation keys.
+        var (resumeRequest, resumeContext) = BuildResumeRequest(ConversationId);
+        capturingAgent.LastSession = null;
+
+        // Act
+        await DrainAsync(handler.CreateAsync(resumeRequest, resumeContext.Object, CancellationToken.None));
+
+        // Assert
+        Assert.NotNull(capturingAgent.LastSession);
+        var ctx = capturingAgent.LastSession.GetHostedContext();
+        Assert.NotNull(ctx);
+        Assert.Equal("alice", ctx.UserId);
+    }
+
+    [Fact]
+    public async Task Handler_ResumeSession_MismatchedUserId_Returns403Async()
+    {
+        // Arrange
+        var capturingAgent = new HostedContextCapturingAgent();
+        var aliceProvider = new FakeHostedSessionIsolationKeyProvider("alice", "chat-A");
+        var sessionStore = new InMemoryAgentSessionStore();
+        var aliceHandler = BuildHandler(capturingAgent, aliceProvider, sessionStore);
+
+        var (freshRequest, freshContext) = BuildFreshRequest();
+        await DrainAsync(aliceHandler.CreateAsync(freshRequest, freshContext.Object, CancellationToken.None));
+        const string ConversationId = "resume-chat-id";
+        await sessionStore.SaveSessionAsync(capturingAgent, ConversationId, capturingAgent.LastSession!, CancellationToken.None);
+
+        // Bob attempts to resume Alice's conversation.
+        var bobProvider = new FakeHostedSessionIsolationKeyProvider("bob", "chat-A");
+        var bobHandler = BuildHandler(capturingAgent, bobProvider, sessionStore);
+        var (resumeRequest, resumeContext) = BuildResumeRequest(ConversationId);
+
+        // Act & Assert
+        var ex = await Assert.ThrowsAsync<ResponsesApiException>(() => DrainAsync(bobHandler.CreateAsync(resumeRequest, resumeContext.Object, CancellationToken.None)));
+        Assert.Equal(403, ex.StatusCode);
+        Assert.Equal("Hosted session identity context mismatch", ex.Error.Message);
+    }
+
+    [Fact]
+    public async Task Handler_ResumeSession_MismatchedChatId_Returns403Async()
+    {
+        // Arrange
+        var capturingAgent = new HostedContextCapturingAgent();
+        var chatAProvider = new FakeHostedSessionIsolationKeyProvider("alice", "chat-A");
+        var sessionStore = new InMemoryAgentSessionStore();
+        var chatAHandler = BuildHandler(capturingAgent, chatAProvider, sessionStore);
+
+        var (freshRequest, freshContext) = BuildFreshRequest();
+        await DrainAsync(chatAHandler.CreateAsync(freshRequest, freshContext.Object, CancellationToken.None));
+        const string ConversationId = "resume-chat-id";
+        await sessionStore.SaveSessionAsync(capturingAgent, ConversationId, capturingAgent.LastSession!, CancellationToken.None);
+
+        var chatBProvider = new FakeHostedSessionIsolationKeyProvider("alice", "chat-B");
+        var chatBHandler = BuildHandler(capturingAgent, chatBProvider, sessionStore);
+        var (resumeRequest, resumeContext) = BuildResumeRequest(ConversationId);
+
+        // Act & Assert
+        var ex = await Assert.ThrowsAsync<ResponsesApiException>(() => DrainAsync(chatBHandler.CreateAsync(resumeRequest, resumeContext.Object, CancellationToken.None)));
+        Assert.Equal(403, ex.StatusCode);
+    }
+
+    [Fact]
+    public async Task Handler_ResumeSession_WithoutPriorContext_StampsAsFreshAsync()
+    {
+        // Arrange: store an untagged session. This case arises in production when the platform
+        // (or the caller) creates a Foundry conversation_id externally, and the very first
+        // hosted-agent request for that conversation hits the handler before any context is
+        // stamped. Such a session is treated as "fresh" rather than "resume" because there is
+        // no prior identity to defend; the stamp made now is what future resumes will validate.
+        var capturingAgent = new HostedContextCapturingAgent();
+        var sessionStore = new InMemoryAgentSessionStore();
+        const string ConversationId = "untagged-chat-id";
+        var untagged = await capturingAgent.CreateSessionAsync(CancellationToken.None);
+        await sessionStore.SaveSessionAsync(capturingAgent, ConversationId, untagged, CancellationToken.None);
+
+        var fakeProvider = new FakeHostedSessionIsolationKeyProvider("alice", "chat-A");
+        var handler = BuildHandler(capturingAgent, fakeProvider, sessionStore);
+        var (resumeRequest, resumeContext) = BuildResumeRequest(ConversationId);
+
+        // Act
+        await DrainAsync(handler.CreateAsync(resumeRequest, resumeContext.Object, CancellationToken.None));
+
+        // Assert
+        Assert.NotNull(capturingAgent.LastSession);
+        var ctx = capturingAgent.LastSession.GetHostedContext();
+        Assert.NotNull(ctx);
+        Assert.Equal("alice", ctx.UserId);
+        Assert.Equal("chat-A", ctx.ChatId);
+    }
+
+    [Fact]
+    public void GetHostedContext_ReturnsNullWhenAbsent()
+    {
+        // Arrange
+        var session = new HostedContextCapturingSession();
+
+        // Act
+        var ctx = session.GetHostedContext();
+
+        // Assert
+        Assert.Null(ctx);
+    }
+
+    [Fact]
+    public void SetHostedContext_ThenGet_RoundTrips()
+    {
+        // Arrange
+        var session = new HostedContextCapturingSession();
+
+        // Act
+        session.SetHostedContext(new HostedSessionContext("alice", "chat-A"));
+        var ctx = session.GetHostedContext();
+
+        // Assert
+        Assert.NotNull(ctx);
+        Assert.Equal("alice", ctx.UserId);
+        Assert.Equal("chat-A", ctx.ChatId);
+    }
+
+    private static AgentFrameworkResponseHandler BuildHandler(
+        AIAgent agent,
+        HostedSessionIsolationKeyProvider provider,
+        AgentSessionStore? sessionStore = null)
+    {
+        var services = new ServiceCollection();
+        services.AddSingleton(sessionStore ?? new InMemoryAgentSessionStore());
+        services.AddSingleton(agent);
+        services.AddSingleton(provider);
+        var sp = services.BuildServiceProvider();
+        return new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
+    }
+
+    private static (CreateResponse Request, Mock<ResponseContext> Context) BuildFreshRequest()
+    {
+        var request = new CreateResponse { Model = "test" };
+        request.Input = BinaryData.FromObjectAsJson(new[]
+        {
+            new { type = "message", id = "msg_1", status = "completed", role = "user",
+                  content = new[] { new { type = "input_text", text = "Hello" } } }
+        });
+
+        var mockContext = new Mock<ResponseContext>("resp_" + new string('0', 46)) { CallBase = true };
+        mockContext.Setup(x => x.GetHistoryAsync(It.IsAny<CancellationToken>()))
+            .ReturnsAsync(Array.Empty<OutputItem>());
+        mockContext.Setup(x => x.GetInputItemsAsync(It.IsAny<bool>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(Array.Empty<Item>());
+        return (request, mockContext);
+    }
+
+    private static (CreateResponse Request, Mock<ResponseContext> Context) BuildResumeRequest(string conversationId)
+    {
+        var (request, mockContext) = BuildFreshRequest();
+        request.Conversation = BinaryData.FromString($"\"{conversationId}\"");
+        return (request, mockContext);
+    }
+
+    private static async Task DrainAsync(IAsyncEnumerable<ResponseStreamEvent> stream)
+    {
+        await foreach (var _ in stream)
+        {
+        }
+    }
+
+    /// <summary>
+    /// Minimal <see cref="AIAgent"/> subclass that captures the session it was invoked with so tests
+    /// can inspect the <see cref="HostedSessionContext"/> applied by the handler.
+    /// </summary>
+    private sealed class HostedContextCapturingAgent : AIAgent
+    {
+        public AgentSession? LastSession { get; set; }
+
+        protected override IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(
+            IEnumerable<ChatMessage> messages,
+            AgentSession? session,
+            AgentRunOptions? options,
+            CancellationToken cancellationToken = default)
+        {
+            this.LastSession = session;
+            return ToAsyncEnumerableAsync(new AgentResponseUpdate
+            {
+                MessageId = "resp_msg_1",
+                Contents = [new Extensions.AI.TextContent("ok")]
+            });
+        }
+
+        protected override Task<AgentResponse> RunCoreAsync(
+            IEnumerable<ChatMessage> messages,
+            AgentSession? session,
+            AgentRunOptions? options,
+            CancellationToken cancellationToken = default) =>
+            throw new NotImplementedException();
+
+        protected override ValueTask<AgentSession> CreateSessionCoreAsync(
+            CancellationToken cancellationToken = default) =>
+            new(new HostedContextCapturingSession());
+
+        protected override ValueTask<JsonElement> SerializeSessionCoreAsync(
+            AgentSession session,
+            JsonSerializerOptions? jsonSerializerOptions = null,
+            CancellationToken cancellationToken = default) =>
+            new(((HostedContextCapturingSession)session).Serialize());
+
+        protected override ValueTask<AgentSession> DeserializeSessionCoreAsync(
+            JsonElement serializedState,
+            JsonSerializerOptions? jsonSerializerOptions = null,
+            CancellationToken cancellationToken = default) =>
+            new(HostedContextCapturingSession.Deserialize(serializedState));
+
+        private static async IAsyncEnumerable<AgentResponseUpdate> ToAsyncEnumerableAsync(params AgentResponseUpdate[] items)
+        {
+            foreach (var item in items)
+            {
+                yield return item;
+            }
+
+            await Task.CompletedTask;
+        }
+    }
+
+    /// <summary>
+    /// Minimal session implementation that round-trips its <see cref="AgentSessionStateBag"/> via JSON.
+    /// </summary>
+    private sealed class HostedContextCapturingSession : AgentSession
+    {
+        public HostedContextCapturingSession()
+        {
+        }
+
+        private HostedContextCapturingSession(AgentSessionStateBag bag)
+        {
+            this.StateBag = bag;
+        }
+
+        public JsonElement Serialize() => this.StateBag.Serialize();
+
+        public static HostedContextCapturingSession Deserialize(JsonElement element)
+            => new(AgentSessionStateBag.Deserialize(element));
+    }
+}