[FEATURE] Deprecate the message-log session managers once snapshot parity and a migration path land #3664

SDK Language

Python

Problem Statement

Python now ships two session systems: the new snapshot-based SnapshotSessionManager (#3283) and the older message-log managers (FileSessionManager, S3SessionManager, RepositorySessionManager). Keeping both indefinitely means two on-disk formats, two code paths to maintain and test, and no clear answer to "which session manager should I use?".

The intent is to converge on snapshots, but deprecation cannot happen yet — the legacy managers are still the only option for three supported workloads:

This is not hypothetical: an earlier revision of #3283 did add @deprecated to all three legacy managers, and it was reverted precisely because the replacement covered neither orchestrators nor Bidi nor existing sessions — a warning telling users to migrate to an API that silently persists nothing for their workload is worse than no warning.

Proposed Solution

Treat this as the gated follow-up. Deprecate only once every workload the legacy managers serve has a supported replacement and a migration path:

• Multi-agent (Graph/Swarm) snapshot support — [FEATURE] Support snapshot session management for multi-agent (Graph/Swarm) #3662
• Migration from message-log sessions — [FEATURE] Provide a migration path from the message-log session managers to SnapshotSessionManager #3663
• BidiAgent snapshot support (or an explicit decision that Bidi keeps a message-log manager, in which case scope the deprecation to exclude it)
• User-guide documentation for the snapshot manager, including the migration procedure (currently tracked as a docs follow-up on feat: add snapshot session manager to python #3283; the session-management guide still labels immutable snapshots and session deletion as TypeScript-only)

Then, per team/FEATURE_LIFECYCLE.md:

• Apply the @deprecated decorator (not a bare warnings.warn in __init__) so the deprecation surfaces to type checkers and IDEs, with a message naming the replacement and linking the migration guide.
• State the removal version explicitly (next major), keeping the classes fully functional until then.
• Update the changelog and the session-management docs, and file the removal as a tracked task against that major.

If Bidi is intentionally excluded, the deprecation message should say which usage is superseded rather than deprecating the class outright.

Use Case

• A new user reads the session docs and gets exactly one recommended answer instead of two overlapping systems.
• An existing user upgrading gets a warning that points at a replacement which actually supports their workload, plus a migration procedure that preserves their sessions.
• Maintainers get to delete a format and its test matrix at the next major instead of carrying both indefinitely.

Alternatives Solutions

• Keep both indefinitely. No migration burden on users, but permanent double maintenance and a persistent "which one?" question.
• Docs-only soft deprecation first — mark the message-log managers as legacy in the guide and recommend snapshots for new code, without runtime warnings. This is a reasonable intermediate step that could land as soon as the docs exist, ahead of the full gate.
• Deprecate only for the single-agent case — scope the guidance to the usage that is genuinely superseded and leave the classes undeprecated for orchestrators/Bidi. Lower risk, but a partial deprecation is harder to communicate.

Additional Context

When this does land it is a user-visible deprecation and eventually a breaking removal, so it warrants the API bar-raising process and a changelog entry, and the removal itself should be scheduled against a major version rather than a minor.

References

• feat: add snapshot session manager to python #3283 (snapshot session manager; the earlier revision's deprecation of all three legacy managers was reverted for lack of a replacement)
• Blocked on: [FEATURE] Support snapshot session management for multi-agent (Graph/Swarm) #3662 (multi-agent support), [FEATURE] Provide a migration path from the message-log session managers to SnapshotSessionManager #3663 (migration path)
• Process: team/FEATURE_LIFECYCLE.md (deprecation timeline and implementation standard), team/API_BAR_RAISING.md

Recommended labels (the triage label declared by the issue template does not exist in this repo, so none were applied): enhancement, python, area-sessions, area-persistence, breaking change.