feat: add snapshot session manager to python

strands-py/src/strands/session/__init__.py

@@ -1,18 +1,28 @@
 """Session module.
 
 This module provides session management functionality.
+
+``SnapshotSessionManager`` is the recommended path for new agents: it persists the whole
+agent as a versioned snapshot to a unified :class:`~strands.storage.storage.Storage` backend
+and supports checkpointing (time-travel restore). The repository-based managers
+(``FileSessionManager``, ``S3SessionManager``, ``RepositorySessionManager``) persist each
+message individually and are deprecated.
 """
 
 from .file_session_manager import FileSessionManager
 from .repository_session_manager import RepositorySessionManager
 from .s3_session_manager import S3SessionManager
 from .session_manager import SessionManager
 from .session_repository import SessionRepository
+from .snapshot_session_manager import SaveLatestStrategy, SnapshotSessionManager, SnapshotTrigger
 
 __all__ = [
     "FileSessionManager",
     "RepositorySessionManager",
     "S3SessionManager",
+    "SaveLatestStrategy",
     "SessionManager",
     "SessionRepository",
+    "SnapshotSessionManager",
+    "SnapshotTrigger",
 ]

strands-py/src/strands/session/file_session_manager.py

@@ -5,6 +5,7 @@
 import os
 import shutil
 import tempfile
+import warnings
 from typing import TYPE_CHECKING, Any, cast
 
 from .. import _identifier
@@ -55,6 +56,12 @@ def __init__(
             storage_dir: Directory for local filesystem storage (defaults to temp dir).
             **kwargs: Additional keyword arguments for future extensibility.
         """
+        warnings.warn(
+            "FileSessionManager is deprecated and will be removed in Strands SDK 2.0. "
+            "Use SnapshotSessionManager with a LocalFileStorage instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         self.storage_dir = storage_dir or os.path.join(tempfile.gettempdir(), "strands/sessions")
         os.makedirs(self.storage_dir, exist_ok=True)
 

strands-py/src/strands/session/repository_session_manager.py

@@ -2,6 +2,7 @@
 
 import copy
 import logging
+import warnings
 from typing import TYPE_CHECKING, Any
 
 from ..agent.state import AgentState
@@ -46,6 +47,15 @@ def __init__(
             **kwargs: Additional keyword arguments for future extensibility.
 
         """
+        # Subclasses (FileSessionManager, S3SessionManager) emit their own, more specific
+        # deprecation warning; only warn when RepositorySessionManager is used directly.
+        if type(self) is RepositorySessionManager:
+            warnings.warn(
+                "RepositorySessionManager is deprecated and will be removed in Strands SDK 2.0. "
+                "Use SnapshotSessionManager with a Storage backend instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         self.session_repository = session_repository
         self.session_id = session_id
         session = session_repository.read_session(session_id)
@@ -279,9 +289,7 @@ def _fix_broken_tool_use(self, messages: list[Message]) -> list[Message]:
 
         for index in reversed(tool_use_indices):
             message = messages[index]
-            tool_use_ids = [
-                content["toolUse"]["toolUseId"] for content in message["content"] if "toolUse" in content
-            ]
+            tool_use_ids = [content["toolUse"]["toolUseId"] for content in message["content"] if "toolUse" in content]
 
             next_message = messages[index + 1]
             next_content = next_message["content"]

strands-py/src/strands/session/s3_session_manager.py

@@ -2,6 +2,7 @@
 
 import json
 import logging
+import warnings
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from typing import TYPE_CHECKING, Any, cast
 
@@ -70,6 +71,12 @@ def __init__(
                 or VPC endpoints (PrivateLink)
             **kwargs: Additional keyword arguments for future extensibility.
         """
+        warnings.warn(
+            "S3SessionManager is deprecated and will be removed in Strands SDK 2.0. "
+            "Use SnapshotSessionManager with an S3Storage instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         self.bucket = bucket
         self.prefix = prefix