strands_session_dynamodb 0.1.0__tar.gz

strands_session_dynamodb-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+*.egg-info/
+.pytest_cache/
+uv.lock

strands_session_dynamodb-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: strands_session_dynamodb
+Version: 0.1.0
+Summary: Amazon DynamoDB session manager (storage backend) for Strands Agents — persists sessions, agent state, and messages
+Project-URL: Homepage, https://github.com/skamalj/strands-agents-session
+Project-URL: Repository, https://github.com/skamalj/strands-agents-session.git
+Author-email: Kamal <skamalj@github.com>
+Keywords: agent-state,aws,dynamodb,memory,persistence,session,strands,strands-agents
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: boto3
+Requires-Dist: strands-agents
+Requires-Dist: strands-agents-session>=0.1.0
+Description-Content-Type: text/markdown
+
+# strands-session-dynamodb
+
+Amazon DynamoDB **session manager** (storage backend) for [Strands Agents](https://strandsagents.com). Persists an agent's sessions, **agent state**, conversation-manager state, and messages to a single DynamoDB table so conversations resume across runs.
+
+It implements Strands' `SessionRepository` and mixes in `RepositorySessionManager` — exactly like the built-in `S3SessionManager` — so all the session lifecycle logic (message indexing, restore, `removed_message_count` offsetting, tool-use repair, change detection) is reused unchanged. This package only supplies the DynamoDB storage.
+
+> **Storage only, by design.** In Strands, message *pruning* is the job of a `ConversationManager` (`SlidingWindow`, `Summarizing`), which is deliberately decoupled from storage. This package does **not** prune — pruning at the storage layer would corrupt Strands' message-index/offset restore logic. Use a `conversation_manager` for that.
+
+## Why DynamoDB instead of S3
+
+Strands ships an `S3SessionManager` out of the box, so why DynamoDB? Because agent sessions are a **request-bound, small-item** workload — the exact shape where DynamoDB wins on both cost and latency.
+
+Strands writes **one item per message** plus an agent record re-synced each turn — lots of tiny (sub-KB) reads and writes. The bill is dominated by *request count*, not bytes stored, and that's where the two services price very differently:
+
+| | S3 Standard | DynamoDB on-demand |
+|---|---|---|
+| Write | ~$5.00 / million PUT (any size) | ~$1.25 / million WRU (per 1 KB) |
+| Read | ~$0.40 / million GET (per object) | ~$0.25 / million RRU (per 4 KB) |
+| Free tier | none | 25 WCU + 25 RCU + 25 GB, perpetual |
+| Latency | tens of ms | single-digit ms |
+
+Two structural advantages for small items:
+
+- **Writes:** S3 charges per request regardless of size — a 200-byte message costs the same PUT as a 4 MB one. DynamoDB bills per KB, so tiny messages hit the cheapest unit *and* the per-unit price is ~4× lower.
+- **Reads:** `list_messages` is **one Query** in DynamoDB, and one RRU covers 4 KB — so several small messages per RRU. In S3 it's **one GET per message object**. Batching crushes the per-item read cost.
+
+For a workload of ~1M small message-writes/month with periodic restores, this is roughly a **3–4× lower bill** on DynamoDB — and often **free** under DynamoDB's perpetual free tier, which S3 has no equivalent of. Add native **TTL** for automatic session expiry and single-digit-ms access, and DynamoDB is the better default for hot session/agent-state storage.
+
+**When S3 still wins:** very large message payloads (big tool results, images) that approach or exceed DynamoDB's 400 KB item limit, or cold/archival sessions rarely read (S3 storage is ~10× cheaper per GB). A robust production setup is DynamoDB for the session/message records + S3 overflow only for oversized blobs.
+
+## Installation
+
+```bash
+pip install strands-session-dynamodb
+# or, via the family's extra:
+pip install "strands-agents-session[dynamodb]"
+```
+
+**Requires Python 3.10+.**
+
+## Quick start
+
+```python
+from strands import Agent
+from strands_session_dynamodb import DynamoDBSessionManager
+
+session_manager = DynamoDBSessionManager(
+    session_id="user-123",
+    table_name="strands-sessions",
+    region_name="us-east-1",
+)
+
+agent = Agent(session_manager=session_manager)
+
+agent("Hi, I'm Kamal")
+agent("What's my name?")   # remembers within the session
+```
+
+Next run, same `session_id` → the agent restores its full history and state from DynamoDB. The table is created automatically (on-demand billing) if it does not exist.
+
+## API
+
+### `DynamoDBSessionManager(session_id, table_name, *, region_name=None, boto_session=None, boto_client_config=None, endpoint_url=None, ttl_seconds=None)`
+
+| Parameter | Description |
+|---|---|
+| `session_id` | Session identifier |
+| `table_name` | DynamoDB table (auto-created if absent) |
+| `region_name` | AWS region |
+| `boto_session` | Optional pre-built `boto3.Session` |
+| `boto_client_config` | Optional `botocore` client config |
+| `endpoint_url` | Custom endpoint (e.g. DynamoDB Local / LocalStack) |
+| `ttl_seconds` | If set, writes a `ttl` epoch attribute and enables table TTL for automatic session expiry |
+
+## AWS setup
+
+Standard AWS credential resolution (env vars, `~/.aws/credentials`, profile, or IAM role). The credentials need permission to create the table (if absent) and read/write items.
+
+## Data model
+
+Single table, both keys strings:
+
+| Item | PK | SK |
+|---|---|---|
+| Session | `SESSION#<session_id>` | `META` |
+| Agent | `SESSION#<session_id>` | `AGENT#<agent_id>` |
+| Message | `SESSION#<session_id>#AGENT#<agent_id>` | `MSG#<zero-padded id>` |
+
+Messages live in a per-agent partition with a zero-padded, lexically ordered sort key, so `list_messages(offset, limit)` is a native range Query — matching the `removed_message_count` offset semantics Strands relies on. Payloads are stored as a JSON string.
+
+> **Item-size note:** DynamoDB items are capped at 400 KB. A single message with a very large payload (e.g. big tool results / images) could exceed that; S3 has no such limit. For such workloads, keep large blobs in S3 and reference them.
+
+## License
+
+MIT

strands_session_dynamodb-0.1.0/README.md

@@ -0,0 +1,95 @@
+# strands-session-dynamodb
+
+Amazon DynamoDB **session manager** (storage backend) for [Strands Agents](https://strandsagents.com). Persists an agent's sessions, **agent state**, conversation-manager state, and messages to a single DynamoDB table so conversations resume across runs.
+
+It implements Strands' `SessionRepository` and mixes in `RepositorySessionManager` — exactly like the built-in `S3SessionManager` — so all the session lifecycle logic (message indexing, restore, `removed_message_count` offsetting, tool-use repair, change detection) is reused unchanged. This package only supplies the DynamoDB storage.
+
+> **Storage only, by design.** In Strands, message *pruning* is the job of a `ConversationManager` (`SlidingWindow`, `Summarizing`), which is deliberately decoupled from storage. This package does **not** prune — pruning at the storage layer would corrupt Strands' message-index/offset restore logic. Use a `conversation_manager` for that.
+
+## Why DynamoDB instead of S3
+
+Strands ships an `S3SessionManager` out of the box, so why DynamoDB? Because agent sessions are a **request-bound, small-item** workload — the exact shape where DynamoDB wins on both cost and latency.
+
+Strands writes **one item per message** plus an agent record re-synced each turn — lots of tiny (sub-KB) reads and writes. The bill is dominated by *request count*, not bytes stored, and that's where the two services price very differently:
+
+| | S3 Standard | DynamoDB on-demand |
+|---|---|---|
+| Write | ~$5.00 / million PUT (any size) | ~$1.25 / million WRU (per 1 KB) |
+| Read | ~$0.40 / million GET (per object) | ~$0.25 / million RRU (per 4 KB) |
+| Free tier | none | 25 WCU + 25 RCU + 25 GB, perpetual |
+| Latency | tens of ms | single-digit ms |
+
+Two structural advantages for small items:
+
+- **Writes:** S3 charges per request regardless of size — a 200-byte message costs the same PUT as a 4 MB one. DynamoDB bills per KB, so tiny messages hit the cheapest unit *and* the per-unit price is ~4× lower.
+- **Reads:** `list_messages` is **one Query** in DynamoDB, and one RRU covers 4 KB — so several small messages per RRU. In S3 it's **one GET per message object**. Batching crushes the per-item read cost.
+
+For a workload of ~1M small message-writes/month with periodic restores, this is roughly a **3–4× lower bill** on DynamoDB — and often **free** under DynamoDB's perpetual free tier, which S3 has no equivalent of. Add native **TTL** for automatic session expiry and single-digit-ms access, and DynamoDB is the better default for hot session/agent-state storage.
+
+**When S3 still wins:** very large message payloads (big tool results, images) that approach or exceed DynamoDB's 400 KB item limit, or cold/archival sessions rarely read (S3 storage is ~10× cheaper per GB). A robust production setup is DynamoDB for the session/message records + S3 overflow only for oversized blobs.
+
+## Installation
+
+```bash
+pip install strands-session-dynamodb
+# or, via the family's extra:
+pip install "strands-agents-session[dynamodb]"
+```
+
+**Requires Python 3.10+.**
+
+## Quick start
+
+```python
+from strands import Agent
+from strands_session_dynamodb import DynamoDBSessionManager
+
+session_manager = DynamoDBSessionManager(
+    session_id="user-123",
+    table_name="strands-sessions",
+    region_name="us-east-1",
+)
+
+agent = Agent(session_manager=session_manager)
+
+agent("Hi, I'm Kamal")
+agent("What's my name?")   # remembers within the session
+```
+
+Next run, same `session_id` → the agent restores its full history and state from DynamoDB. The table is created automatically (on-demand billing) if it does not exist.
+
+## API
+
+### `DynamoDBSessionManager(session_id, table_name, *, region_name=None, boto_session=None, boto_client_config=None, endpoint_url=None, ttl_seconds=None)`
+
+| Parameter | Description |
+|---|---|
+| `session_id` | Session identifier |
+| `table_name` | DynamoDB table (auto-created if absent) |
+| `region_name` | AWS region |
+| `boto_session` | Optional pre-built `boto3.Session` |
+| `boto_client_config` | Optional `botocore` client config |
+| `endpoint_url` | Custom endpoint (e.g. DynamoDB Local / LocalStack) |
+| `ttl_seconds` | If set, writes a `ttl` epoch attribute and enables table TTL for automatic session expiry |
+
+## AWS setup
+
+Standard AWS credential resolution (env vars, `~/.aws/credentials`, profile, or IAM role). The credentials need permission to create the table (if absent) and read/write items.
+
+## Data model
+
+Single table, both keys strings:
+
+| Item | PK | SK |
+|---|---|---|
+| Session | `SESSION#<session_id>` | `META` |
+| Agent | `SESSION#<session_id>` | `AGENT#<agent_id>` |
+| Message | `SESSION#<session_id>#AGENT#<agent_id>` | `MSG#<zero-padded id>` |
+
+Messages live in a per-agent partition with a zero-padded, lexically ordered sort key, so `list_messages(offset, limit)` is a native range Query — matching the `removed_message_count` offset semantics Strands relies on. Payloads are stored as a JSON string.
+
+> **Item-size note:** DynamoDB items are capped at 400 KB. A single message with a very large payload (e.g. big tool results / images) could exceed that; S3 has no such limit. For such workloads, keep large blobs in S3 and reference them.
+
+## License
+
+MIT

strands_session_dynamodb-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "strands_session_dynamodb"
+version = "0.1.0"
+description = "Amazon DynamoDB session manager (storage backend) for Strands Agents — persists sessions, agent state, and messages"
+authors = [{name = "Kamal", email = "skamalj@github.com"}]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "strands-agents-session>=0.1.0",
+    "strands-agents",
+    "boto3",
+]
+keywords = [
+    "strands", "strands-agents", "session", "dynamodb", "aws",
+    "agent-state", "memory", "persistence",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://github.com/skamalj/strands-agents-session"
+Repository = "https://github.com/skamalj/strands-agents-session.git"
+
+[dependency-groups]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+    "strands-agents[openai]",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/strands_session_dynamodb"]

strands_session_dynamodb-0.1.0/src/strands_session_dynamodb/__init__.py

@@ -0,0 +1,5 @@
+"""Amazon DynamoDB session manager for Strands Agents."""
+
+from .session_manager import DynamoDBSessionManager, DynamoDBSessionStorage
+
+__all__ = ["DynamoDBSessionManager", "DynamoDBSessionStorage"]

strands_session_dynamodb-0.1.0/src/strands_session_dynamodb/session_manager.py

@@ -0,0 +1,173 @@
+"""Amazon DynamoDB session backend for Strands Agents.
+
+Provides a ``DynamoDBSessionStorage`` (implementing the ``SessionStorage``
+interface from ``strands-agents-session``) and a thin ``DynamoDBSessionManager``
+that wires it into ``KeyValueSessionManager``. All the session-repository logic
+lives in the base package; this module is just the storage layer.
+
+Single DynamoDB table, both keys strings (``PK`` HASH, ``SK`` RANGE). Payloads
+are stored as a JSON string in a ``data`` attribute, which sidesteps DynamoDB's
+float/empty-value quirks.
+"""
+
+import time
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+import boto3
+from boto3.dynamodb.conditions import Key
+from botocore.exceptions import ClientError
+
+from strands_agents_session import KeyValueSessionManager, SessionStorage
+
+if TYPE_CHECKING:  # pragma: no cover
+    from botocore.config import Config as BotocoreConfig
+
+
+class DynamoDBSessionStorage(SessionStorage):
+    """DynamoDB implementation of the session ``SessionStorage`` interface."""
+
+    def __init__(
+        self,
+        table_name: str,
+        *,
+        boto_session: "boto3.Session | None" = None,
+        boto_client_config: "BotocoreConfig | None" = None,
+        region_name: str | None = None,
+        endpoint_url: str | None = None,
+        ttl_seconds: int | None = None,
+    ) -> None:
+        session = boto_session or boto3.Session(region_name=region_name)
+        self.dynamodb = session.resource(
+            "dynamodb", endpoint_url=endpoint_url, config=boto_client_config
+        )
+        self.client = session.client(
+            "dynamodb", endpoint_url=endpoint_url, config=boto_client_config
+        )
+        self.table_name = table_name
+        self.ttl_seconds = ttl_seconds
+        self.table = self._get_or_create_table(table_name)
+
+    def _get_or_create_table(self, table_name: str):
+        table = self.dynamodb.Table(table_name)
+        try:
+            table.load()
+            return table
+        except ClientError as e:
+            if e.response["Error"]["Code"] != "ResourceNotFoundException":
+                raise
+        table = self.dynamodb.create_table(
+            TableName=table_name,
+            KeySchema=[
+                {"AttributeName": "PK", "KeyType": "HASH"},
+                {"AttributeName": "SK", "KeyType": "RANGE"},
+            ],
+            AttributeDefinitions=[
+                {"AttributeName": "PK", "AttributeType": "S"},
+                {"AttributeName": "SK", "AttributeType": "S"},
+            ],
+            BillingMode="PAY_PER_REQUEST",
+        )
+        table.wait_until_exists()
+        if self.ttl_seconds:
+            try:
+                self.client.update_time_to_live(
+                    TableName=table_name,
+                    TimeToLiveSpecification={"Enabled": True, "AttributeName": "ttl"},
+                )
+            except ClientError:  # pragma: no cover
+                pass
+        return table
+
+    # SessionStorage ----------------------------------------------------
+
+    def put(self, item: Dict[str, Any]) -> None:
+        ddb_item = {"PK": item["pk"], "SK": item["sk"], "data": item["data"]}
+        if self.ttl_seconds:
+            ddb_item["ttl"] = int(time.time()) + self.ttl_seconds
+        self.table.put_item(Item=ddb_item)
+
+    def get(self, pk: str, sk: str) -> Optional[Dict[str, Any]]:
+        item = self.table.get_item(Key={"PK": pk, "SK": sk}).get("Item")
+        if not item:
+            return None
+        return {"pk": item["PK"], "sk": item["SK"], "data": item["data"]}
+
+    def query(
+        self, pk: str, sk_gte: Optional[str] = None, limit: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
+        condition = Key("PK").eq(pk)
+        if sk_gte is not None:
+            condition = condition & Key("SK").gte(sk_gte)
+
+        items: List[dict] = []
+        start_key = None
+        while True:
+            query_kwargs: Dict[str, Any] = {
+                "KeyConditionExpression": condition,
+                "ScanIndexForward": True,
+            }
+            if start_key is not None:
+                query_kwargs["ExclusiveStartKey"] = start_key
+            if limit is not None:
+                query_kwargs["Limit"] = limit - len(items)
+            resp = self.table.query(**query_kwargs)
+            items.extend(resp.get("Items", []))
+            start_key = resp.get("LastEvaluatedKey")
+            if limit is not None and len(items) >= limit:
+                items = items[:limit]
+                break
+            if not start_key:
+                break
+
+        return [{"pk": i["PK"], "sk": i["SK"], "data": i["data"]} for i in items]
+
+    def delete(self, pk: str, sk: str) -> None:
+        self.table.delete_item(Key={"PK": pk, "SK": sk})
+
+    def delete_partition(self, pk: str) -> None:
+        start_key = None
+        while True:
+            query_kwargs: Dict[str, Any] = {"KeyConditionExpression": Key("PK").eq(pk)}
+            if start_key is not None:
+                query_kwargs["ExclusiveStartKey"] = start_key
+            resp = self.table.query(**query_kwargs)
+            items = resp.get("Items", [])
+            with self.table.batch_writer() as batch:
+                for i in items:
+                    batch.delete_item(Key={"PK": i["PK"], "SK": i["SK"]})
+            start_key = resp.get("LastEvaluatedKey")
+            if not start_key:
+                break
+
+
+class DynamoDBSessionManager(KeyValueSessionManager):
+    """DynamoDB-backed session manager for Strands Agents.
+
+        agent = Agent(session_manager=DynamoDBSessionManager(
+            session_id="user-123", table_name="strands-sessions",
+        ))
+
+    The table is created automatically (on-demand billing) if it does not exist.
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        table_name: str,
+        *,
+        boto_session: "boto3.Session | None" = None,
+        boto_client_config: "BotocoreConfig | None" = None,
+        region_name: str | None = None,
+        endpoint_url: str | None = None,
+        ttl_seconds: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        storage = DynamoDBSessionStorage(
+            table_name,
+            boto_session=boto_session,
+            boto_client_config=boto_client_config,
+            region_name=region_name,
+            endpoint_url=endpoint_url,
+            ttl_seconds=ttl_seconds,
+        )
+        super().__init__(session_id=session_id, storage=storage)

strands_session_dynamodb-0.1.0/tests/test_agent_llm.py

@@ -0,0 +1,81 @@
+"""
+End-to-end tests: a real Strands Agent (OpenAI gpt-4o-mini) persisting to real
+DynamoDB via DynamoDBSessionManager, then restoring in a fresh manager.
+
+Requires:
+  - AWS credentials (AWS_PROFILE / keys) + region
+  - OPENAI_API_KEY
+"""
+import os
+import uuid
+
+import pytest
+
+from strands import Agent
+from strands.models.openai import OpenAIModel
+
+from strands_session_dynamodb import DynamoDBSessionManager
+
+TABLE = os.environ.get("STRANDS_DDB_TABLE", "strands_sessions_test")
+OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY")
+
+pytestmark = pytest.mark.skipif(not OPENAI_API_KEY, reason="OPENAI_API_KEY not set")
+
+
+def make_model():
+    return OpenAIModel(
+        client_args={"api_key": OPENAI_API_KEY},
+        model_id="gpt-4o-mini",
+        params={"temperature": 0},
+    )
+
+
+def text_of(result):
+    try:
+        return " ".join(
+            b.get("text", "") for b in result.message["content"] if isinstance(b, dict)
+        )
+    except Exception:
+        return str(result)
+
+
+def test_conversation_persists_and_restores_across_managers():
+    session_id = f"llm-{uuid.uuid4()}"
+
+    # First manager/agent: introduce a fact.
+    m1 = DynamoDBSessionManager(session_id=session_id, table_name=TABLE)
+    a1 = Agent(model=make_model(), agent_id="assistant", session_manager=m1)
+    a1("Hi, my name is Kamal and I live in Pune.")
+
+    # Fresh manager + agent bound to the SAME session — must restore history.
+    m2 = DynamoDBSessionManager(session_id=session_id, table_name=TABLE)
+    a2 = Agent(model=make_model(), agent_id="assistant", session_manager=m2)
+    reply = text_of(a2("What is my name?"))
+
+    assert "kamal" in reply.lower(), f"expected restored recall of 'kamal', got: {reply}"
+
+
+def test_messages_written_to_repository():
+    session_id = f"llm-{uuid.uuid4()}"
+    m1 = DynamoDBSessionManager(session_id=session_id, table_name=TABLE)
+    a1 = Agent(model=make_model(), agent_id="assistant", session_manager=m1)
+    a1("Say hello in one word.")
+
+    # user turn + assistant turn should both be persisted, in order
+    msgs = m1.list_messages(session_id, "assistant")
+    assert len(msgs) >= 2
+    assert [mm.message_id for mm in msgs] == sorted(mm.message_id for mm in msgs)
+    assert msgs[0].message["role"] == "user"
+
+
+def test_agent_record_persisted():
+    session_id = f"llm-{uuid.uuid4()}"
+    m1 = DynamoDBSessionManager(session_id=session_id, table_name=TABLE)
+    a1 = Agent(model=make_model(), agent_id="assistant", session_manager=m1)
+    a1("Hello there.")
+
+    # The agent record (state + conversation-manager state) must be persisted.
+    got = m1.read_agent(session_id, "assistant")
+    assert got is not None
+    assert got.agent_id == "assistant"
+    assert isinstance(got.conversation_manager_state, dict)

strands_session_dynamodb-0.1.0/tests/test_repository.py

@@ -0,0 +1,196 @@
+"""
+Comprehensive repository tests for DynamoDBSessionManager against real DynamoDB.
+
+Deterministic (no LLM): exercises the SessionRepository CRUD surface directly —
+sessions, agents (with agent state), messages, pagination, updates/redaction,
+and isolation.
+
+Requires AWS credentials (AWS_PROFILE / keys) + region with DynamoDB access.
+The table is auto-created on first use.
+"""
+import os
+import uuid
+
+import pytest
+
+from strands.types.exceptions import SessionException
+from strands.types.session import SessionAgent, SessionMessage
+from strands_session_dynamodb import DynamoDBSessionManager
+
+TABLE = os.environ.get("STRANDS_DDB_TABLE", "strands_sessions_test")
+
+
+def make_manager(session_id=None):
+    return DynamoDBSessionManager(
+        session_id=session_id or f"sess-{uuid.uuid4()}", table_name=TABLE
+    )
+
+
+def msg(i, role="user", text=None):
+    return SessionMessage.from_message(
+        {"role": role, "content": [{"text": text or f"m{i}"}]}, i
+    )
+
+
+# ---------------------------------------------------------------------------
+# Sessions
+# ---------------------------------------------------------------------------
+
+def test_session_created_on_init():
+    mgr = make_manager()
+    got = mgr.read_session(mgr.session_id)
+    assert got is not None
+    assert got.session_id == mgr.session_id
+
+
+def test_create_duplicate_session_raises():
+    mgr = make_manager()
+    with pytest.raises(SessionException):
+        mgr.create_session(mgr.session)
+
+
+def test_read_missing_session_returns_none():
+    mgr = make_manager()
+    assert mgr.read_session(f"nope-{uuid.uuid4()}") is None
+
+
+def test_delete_session_removes_everything():
+    mgr = make_manager()
+    sid = mgr.session_id
+    mgr.create_agent(sid, SessionAgent(agent_id="a1", state={}, conversation_manager_state={}))
+    mgr.create_message(sid, "a1", msg(0))
+    mgr.delete_session(sid)
+    assert mgr.read_session(sid) is None
+    assert mgr.read_agent(sid, "a1") is None
+    assert mgr.list_messages(sid, "a1") == []
+
+
+# ---------------------------------------------------------------------------
+# Agents (incl. agent state)
+# ---------------------------------------------------------------------------
+
+def test_agent_state_round_trip():
+    mgr = make_manager()
+    sid = mgr.session_id
+    agent = SessionAgent(
+        agent_id="assistant",
+        state={"user_tier": "gold", "lang": "en"},
+        conversation_manager_state={"removed_message_count": 0},
+    )
+    mgr.create_agent(sid, agent)
+
+    got = mgr.read_agent(sid, "assistant")
+    assert got is not None
+    assert got.state == {"user_tier": "gold", "lang": "en"}
+    assert got.conversation_manager_state == {"removed_message_count": 0}
+
+
+def test_read_missing_agent_returns_none():
+    mgr = make_manager()
+    assert mgr.read_agent(mgr.session_id, "ghost") is None
+
+
+def test_update_agent_preserves_created_at_and_updates_state():
+    mgr = make_manager()
+    sid = mgr.session_id
+    agent = SessionAgent(agent_id="a1", state={"v": 1}, conversation_manager_state={})
+    mgr.create_agent(sid, agent)
+    created_at = mgr.read_agent(sid, "a1").created_at
+
+    updated = SessionAgent(agent_id="a1", state={"v": 2}, conversation_manager_state={})
+    mgr.update_agent(sid, updated)
+
+    got = mgr.read_agent(sid, "a1")
+    assert got.state == {"v": 2}
+    assert got.created_at == created_at  # creation timestamp preserved
+
+
+def test_update_missing_agent_raises():
+    mgr = make_manager()
+    with pytest.raises(SessionException):
+        mgr.update_agent(mgr.session_id, SessionAgent(agent_id="x", state={}, conversation_manager_state={}))
+
+
+# ---------------------------------------------------------------------------
+# Messages + pagination
+# ---------------------------------------------------------------------------
+
+def test_message_round_trip():
+    mgr = make_manager()
+    sid = mgr.session_id
+    mgr.create_agent(sid, SessionAgent(agent_id="a1", state={}, conversation_manager_state={}))
+    mgr.create_message(sid, "a1", msg(0, text="hello"))
+
+    got = mgr.read_message(sid, "a1", 0)
+    assert got is not None
+    assert got.message_id == 0
+    assert got.message["content"][0]["text"] == "hello"
+
+
+def test_list_messages_sorted_by_id():
+    mgr = make_manager()
+    sid = mgr.session_id
+    mgr.create_agent(sid, SessionAgent(agent_id="a1", state={}, conversation_manager_state={}))
+    # insert out of order
+    for i in [2, 0, 4, 1, 3]:
+        mgr.create_message(sid, "a1", msg(i))
+    got = mgr.list_messages(sid, "a1")
+    assert [m.message_id for m in got] == [0, 1, 2, 3, 4]
+
+
+def test_list_messages_offset():
+    mgr = make_manager()
+    sid = mgr.session_id
+    mgr.create_agent(sid, SessionAgent(agent_id="a1", state={}, conversation_manager_state={}))
+    for i in range(6):
+        mgr.create_message(sid, "a1", msg(i))
+    got = mgr.list_messages(sid, "a1", offset=2)
+    assert [m.message_id for m in got] == [2, 3, 4, 5]
+
+
+def test_list_messages_limit():
+    mgr = make_manager()
+    sid = mgr.session_id
+    mgr.create_agent(sid, SessionAgent(agent_id="a1", state={}, conversation_manager_state={}))
+    for i in range(6):
+        mgr.create_message(sid, "a1", msg(i))
+    got = mgr.list_messages(sid, "a1", limit=3)
+    assert [m.message_id for m in got] == [0, 1, 2]
+
+
+def test_list_messages_offset_and_limit():
+    mgr = make_manager()
+    sid = mgr.session_id
+    mgr.create_agent(sid, SessionAgent(agent_id="a1", state={}, conversation_manager_state={}))
+    for i in range(10):
+        mgr.create_message(sid, "a1", msg(i))
+    got = mgr.list_messages(sid, "a1", offset=3, limit=4)
+    assert [m.message_id for m in got] == [3, 4, 5, 6]
+
+
+def test_update_message_redaction():
+    mgr = make_manager()
+    sid = mgr.session_id
+    mgr.create_agent(sid, SessionAgent(agent_id="a1", state={}, conversation_manager_state={}))
+    original = msg(0, text="secret 4271")
+    mgr.create_message(sid, "a1", original)
+
+    original.redact_message = {"role": "user", "content": [{"text": "[REDACTED]"}]}
+    mgr.update_message(sid, "a1", original)
+
+    got = mgr.read_message(sid, "a1", 0)
+    assert got.redact_message is not None
+    assert got.redact_message["content"][0]["text"] == "[REDACTED]"
+
+
+# ---------------------------------------------------------------------------
+# Isolation
+# ---------------------------------------------------------------------------
+
+def test_sessions_isolated():
+    m1 = make_manager()
+    m2 = make_manager()
+    m1.create_agent(m1.session_id, SessionAgent(agent_id="a", state={"who": "one"}, conversation_manager_state={}))
+    m2.create_agent(m2.session_id, SessionAgent(agent_id="a", state={"who": "two"}, conversation_manager_state={}))
+    assert m1.read_agent(m1.session_id, "a").state == {"who": "one"}
+    assert m2.read_agent(m2.session_id, "a").state == {"who": "two"}