.NET: Fix hosted agent crash after tool call by rooting session store under $HOME (#6231)#6714
Merged
rogerbarreto merged 2 commits intoJun 24, 2026
Merged
Conversation
… under $HOME FileSystemAgentSessionStore.CreateDefault rooted the hosted session store at the filesystem root "/.checkpoints", which is read-only inside a Foundry hosted container. After a local tool call the response handler persists the session, so the write to "/.checkpoints" threw IOException and tore down the container, which the platform surfaced as "mount: /app: mount failed: No such file or directory.". Root the hosted store at $HOME (default /home/session), the only writable and durable location per the container image spec. Persistence failures stay fatal but are now wrapped in a clear, actionable IOException instead of the opaque raw error. Add unit tests covering hosted and local path resolution plus the clear error, and enable the ToolCalling Foundry Hosted Agents integration tests (verified live). Fixes microsoft#6231
Contributor
There was a problem hiding this comment.
Pull request overview
This PR fixes a regression in the .NET Foundry hosting layer where hosted agents can crash after the first local tool call due to the default file-based session store attempting to write under the container filesystem root (/.checkpoints) on a read-only root filesystem. It updates the default hosted storage root to use the platform-provided writable/durable $HOME volume and adds/reenables test coverage to validate the behavior end-to-end.
Changes:
- Update
FileSystemAgentSessionStore.CreateDefault()to root hosted session persistence under$HOME/.checkpoints(fallback/home/session/.checkpoints) while keeping local behavior under{cwd}/.checkpoints. - Improve
SaveSessionAsyncfailure diagnostics by wrappingIOException/UnauthorizedAccessExceptionwith an actionable message that explains the$HOMErequirement (preserving the original exception asInnerException). - Add unit tests for hosted/local path resolution + failure message, and re-enable the hosted agent tool-calling integration tests.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/FileSystemAgentSessionStore.cs | Changes hosted default session-store root to $HOME and improves fatal error messaging on non-writable roots. |
| dotnet/tests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests/FileSystemAgentSessionStoreTests.cs | Adds unit coverage for hosted/local root resolution and for clear fatal IO error messaging on non-writable roots. |
| dotnet/tests/Foundry.Hosting.IntegrationTests/ToolCallingHostedAgentTests.cs | Re-enables hosted tool-calling integration tests to validate multi-turn server-side tool invocation and persistence. |
Address review feedback on microsoft#6714: a misconfigured HOME pointing at a filesystem root (e.g. "/") resolved back to "/.checkpoints" and would reintroduce the original read-only-root crash. CreateDefault now falls back to the default session-data directory (/home/session) when HOME is missing, blank, a filesystem root, or an unnormalizable path. Adds a unit test locking in the "never the filesystem root" behavior for a hosted HOME of "/". Related microsoft#6231
SergeyMenshykh
approved these changes
Jun 24, 2026
westey-m
approved these changes
Jun 24, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation & Context
After upgrading a .NET hosted Foundry agent to
Microsoft.Agents.AI.Foundry.Hosting1.8.0, the container starts but crashes right after the agent invokes a localAIFunctionFactory.Create(...)tool, with the platform logmount: /app: mount failed: No such file or directory..Root cause: PR #5589 (first shipped in 1.8.0) made
FileSystemAgentSessionStorethe default session store inAddFoundryResponses. When hosted,CreateDefault()rooted the store at the absolute path/.checkpoints(the filesystem root).AgentFrameworkResponseHandlerpersists the session in afinallyafter the response stream, so the first tool-call turn writes under/.checkpoints. In a Foundry hosted container the root filesystem is read-only, soDirectory.CreateDirectory("/.checkpoints")throwsIOException: Read-only file system, which tears down the request and the container. Themount: /appmessage is the platform's downstream symptom. 1.3.0 had no file-backed default, which is why the upgrade introduced the failure.Per
container-image-spec.mdsection 5, the only writable and durable location in a hosted container is$HOME(default/home/session); the root filesystem is read-only and paths outside$HOMEmay be cleared between requests.Description & Review Guide
What are the major changes?
FileSystemAgentSessionStore.CreateDefault()now roots the hosted store at{$HOME}/.checkpoints(envHOME, default/home/session) instead of/.checkpoints. Local (non-hosted) behavior is unchanged ({cwd}/.checkpoints).ResolveDefaultRootDirectory(isHosted, home, cwd)so it can be unit tested without the process-wide cachedFoundryEnvironment.IsHosted.SaveSessionAsyncnow wrapsIOException/UnauthorizedAccessExceptionin a clear, actionableIOExceptionthat names the path and the$HOMErequirement, preserving the raw error asInnerException.HostedCheckpointDirectory("/.checkpoints") is replaced bySessionDataDirectoryEnvironmentVariable("HOME") andDefaultHostedSessionDataDirectory("/home/session") on the[Experimental]FileSystemAgentSessionStoretype.ToolCallingHostedAgentTests(previously skipped pending end to end smoke), which exercise server-side tool invocation and multi-turn session persistence in a real hosted container.What is the impact of these changes?
$HOMEvolume so they survive across requests and restarts.Verification
--warnaserrorclean (0 warnings) on the changed projects.dotnet format --verify-no-changes(Dockermcr.microsoft.com/dotnet/sdk:10.0) clean on all three changed projects.FileSystemAgentSessionStoreTestspass.IOException: Read-only file system : '/.checkpoints'under a read-only root container, and confirms the fix succeeds when$HOMEis writable and emits the clear fatal error when it is not.ToolCallingFoundry Hosted Agents integration tests pass end to end against a live Foundry project, including the multi-turn session-persistence test, confirming the platform mounts$HOMEwritable and the fix resolves the issue.Related Issue
Fixes #6231
Contribution Checklist