citadeldb-strands-agents 2.0.0__tar.gz

citadeldb_strands_agents-2.0.0/.gitignore

@@ -0,0 +1,18 @@
+/target
+**/*.rs.bk
+*.swp
+*.swo
+*~
+.DS_Store
+site/public/
+site/static/wasm/*.wasm
+site/static/wasm/*.js
+/notes/
+__pycache__/
+*.py[cod]
+# maturin build output; the .pyd is caught by the line above only by accident.
+*.pdb
+.pytest_cache/
+.mypy_cache/
+/dist/
+packaging/*/dist/

citadeldb_strands_agents-2.0.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.5
+Name: citadeldb-strands-agents
+Version: 2.0.0
+Summary: Strands Agents session storage backed by Citadel: encrypted at rest, with deletes that destroy the key
+Project-URL: Homepage, https://citadeldb.dev
+Project-URL: Repository, https://github.com/yp3y5akh0v/citadel
+Author: Yuriy Peysakhov
+License-Expression: Apache-2.0
+Keywords: agents,encryption,memory,session,strands,strands-agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: citadeldb<3,>=2.0
+Requires-Dist: strands-agents<2,>=1.0
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# citadeldb-strands-agents
+
+A [Strands Agents](https://strandsagents.com/) session manager backed by
+[Citadel](https://citadeldb.dev). Encrypted at rest, embedded in your process, and
+redaction that removes the redacted content rather than annotating it.
+
+```
+pip install citadeldb-strands-agents
+```
+
+```python
+from strands import Agent
+from citadeldb_strands_agents import CitadelSessionManager
+
+sessions = CitadelSessionManager("user-123", "sessions.cdl", key="your-passphrase")
+agent = Agent(session_manager=sessions)
+```
+
+Built the way the shipped managers are: it implements `SessionRepository` and inherits
+`RepositorySessionManager`, exactly as `FileSessionManager` and `S3SessionManager` do.
+
+## Redaction actually redacts
+
+Strands redacts by setting a `redact_message` field beside the original and updating the
+record:
+
+```python
+# from strands RepositorySessionManager.redact_latest_message
+latest_agent_message.redact_message = redact_message
+return self.session_repository.update_message(...)
+```
+
+The original `message` stays in the record. Strands reads a redacted message through
+`to_message()`, which returns the redaction, so the original is never read again. This
+manager therefore does not keep it: the superseded record's key is destroyed and the
+replacement carries the redaction in place of the original.
+
+```python
+after = sessions.read_message("user-123", agent.agent_id, 0)
+after.to_message()      # {'content': [{'text': '[REDACTED]'}], 'role': 'user'}
+after.message           # the redaction, not the original
+```
+
+An ordinary update is unaffected: only a message carrying a redaction drops its original.
+
+## Erasure
+
+```python
+sessions.forget_session("user-123")   # returns the number of records erased
+```
+
+Strands has no delete in its repository protocol. This destroys the session, its agents
+and every message key.
+
+## Notes
+
+Messages are ordered by their conversation index rather than write time, so editing an
+earlier turn does not move it to the end of the history.
+
+Citadel is embedded and one process owns the file. A path already open on this thread,
+under the same passphrase, is shared, so many sessions and other Citadel adapters can share
+one database; construct them on the same thread.
+
+## License
+
+Apache-2.0

citadeldb_strands_agents-2.0.0/README.md

@@ -0,0 +1,66 @@
+# citadeldb-strands-agents
+
+A [Strands Agents](https://strandsagents.com/) session manager backed by
+[Citadel](https://citadeldb.dev). Encrypted at rest, embedded in your process, and
+redaction that removes the redacted content rather than annotating it.
+
+```
+pip install citadeldb-strands-agents
+```
+
+```python
+from strands import Agent
+from citadeldb_strands_agents import CitadelSessionManager
+
+sessions = CitadelSessionManager("user-123", "sessions.cdl", key="your-passphrase")
+agent = Agent(session_manager=sessions)
+```
+
+Built the way the shipped managers are: it implements `SessionRepository` and inherits
+`RepositorySessionManager`, exactly as `FileSessionManager` and `S3SessionManager` do.
+
+## Redaction actually redacts
+
+Strands redacts by setting a `redact_message` field beside the original and updating the
+record:
+
+```python
+# from strands RepositorySessionManager.redact_latest_message
+latest_agent_message.redact_message = redact_message
+return self.session_repository.update_message(...)
+```
+
+The original `message` stays in the record. Strands reads a redacted message through
+`to_message()`, which returns the redaction, so the original is never read again. This
+manager therefore does not keep it: the superseded record's key is destroyed and the
+replacement carries the redaction in place of the original.
+
+```python
+after = sessions.read_message("user-123", agent.agent_id, 0)
+after.to_message()      # {'content': [{'text': '[REDACTED]'}], 'role': 'user'}
+after.message           # the redaction, not the original
+```
+
+An ordinary update is unaffected: only a message carrying a redaction drops its original.
+
+## Erasure
+
+```python
+sessions.forget_session("user-123")   # returns the number of records erased
+```
+
+Strands has no delete in its repository protocol. This destroys the session, its agents
+and every message key.
+
+## Notes
+
+Messages are ordered by their conversation index rather than write time, so editing an
+earlier turn does not move it to the end of the history.
+
+Citadel is embedded and one process owns the file. A path already open on this thread,
+under the same passphrase, is shared, so many sessions and other Citadel adapters can share
+one database; construct them on the same thread.
+
+## License
+
+Apache-2.0

citadeldb_strands_agents-2.0.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+# Bare "strands" is an unrelated package on PyPI.
+name = "citadeldb-strands-agents"
+dynamic = ["version"]
+description = "Strands Agents session storage backed by Citadel: encrypted at rest, with deletes that destroy the key"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "Yuriy Peysakhov" }]
+keywords = ["strands", "strands-agents", "agents", "session", "memory", "encryption"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Database",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+# A record replaces under its own id, which needs the keyed write added in 2.0.
+dependencies = ["citadeldb>=2.0,<3", "strands-agents>=1.0,<2"]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://citadeldb.dev"
+Repository = "https://github.com/yp3y5akh0v/citadel"
+
+# The version comes from the release tag, so there is nothing to bump.
+[tool.hatch.version]
+source = "vcs"
+raw-options = { root = "../..", tag_regex = '^v(?P<version>\d+\.\d+\.\d+)$' }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/citadeldb_strands_agents"]

citadeldb_strands_agents-2.0.0/src/citadeldb_strands_agents/__init__.py

@@ -0,0 +1,13 @@
+"""Strands Agents session storage backed by Citadel, encrypted at rest."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .session import CitadelSessionManager
+
+__all__ = ["CitadelSessionManager", "__version__"]
+
+
+try:
+    __version__ = version("citadeldb-strands-agents")
+except PackageNotFoundError:  # running from a source tree, never installed
+    __version__ = "0+unknown"

citadeldb_strands_agents-2.0.0/src/citadeldb_strands_agents/session.py

@@ -0,0 +1,332 @@
+"""Strands Agents session store on an encrypted Citadel region."""
+from __future__ import annotations
+
+from typing import Any
+
+import citadeldb
+from strands.session.repository_session_manager import RepositorySessionManager
+from strands.session.session_repository import SessionRepository
+from strands.types.exceptions import SessionException
+from strands.types.session import (
+    Session,
+    SessionAgent,
+    SessionMessage,
+    encode_bytes_values,
+)
+
+SESSION_KIND = "session"
+AGENT_KIND = "agent"
+MESSAGE_KIND = "message"
+MULTI_AGENT_KIND = "multi_agent"
+DEFAULT_PATH = "strands_sessions.cdl"
+DEFAULT_REGION = "strands_sessions"
+PAGE = 10_000
+
+
+def _page(mem: Any, region: str, kind: str, criterion: dict[str, Any]) -> list[Any]:
+    """Page to the end: one fetch is bounded, and a partial erase must not look whole."""
+    out: list[Any] = []
+    after = None
+    while True:
+        got = mem.fetch(region, kind, payload_filter=criterion, limit=PAGE, after_id=after)
+        out.extend(got)
+        if len(got) < PAGE:
+            return out
+        after = got[-1].id
+
+
+# Memory holds no database reference, so no handle is pinned to a thread.
+
+
+def _one(mem: Any, region: str, kind: str, criterion: dict[str, Any]):
+    hits = mem.fetch(region, kind, payload_filter=criterion, limit=1)
+    return hits[0] if hits else None
+
+
+def _key(*parts: Any) -> str:
+    """One engine key from several names, length-prefixed so that no two name
+    tuples can spell the same key."""
+    return "".join(f"{len(s)}\x1f{s}" for s in (str(p) for p in parts))
+
+
+def _put(mem: Any, region: str, atom: dict, key: str) -> None:
+    """Store `atom` as the sole occupant of `key`. Every reference repository
+    keys its records - a file per message, an object per key - so a second write
+    replaces the first rather than standing beside it, and two request handlers
+    sharing a store cannot each add a copy."""
+    mem.remember_replacing_keyed(region, atom, key)
+
+
+def _persisted(session_message: SessionMessage) -> dict:
+    """The record to store; a redaction replaces the original message."""
+    data = session_message.to_dict()
+    if session_message.redact_message is not None:
+        # to_dict() runs the bytes encoder over the whole record, so the
+        # replacement has to go through it too. Assigning it raw sends live
+        # Python bytes to the engine whenever a redaction carries an image or
+        # a document block.
+        data["message"] = encode_bytes_values(session_message.redact_message)
+    return data
+
+
+def _text_of(session_message: SessionMessage) -> str:
+    """An atom needs text to embed; the index identifies it otherwise."""
+    content = session_message.redact_message or session_message.message
+    parts = content.get("content") or [] if isinstance(content, dict) else []
+    text = " ".join(
+        p["text"] for p in parts if isinstance(p, dict) and isinstance(p.get("text"), str)
+    )
+    return text or f"message {session_message.message_id}"
+
+
+class CitadelSessionManager(RepositorySessionManager, SessionRepository):
+    """A Strands SessionRepository backed by one encrypted Citadel region."""
+
+    def __init__(
+        self,
+        session_id: str,
+        path: str = DEFAULT_PATH,
+        key: str = "",
+        *,
+        region: str = DEFAULT_REGION,
+        embedder: Any | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if not key:
+            raise ValueError("a passphrase is required: transcripts are the payload")
+        try:
+            self._db = citadeldb.connect(path, key=key, region_keys=True)
+        except citadeldb.OperationalError as e:
+            if "locked" not in str(e):
+                raise
+            raise RuntimeError(
+                f"{path} is open in another process. Citadel is embedded, so one "
+                f"process owns the file."
+            ) from e
+        self._mem = self._db.memory()
+        self._region = region
+        # Idempotent for a region of the same width, so a dim clash raises here.
+        self._mem.create_encrypted_region(
+            region, embedder or citadeldb.MockEmbedder(dim=64)
+        )
+
+        super().__init__(session_id=session_id, session_repository=self, **kwargs)
+
+    # ---- sessions ---------------------------------------------------------
+
+    def create_session(self, session: Session, **kwargs: Any) -> Session:
+        if _one(self._mem, self._region, SESSION_KIND, {"sid": session.session_id}):
+            raise SessionException(f"Session {session.session_id} already exists")
+        _put(
+            self._mem,
+            self._region,
+            {
+                "kind": SESSION_KIND,
+                "text": session.session_id,
+                "payload": {"sid": session.session_id, "session": session.to_dict()},
+            },
+            _key(session.session_id),
+        )
+        return session
+
+    def read_session(self, session_id: str, **kwargs: Any) -> Session | None:
+        hit = _one(self._mem, self._region, SESSION_KIND, {"sid": session_id})
+        return Session.from_dict(hit.payload["session"]) if hit else None
+
+    # ---- agents -----------------------------------------------------------
+
+    def create_agent(
+        self, session_id: str, session_agent: SessionAgent, **kwargs: Any
+    ) -> None:
+        _put(
+            self._mem,
+            self._region,
+            {
+                "kind": AGENT_KIND,
+                "text": session_agent.agent_id,
+                "payload": {
+                    "sid": session_id,
+                    "aid": session_agent.agent_id,
+                    "agent": session_agent.to_dict(),
+                },
+            },
+            _key(session_id, session_agent.agent_id),
+        )
+
+    def read_agent(
+        self, session_id: str, agent_id: str, **kwargs: Any
+    ) -> SessionAgent | None:
+        hit = _one(
+            self._mem, self._region, AGENT_KIND, {"sid": session_id, "aid": agent_id}
+        )
+        return SessionAgent.from_dict(hit.payload["agent"]) if hit else None
+
+    def update_agent(
+        self, session_id: str, session_agent: SessionAgent, **kwargs: Any
+    ) -> None:
+        agent_id = session_agent.agent_id
+        previous = self.read_agent(session_id, agent_id)
+        if previous is None:
+            raise SessionException(
+                f"Agent {agent_id} in session {session_id} does not exist"
+            )
+        # The reference carries the original creation time forward on update.
+        session_agent.created_at = previous.created_at
+        _put(
+            self._mem,
+            self._region,
+            {
+                "kind": AGENT_KIND,
+                "text": agent_id,
+                "payload": {
+                    "sid": session_id,
+                    "aid": agent_id,
+                    "agent": session_agent.to_dict(),
+                },
+            },
+            _key(session_id, agent_id),
+        )
+
+    # ---- messages ---------------------------------------------------------
+
+    def create_message(
+        self, session_id: str, agent_id: str, session_message: SessionMessage, **kwargs: Any
+    ) -> None:
+        _put(
+            self._mem,
+            self._region,
+            {
+                "kind": MESSAGE_KIND,
+                "text": _text_of(session_message),
+                "payload": {
+                    "sid": session_id,
+                    "aid": agent_id,
+                    "mid": session_message.message_id,
+                    "message": _persisted(session_message),
+                },
+            },
+            _key(session_id, agent_id, session_message.message_id),
+        )
+
+    def read_message(
+        self, session_id: str, agent_id: str, message_id: int, **kwargs: Any
+    ) -> SessionMessage | None:
+        hit = _one(
+            self._mem, self._region, MESSAGE_KIND,
+            {"sid": session_id, "aid": agent_id, "mid": message_id},
+        )
+        return SessionMessage.from_dict(hit.payload["message"]) if hit else None
+
+    def update_message(
+        self, session_id: str, agent_id: str, session_message: SessionMessage, **kwargs: Any
+    ) -> None:
+        message_id = session_message.message_id
+        previous = self.read_message(session_id, agent_id, message_id)
+        if previous is None:
+            raise SessionException(f"Message {message_id} does not exist")
+        session_message.created_at = previous.created_at
+        # A redaction lands here, so the superseded record's key is destroyed.
+        _put(
+            self._mem,
+            self._region,
+            {
+                "kind": MESSAGE_KIND,
+                "text": _text_of(session_message),
+                "payload": {
+                    "sid": session_id,
+                    "aid": agent_id,
+                    "mid": message_id,
+                    "message": _persisted(session_message),
+                },
+            },
+            _key(session_id, agent_id, message_id),
+        )
+
+    def list_messages(
+        self,
+        session_id: str,
+        agent_id: str,
+        limit: int | None = None,
+        offset: int = 0,
+        **kwargs: Any,
+    ) -> list[SessionMessage]:
+        hits = _page(self._mem, self._region, MESSAGE_KIND,
+                     {"sid": session_id, "aid": agent_id})
+        # The reference gates on the message container, which create_message
+        # makes: an agent with stored messages lists them whether or not an
+        # agent record was written first. Refusing on the record alone would
+        # hide writes this repository accepted.
+        if not hits and self.read_agent(session_id, agent_id) is None:
+            raise SessionException(
+                f"Messages missing from agent: {agent_id} in session {session_id}"
+            )
+        # Atom order follows write time and diverges once a message is updated.
+        ordered = sorted(hits, key=lambda h: h.payload["mid"])
+        window = ordered[offset : offset + limit] if limit is not None else ordered[offset:]
+        return [SessionMessage.from_dict(h.payload["message"]) for h in window]
+
+    # ---- multi-agent state ------------------------------------------------
+    # Base class raises NotImplementedError; a Swarm fails without these.
+
+    def create_multi_agent(
+        self, session_id: str, multi_agent: Any, **kwargs: Any
+    ) -> None:
+        _put(
+            self._mem,
+            self._region,
+            {
+                "kind": MULTI_AGENT_KIND,
+                "text": multi_agent.id,
+                "payload": {
+                    "sid": session_id,
+                    "maid": multi_agent.id,
+                    "state": multi_agent.serialize_state(),
+                },
+            },
+            _key(session_id, multi_agent.id),
+        )
+
+    def read_multi_agent(
+        self, session_id: str, multi_agent_id: str, **kwargs: Any
+    ) -> dict[str, Any] | None:
+        hit = _one(
+            self._mem, self._region, MULTI_AGENT_KIND,
+            {"sid": session_id, "maid": multi_agent_id},
+        )
+        return hit.payload["state"] if hit else None
+
+    def update_multi_agent(
+        self, session_id: str, multi_agent: Any, **kwargs: Any
+    ) -> None:
+        if self.read_multi_agent(session_id, multi_agent.id) is None:
+            raise SessionException(
+                f"MultiAgent state {multi_agent.id} in session {session_id} "
+                f"does not exist"
+            )
+        _put(
+            self._mem,
+            self._region,
+            {
+                "kind": MULTI_AGENT_KIND,
+                "text": multi_agent.id,
+                "payload": {
+                    "sid": session_id,
+                    "maid": multi_agent.id,
+                    "state": multi_agent.serialize_state(),
+                },
+            },
+            _key(session_id, multi_agent.id),
+        )
+
+    # ---- beyond the repository --------------------------------------------
+
+    def forget_session(self, session_id: str) -> int:
+        """Destroy a session's records, returning the number erased."""
+        doomed = [
+            h
+            for kind in (SESSION_KIND, AGENT_KIND, MESSAGE_KIND, MULTI_AGENT_KIND)
+            for h in _page(self._mem, self._region, kind, {"sid": session_id})
+        ]
+        if not doomed:
+            return 0
+        return self._mem.forget(self._region, [h.id for h in doomed]).erased_count

citadeldb_strands_agents-2.0.0/tests/test_multi_agent.py

@@ -0,0 +1,195 @@
+"""Multi-agent state and the manager paths the framework drives."""
+import os
+import tempfile
+
+import pytest
+from strands.session.file_session_manager import FileSessionManager
+from strands.types.exceptions import SessionException
+from strands.types.session import SessionAgent, SessionMessage
+
+from citadeldb_strands_agents import CitadelSessionManager
+
+SID, AID = "s1", "a1"
+
+
+def path(name="s.cdl"):
+    return os.path.join(tempfile.mkdtemp(), name)
+
+
+def mgr(p=None, session_id=SID):
+    return CitadelSessionManager(session_id, p or path(), "pw")
+
+
+def ref(session_id=SID):
+    return FileSessionManager(session_id, storage_dir=tempfile.mkdtemp())
+
+
+def msg(i, text="hello"):
+    return SessionMessage(
+        message={"role": "user", "content": [{"text": text}]}, message_id=i
+    )
+
+
+def agent(aid=AID):
+    return SessionAgent(agent_id=aid, state={}, conversation_manager_state={})
+
+
+class FakeMultiAgent:
+    """The shape RepositorySessionManager requires."""
+
+    def __init__(self, mid="swarm-1", state=None):
+        self.id = mid
+        self._state = state or {"nodes": ["a", "b"], "step": 1}
+
+    def serialize_state(self):
+        return dict(self._state)
+
+    def deserialize_state(self, state):
+        self._state = dict(state)
+
+
+# ---- multi-agent state: the base class raises without these --------------
+
+
+def test_multi_agent_state_round_trips():
+    m = mgr()
+    swarm = FakeMultiAgent()
+    m.create_multi_agent(SID, swarm)
+    assert m.read_multi_agent(SID, "swarm-1") == {"nodes": ["a", "b"], "step": 1}
+
+
+def test_reading_unknown_multi_agent_state_is_none_like_the_reference():
+    assert mgr().read_multi_agent(SID, "nope") is None
+    assert ref().read_multi_agent(SID, "nope") is None
+
+
+def test_updating_unknown_multi_agent_state_raises_like_the_reference():
+    m, r = mgr(), ref()
+    for store in (m, r):
+        with pytest.raises(SessionException, match="does not exist"):
+            store.update_multi_agent(SID, FakeMultiAgent("ghost"))
+
+
+def test_updating_multi_agent_state_does_not_duplicate():
+    m = mgr()
+    swarm = FakeMultiAgent()
+    m.create_multi_agent(SID, swarm)
+    for step in range(2, 6):
+        swarm._state["step"] = step
+        m.update_multi_agent(SID, swarm)
+    assert m.read_multi_agent(SID, "swarm-1")["step"] == 5
+
+
+def test_the_manager_hook_initializes_multi_agent_state():
+    """initialize_multi_agent creates on first sight and restores afterwards."""
+    p = path()
+    first = mgr(p)
+    swarm = FakeMultiAgent(state={"step": 7})
+    first.initialize_multi_agent(swarm)
+    first.sync_multi_agent(swarm)
+    del first
+
+    import gc
+
+    gc.collect()
+    again = CitadelSessionManager(SID, p, "pw")
+    restored = FakeMultiAgent(state={"step": 0})
+    again.initialize_multi_agent(restored)
+    assert restored._state["step"] == 7, "multi-agent state did not restore"
+
+
+def test_forget_session_also_destroys_multi_agent_state():
+    m = mgr()
+    m.create_multi_agent(SID, FakeMultiAgent())
+    m.forget_session(SID)
+    assert m.read_multi_agent(SID, "swarm-1") is None
+
+
+# ---- the path an Agent actually takes ------------------------------------
+
+
+def test_an_agent_restores_its_history_through_the_manager():
+    """initialize() is what Agent construction calls."""
+    from strands import Agent
+
+    p = path()
+    first = mgr(p)
+    a = Agent(agent_id=AID, session_manager=first, messages=[
+        {"role": "user", "content": [{"text": "remembered turn"}]}
+    ])
+    first.sync_agent(a)
+    del a, first
+
+    import gc
+
+    gc.collect()
+    again = CitadelSessionManager(SID, p, "pw")
+    restored = Agent(agent_id=AID, session_manager=again)
+    assert any(
+        "remembered turn" in str(m) for m in restored.messages
+    ), f"history did not restore: {restored.messages}"
+
+
+def test_agent_state_survives_a_restore():
+    from strands import Agent
+
+    p = path()
+    first = mgr(p)
+    a = Agent(agent_id=AID, session_manager=first)
+    a.state.set("locale", "en-GB")
+    first.sync_agent(a)
+    del a, first
+
+    import gc
+
+    gc.collect()
+    again = CitadelSessionManager(SID, p, "pw")
+    restored = Agent(agent_id=AID, session_manager=again)
+    assert restored.state.get("locale") == "en-GB"
+
+
+# ---- list_messages slice edges vs the reference --------------------------
+
+
+def seeded(store, n=4):
+    store.create_agent(SID, agent())
+    for i in range(n):
+        store.create_message(SID, AID, msg(i, f"turn {i}"))
+    return store
+
+
+def test_slice_edges_match_the_reference():
+    m, r = seeded(mgr()), seeded(ref())
+    for limit, offset in ((0, 0), (1, 0), (None, 0), (None, 10), (3, 2), (100, 1)):
+        ours = [x.message_id for x in m.list_messages(SID, AID, limit, offset)]
+        theirs = [x.message_id for x in r.list_messages(SID, AID, limit, offset)]
+        assert ours == theirs, (limit, offset, ours, theirs)
+
+
+def test_listing_an_agent_with_no_messages_is_empty_like_the_reference():
+    m, r = mgr(), ref()
+    for store in (m, r):
+        store.create_agent(SID, agent())
+        assert store.list_messages(SID, AID) == []
+
+
+# ---- an update that fails must not lose the record ----------------------
+
+
+def test_a_failed_update_leaves_the_original_readable():
+    """The write path erases before it writes; a failure must not orphan."""
+    m = seeded(mgr(), 2)
+    broken = msg(0, "replacement")
+    broken.message_id = 0
+
+    class Exploding(dict):
+        def __getitem__(self, k):
+            raise RuntimeError("boom")
+
+    # A message whose serialization explodes.
+    try:
+        m.update_message(SID, AID, msg(99))  # unknown id: raises before any erase
+    except SessionException:
+        pass
+    assert m.read_message(SID, AID, 0).message["content"][0]["text"] == "turn 0"
+    assert len(m.list_messages(SID, AID)) == 2

citadeldb_strands_agents-2.0.0/tests/test_session.py

@@ -0,0 +1,362 @@
+"""Tests for CitadelSessionManager, asserted against FileSessionManager."""
+import concurrent.futures as cf
+import gc
+import os
+import tempfile
+
+import pytest
+from strands.session.file_session_manager import FileSessionManager
+from strands.types.exceptions import SessionException
+from strands.types.session import Session, SessionAgent, SessionMessage, SessionType
+
+from citadeldb_strands_agents import CitadelSessionManager
+
+SID = "s1"
+AID = "a1"
+
+
+def path(name="s.cdl"):
+    return os.path.join(tempfile.mkdtemp(), name)
+
+
+def mgr(p=None, session_id=SID):
+    return CitadelSessionManager(session_id, p or path(), "pw")
+
+
+def ref(session_id=SID):
+    return FileSessionManager(session_id, storage_dir=tempfile.mkdtemp())
+
+
+def msg(i, text="hello"):
+    return SessionMessage(
+        message={"role": "user", "content": [{"text": text}]}, message_id=i
+    )
+
+
+def agent(aid=AID):
+    return SessionAgent(agent_id=aid, state={}, conversation_manager_state={})
+
+
+def seeded(m, n=3):
+    """A session with an agent and n messages."""
+    m.create_agent(SID, agent())
+    for i in range(n):
+        m.create_message(SID, AID, msg(i, f"turn {i}"))
+    return m
+
+
+# ---- construction mirrors the shipped managers ---------------------------
+
+
+def test_it_is_both_a_repository_and_a_manager():
+    from strands.session.session_manager import SessionManager
+    from strands.session.session_repository import SessionRepository
+
+    m = mgr()
+    assert isinstance(m, SessionRepository)
+    assert isinstance(m, SessionManager)
+
+
+def test_constructing_it_creates_the_session_like_the_reference():
+    """RepositorySessionManager creates the session on construction."""
+    assert mgr().read_session(SID) is not None
+    assert ref().read_session(SID) is not None
+
+
+def test_a_passphrase_is_required():
+    with pytest.raises(ValueError, match="passphrase"):
+        CitadelSessionManager(SID, path(), "")
+
+
+# ---- session / agent / message contracts vs the reference ----------------
+
+
+def test_creating_a_duplicate_session_raises_like_the_reference():
+    m, r = mgr(), ref()
+    dup = Session(session_id=SID, session_type=SessionType.AGENT)
+    for store in (m, r):
+        with pytest.raises(SessionException, match="already exists"):
+            store.create_session(dup)
+
+
+def test_reading_an_unknown_session_is_none_like_the_reference():
+    assert mgr().read_session("nope") is None
+    assert ref().read_session("nope") is None
+
+
+def test_reading_an_unknown_agent_is_none_like_the_reference():
+    assert mgr().read_agent(SID, "nope") is None
+    assert ref().read_agent(SID, "nope") is None
+
+
+def test_updating_an_unknown_agent_raises_like_the_reference():
+    m, r = mgr(), ref()
+    for store in (m, r):
+        with pytest.raises(SessionException, match="does not exist"):
+            store.update_agent(SID, agent("ghost"))
+
+
+def test_reading_an_unknown_message_is_none_like_the_reference():
+    m, r = seeded(mgr()), seeded(ref())
+    assert m.read_message(SID, AID, 99) is None
+    assert r.read_message(SID, AID, 99) is None
+
+
+def test_updating_an_unknown_message_raises_like_the_reference():
+    m, r = seeded(mgr()), seeded(ref())
+    for store in (m, r):
+        with pytest.raises(SessionException, match="does not exist"):
+            store.update_message(SID, AID, msg(99))
+
+
+def test_listing_messages_for_an_unknown_agent_raises_like_the_reference():
+    m, r = mgr(), ref()
+    for store in (m, r):
+        with pytest.raises(SessionException):
+            store.list_messages(SID, "ghost")
+
+
+# ---- ordering and pagination --------------------------------------------
+
+
+def test_messages_come_back_in_conversation_order():
+    m = seeded(mgr(), 5)
+    assert [x.message_id for x in m.list_messages(SID, AID)] == [0, 1, 2, 3, 4]
+
+
+def test_order_follows_the_index_not_the_write_time():
+    """Updating an early message must not move it to the end."""
+    m = seeded(mgr(), 5)
+    m.update_message(SID, AID, msg(1, "edited"))
+    assert [x.message_id for x in m.list_messages(SID, AID)] == [0, 1, 2, 3, 4]
+
+
+def test_pagination_matches_the_reference():
+    m, r = seeded(mgr(), 6), seeded(ref(), 6)
+    for limit, offset in ((2, 0), (2, 2), (None, 3), (10, 0), (2, 99)):
+        ours = [x.message_id for x in m.list_messages(SID, AID, limit, offset)]
+        theirs = [x.message_id for x in r.list_messages(SID, AID, limit, offset)]
+        assert ours == theirs, (limit, offset, ours, theirs)
+
+
+# ---- no duplicates on repeat writes -------------------------------------
+
+
+def test_updating_a_message_does_not_duplicate_it():
+    m = seeded(mgr(), 3)
+    for text in ("one", "two", "three"):
+        m.update_message(SID, AID, msg(1, text))
+    assert len(m.list_messages(SID, AID)) == 3
+    assert m.read_message(SID, AID, 1).message["content"][0]["text"] == "three"
+
+
+def test_updating_an_agent_does_not_duplicate_it():
+    m = seeded(mgr())
+    for _ in range(5):
+        a = agent()
+        a.state = {"n": 1}
+        m.update_agent(SID, a)
+    assert m.read_agent(SID, AID).state == {"n": 1}
+
+
+# ---- redaction: the reason to use an encrypted store --------------------
+
+
+def test_the_reference_keeps_the_redacted_text_on_disk():
+    """Established as the baseline this integration improves on."""
+    r = seeded(ref(), 1)
+    original = "my card number is 4111 1111 1111 1111"
+    r.create_message(SID, AID, msg(1, original))
+    m = r.read_message(SID, AID, 1)
+    m.redact_message = {"role": "user", "content": [{"text": "[REDACTED]"}]}
+    r.update_message(SID, AID, m)
+
+    stored = r.read_message(SID, AID, 1)
+    assert stored.redact_message is not None
+    assert original in str(stored.message), "the reference keeps the original beside it"
+
+
+def test_a_redaction_removes_the_original_from_the_store():
+    """Keeping the original would leave the redacted content in the store."""
+    m = seeded(mgr(), 0)
+    secret = "my card number is 4111 1111 1111 1111"
+    m.create_message(SID, AID, msg(0, secret))
+
+    stored = m.read_message(SID, AID, 0)
+    stored.redact_message = {"role": "user", "content": [{"text": "[REDACTED]"}]}
+    m.update_message(SID, AID, stored)
+
+    after = m.read_message(SID, AID, 0)
+    assert after.to_message() == {"role": "user", "content": [{"text": "[REDACTED]"}]}
+    assert secret not in str(after.message), "the original survived the redaction"
+    assert secret not in str(after.to_dict()), "the original survived the redaction"
+
+
+def test_a_redaction_at_creation_time_also_drops_the_original():
+    m = seeded(mgr(), 0)
+    secret = "another secret"
+    sm = msg(0, secret)
+    sm.redact_message = {"role": "user", "content": [{"text": "[REDACTED]"}]}
+    m.create_message(SID, AID, sm)
+    assert secret not in str(m.read_message(SID, AID, 0).to_dict())
+
+
+def test_an_unredacted_message_keeps_its_content():
+    """Only a redaction drops the original; an ordinary update must not."""
+    m = seeded(mgr(), 0)
+    m.create_message(SID, AID, msg(0, "ordinary content"))
+    m.update_message(SID, AID, msg(0, "edited content"))
+    after = m.read_message(SID, AID, 0)
+    assert after.to_message()["content"][0]["text"] == "edited content"
+    assert after.redact_message is None
+
+
+def test_a_redaction_replaces_the_stored_record():
+    m = seeded(mgr(), 1)
+    original = "my card number is 4111 1111 1111 1111"
+    m.create_message(SID, AID, msg(1, original))
+
+    stored = m.read_message(SID, AID, 1)
+    stored.redact_message = {"role": "user", "content": [{"text": "[REDACTED]"}]}
+    m.update_message(SID, AID, stored)
+
+    # One record for the index, carrying the redaction.
+    assert len([x for x in m.list_messages(SID, AID) if x.message_id == 1]) == 1
+    assert m.read_message(SID, AID, 1).redact_message is not None
+
+
+def test_created_at_survives_an_update_like_the_reference():
+    m, r = seeded(mgr(), 1), seeded(ref(), 1)
+    for store in (m, r):
+        first = store.read_message(SID, AID, 0)
+        edited = msg(0, "edited")
+        store.update_message(SID, AID, edited)
+        assert store.read_message(SID, AID, 0).created_at == first.created_at
+
+
+# ---- erasure -------------------------------------------------------------
+
+
+def test_forget_session_destroys_everything_it_owns():
+    p = path()
+    m = seeded(mgr(p), 3)
+    assert m.forget_session(SID) == 5  # session + agent + 3 messages
+    assert m.read_session(SID) is None
+    assert m.read_agent(SID, AID) is None
+
+
+def test_forgetting_an_unknown_session_is_zero():
+    assert mgr().forget_session("never") == 0
+
+
+# ---- persistence ---------------------------------------------------------
+
+
+def test_it_survives_a_reopen():
+    p = path()
+    first = seeded(mgr(p), 3)
+    first.update_agent(SID, SessionAgent(agent_id=AID, state={"k": "v"},
+                                         conversation_manager_state={}))
+    del first
+    gc.collect()
+
+    again = CitadelSessionManager(SID, p, "pw")
+    assert again.read_session(SID) is not None
+    assert again.read_agent(SID, AID).state == {"k": "v"}
+    assert [x.message_id for x in again.list_messages(SID, AID)] == [0, 1, 2]
+
+
+def test_a_wrong_passphrase_cannot_reopen():
+    import citadeldb
+
+    p = path()
+    first = seeded(mgr(p))
+    del first
+    gc.collect()
+    with pytest.raises(citadeldb.EncryptionError):
+        CitadelSessionManager(SID, p, "wrong")
+
+
+# ---- concurrency ---------------------------------------------------------
+
+
+def test_concurrent_message_writes_all_land():
+    m = seeded(mgr(), 0)
+    with cf.ThreadPoolExecutor(max_workers=4) as ex:
+        list(ex.map(lambda i: m.create_message(SID, AID, msg(i, f"t{i}")), range(40)))
+    assert len(m.list_messages(SID, AID)) == 40
+
+
+def test_a_message_id_is_stored_once_however_often_it_is_written():
+    """message_id is the conversation index, so a second write of one id
+    replaces it. Two request handlers over one store is the normal shape."""
+    m = seeded(mgr(), 0)
+    m.create_message(SID, AID, msg(7, "from handler one"))
+    m.create_message(SID, AID, msg(7, "from handler two"))
+    stored = m.list_messages(SID, AID)
+    assert [s.message_id for s in stored] == [7]
+    assert m.read_message(SID, AID, 7).message["content"][0]["text"] == "from handler two"
+
+
+def test_concurrent_writes_of_one_message_id_leave_one_record():
+    m = seeded(mgr(), 0)
+    with cf.ThreadPoolExecutor(max_workers=8) as ex:
+        list(ex.map(lambda i: m.create_message(SID, AID, msg(3, f"t{i}")), range(32)))
+    assert [s.message_id for s in m.list_messages(SID, AID)] == [3]
+
+
+# ---- scoping and content shapes -----------------------------------------
+
+
+def test_sessions_and_agents_are_scoped_exactly():
+    p = path()
+    m = CitadelSessionManager("sess", p, "pw")
+    other = CitadelSessionManager("sess-2", p, "pw")
+    m.create_agent("sess", agent())
+    other.create_agent("sess-2", agent())
+    m.create_message("sess", AID, msg(0, "mine"))
+    assert len(m.list_messages("sess", AID)) == 1
+    assert other.list_messages("sess-2", AID) == []
+
+
+def test_agents_within_a_session_are_scoped_exactly():
+    m = mgr()
+    m.create_agent(SID, agent("a"))
+    m.create_agent(SID, agent("a-2"))
+    m.create_message(SID, "a", msg(0, "mine"))
+    assert len(m.list_messages(SID, "a")) == 1
+    assert m.list_messages(SID, "a-2") == []
+
+
+def test_unicode_round_trips():
+    m = seeded(mgr(), 0)
+    text = "ünïcode — 中文 — emoji 🎉"
+    m.create_message(SID, AID, msg(0, text))
+    assert m.read_message(SID, AID, 0).message["content"][0]["text"] == text
+
+
+def test_agent_state_named_like_internal_fields_round_trips():
+    m = seeded(mgr(), 0)
+    hostile = {"sid": "x", "aid": "x", "mid": "x", "message": "x", "agent": "x"}
+    a = agent()
+    a.state = dict(hostile)
+    m.update_agent(SID, a)
+    assert m.read_agent(SID, AID).state == hostile
+
+
+def test_a_message_with_no_text_is_storable():
+    m = seeded(mgr(), 0)
+    m.create_message(SID, AID, SessionMessage(
+        message={"role": "assistant", "content": []}, message_id=0
+    ))
+    assert len(m.list_messages(SID, AID)) == 1
+
+
+def test_two_managers_share_one_database_file():
+    p = path()
+    a = CitadelSessionManager("sa", p, "pw")
+    b = CitadelSessionManager("sb", p, "pw")
+    a.create_agent("sa", agent())
+    a.create_message("sa", AID, msg(0, "in a"))
+    assert a.read_session("sa") is not None and b.read_session("sb") is not None
+    assert b.read_session("sa") is not None, "one file, both sessions visible"