TurnStateContainer Class

The state scopes loaded for one turn, together with the identity they were loaded for.

conversation is always present. user is None when the activity has no from identity, so there is no per-user scope to load or persist.

conversation_id/user_id record the identity this container was loaded for. The loader reads them back off the container when saving, so a save can never be told to persist under a different key than it was loaded from. That guarantee is why they are read-only properties: rebinding either one mid-turn would redirect the save to a different conversation or user while the scopes still hold the original identity's data.

Only the identity is bound. conversation/user and the injected deleter/saver remain ordinary mutable attributes, and the TurnState scopes stay mutable for the whole turn, which is how seal() and delete() work.

Constructor arguments are keyword-only so the public constructor is not tied to positional order and can evolve without breaking callers.

Constructor

TurnStateContainer(*, conversation: TurnState, conversation_id: str, user: TurnState | None = None, user_id: str | None = None, _deleter: Callable[[], Awaitable[None]] | None = None, _saver: Callable[[TurnStateContainer], Awaitable[None]] | None = None)

Keyword-Only Parameters

Name	Description
conversation Required
conversation_id Required
user	Default value: None
user_id	Default value: None
_deleter	Default value: None
_saver	Default value: None

Methods

delete	Clear both scopes and remove them from the backing store. The injected deleter removes the keys immediately, then in-memory scopes are cleared so state reflects the deletion during the current turn.
seal	Seal every scope so post-turn access raises.

delete

Clear both scopes and remove them from the backing store.

The injected deleter removes the keys immediately, then in-memory scopes are cleared so state reflects the deletion during the current turn.

async delete() -> None

seal

Seal every scope so post-turn access raises.

seal() -> None

Attributes

conversation_id

Conversation this container was loaded for. Fixed at construction.

user_id

User this container was loaded for, if any. Fixed at construction.

conversation

conversation: TurnState

user

user: TurnState | None