Python: Move SessionStore to core and persist Foundry Responses sessions

[eavanvalkenburg]

Motivation & Context

Core agents need a reusable way to persist complete AgentSession state, while Foundry Responses hosting currently restores transcript history without restoring middleware state, provider state, or service continuation handles. This change moves session storage into core and uses it in Foundry hosting so state survives Responses API calls with explicit per-user isolation.

Description & Review Guide

• What are the major changes? Move the concrete, overridable SessionStore into core; add an experimental msgspec-backed FileSessionStore with JSON and MessagePack formats, atomic replacement, restricted storage keys, and explicit custom-state registration; make msgspec the FileHistoryProvider default while deprecating custom dumps/loads; and restore/save sessions throughout the Foundry Responses lifecycle using a request identity resolver and scoped file storage. The change also updates hosting imports, samples, package metadata, tests, and ADR-0033.
• What is the impact of these changes? Regular Foundry-hosted agents can retain framework session state across streaming and non-streaming Responses calls, including process restarts, while sessions, checkpoints, and approvals remain partitioned by authenticated identity. Consumers of the alpha hosting package now import SessionStore from agent_framework, and core gains a msgspec runtime dependency.
• What do you want reviewers to focus on? The concrete overridable store API, typed serialization and dynamic state registry, Foundry persistence lifecycle on success/failure/cancellation, and the per-user storage isolation boundaries.

Related Issue

No issue is linked for this draft, as requested.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_feature_stage.py	189	10	94%	109, 148, 164, 219, 230, 251, 289, 328, 378, 406
_sessions.py	727	53	92%	120, 176, 178, 189, 203, 227, 268, 273, 275, 285, 306, 322, 386, 393, 395, 464–465, 598, 880–884, 899, 929, 966–967, 981, 983, 1002, 1004, 1087, 1093, 1127, 1198, 1202, 1212, 1425, 1502, 1564, 1580, 1659, 1730, 1759, 1778, 1781, 1789–1790, 1802–1803, 1815, 1825, 1855
packages/core/agent_framework/_harness
_memory.py	774	117	84%	75–76, 92, 99, 151, 164, 171–173, 196, 216, 225–229, 292, 298, 333, 414, 422, 424, 428, 431, 435, 530, 542, 560–561, 572–573, 584, 699, 716, 725, 740, 768, 771–773, 783, 805–808, 857, 867, 870, 872, 892, 902, 907, 910, 922, 992, 994, 996, 998, 1000, 1002, 1072, 1089, 1117, 1146, 1154–1156, 1158, 1212, 1238–1241, 1247, 1402, 1405, 1416–1417, 1421, 1424–1426, 1432, 1436, 1441, 1445, 1450, 1454, 1462–1463, 1514, 1517–1520, 1527–1528, 1556, 1560–1568, 1585, 1611–1612, 1615–1616, 1622, 1624, 1629, 1634, 1640
packages/foundry_hosting/agent_framework_foundry_hosting
_responses.py	970	103	89%	213–216, 283, 286–287, 330, 407, 480–481, 495, 498–499, 549, 554–555, 571, 633, 654–658, 669, 709, 723, 754, 768, 822–823, 828, 853, 856, 862, 864, 940, 1027–1028, 1146, 1376, 1389, 1880–1882, 1884, 1931–1932, 1934–1935, 1937–1938, 1940–1941, 1946, 1955, 1958–1960, 1962, 1972, 1976, 1989, 2080–2081, 2096–2097, 2099, 2104–2108, 2110, 2117–2118, 2120–2121, 2127, 2129–2133, 2140, 2146, 2168, 2174, 2180, 2182, 2184–2187, 2195, 2197, 2258–2260, 2274–2275, 2278–2279
_session_isolation.py	62	2	96%	70, 87
packages/hosting-telegram/agent_framework_hosting_telegram
_parsing.py	155	5	96%	79, 121, 200, 208, 240
packages/hosting/agent_framework_hosting
_state.py	106	9	91%	137, 150–152, 234, 264, 277–279
TOTAL	45967	4489	90%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9445	33 💤	0 ❌	0 🔥	2m 31s ⏱️

[Copilot]

Pull request overview

Moves Python session persistence primitives into agent-framework-core and updates Foundry Responses hosting to persist/restore full AgentSession state (not just transcript history), including a new msgspec-backed file store and explicit per-user storage isolation for hosted scenarios.

Changes:

• Introduces experimental SessionStore (in-memory) and FileSessionStore (JSON/MessagePack, atomic replace) in core, plus a stricter session-state type registry via register_state_type.
• Switches FileHistoryProvider default JSON codec to msgspec (and adds optional MessagePack), deprecating custom JSON dumps/loads hooks.
• Updates Foundry Responses hosting to persist sessions across calls, partition durable storage by resolved authenticated identity, and harden isolation/scoping across sessions, checkpoints, and approvals.

Reviewed changes

Copilot reviewed 34 out of 35 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
python/uv.lock	Adds msgspec to the locked dependency set.
python/samples/04-hosting/af-hosting/README.md	Updates sample documentation to reflect core-owned SessionStore.
python/samples/04-hosting/af-hosting/local_telegram/README.md	Updates Telegram session-id format description (no :).
python/samples/04-hosting/af-hosting/local_responses/README.md	Documents use of core FileSessionStore for session snapshots.
python/samples/04-hosting/af-hosting/local_responses/app.py	Wires AgentState to a FileSessionStore for local persistence.
python/samples/02-agents/conversations/file_history_provider.py	Removes optional orjson path; documents msgspec default.
python/samples/02-agents/conversations/file_history_provider_conversation_persistence.py	Removes optional orjson path; documents msgspec default.
python/samples/02-agents/context_providers/simple_context_provider.py	Demonstrates explicit register_state_type for persisted custom state.
python/packages/hosting/tests/hosting/test_state.py	Updates hosting tests for core-owned SessionStore and new ID validation.
python/packages/hosting/README.md	Documents new core session store APIs and ID restrictions.
python/packages/hosting/agent_framework_hosting/_state.py	Removes hosting-owned store implementation; uses core SessionStore and validation.
python/packages/hosting/agent_framework_hosting/init.py	Stops re-exporting SessionStore.
python/packages/hosting-telegram/tests/hosting_telegram/test_parsing.py	Updates tests for new Telegram session-id format.
python/packages/hosting-telegram/README.md	Updates docs to refer to core session stores and new ID format.
python/packages/hosting-telegram/agent_framework_hosting_telegram/_parsing.py	Changes telegram_session_id output to use underscore-delimited IDs.
python/packages/hosting-responses/README.md	Documents session store location in core.
python/packages/foundry_hosting/tests/test_responses.py	Adds/updates tests for session persistence and isolation behavior.
python/packages/foundry_hosting/README.md	Documents hosted persistence behavior, default storage layout, and isolation resolver.
python/packages/foundry_hosting/agent_framework_foundry_hosting/_session_isolation.py	Adds isolation resolver and scoped file session store wrapper.
python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses.py	Implements session persistence + isolation scoping across Responses lifecycle.
python/packages/foundry_hosting/agent_framework_foundry_hosting/init.py	Exposes new isolation-related public types.
python/packages/core/tests/core/test_sessions.py	Adds comprehensive tests for state registry + session/file stores + msgspec history changes.
python/packages/core/tests/core/test_harness_memory.py	Removes custom JSON codec plumbing now that msgspec is default.
python/packages/core/tests/core/test_feature_stage.py	Adds test ensuring internal subclasses don’t warn under experimental features.
python/packages/core/pyproject.toml	Adds msgspec runtime dependency.
python/packages/core/AGENTS.md	Updates package map docs for new session persistence APIs.
python/packages/core/agent_framework/_sessions.py	Adds session stores + registry hardening + msgspec-based history/session serialization.
python/packages/core/agent_framework/_harness/_memory.py	Marks history codec overrides as deprecated.
python/packages/core/agent_framework/_feature_stage.py	Avoids experimental warnings for internal framework subclasses.
python/packages/core/agent_framework/init.pyi	Exports SessionStore/FileSessionStore typing surface.
python/packages/core/agent_framework/init.py	Exports SessionStore/FileSessionStore runtime surface.
python/PACKAGE_STATUS.md	Adds SESSION_STORE feature-stage entry and updates staged-API listing.
python/AGENTS.md	Adds “Changelog Ownership” guidance for Python PRs.
python/.github/skills/agent-framework-py-release/SKILL.md	Documents that release workflow owns python/CHANGELOG.md.
docs/decisions/0033-python-session-store-serialization.md	Adds ADR for session store ownership + msgspec serialization strategy.

[github-actions]

Automated Code Review

Reviewers: 4 | Confidence: 84% | Result: All clear

Reviewed: Correctness, Security Reliability, Test Coverage, Design Approach

---

Automated review by eavanvalkenburg's agents