cleveragents-core/docs/reference/session_model.md

Session Domain Model

The Session domain model represents a persistent conversation thread tied to an orchestrator actor. It maintains message history across plans and serves as the user's natural-language interface.

Key Classes

Class	Description
Session	Core session model with messages, token tracking, and export
SessionMessage	A single message within a session (ULID-identified, sequenced)
MessageRole	Enum: user, assistant, system, tool
SessionTokenUsage	Accumulated input/output token counts and cost

Source Location

src/cleveragents/domain/models/core/session.py

Session Lifecycle

1. Create -- Session(session_id=str(ULID())) with optional actor_name
2. Append messages -- session.append_message(role, content) auto-sequences
3. Query -- session.get_messages(limit, offset) for paginated access
4. Export -- session.as_export_dict() produces a checksummed JSON dict
5. CLI rendering -- session.as_cli_dict() returns an OrderedDict for display

Export Serialization Order

The as_export_dict() method produces keys in this fixed order:

schema_version, session_id, actor_name, namespace, messages,
linked_plan_ids, automation_level, token_usage, metadata,
created_at, updated_at, checksum

Running Tests

Behave (BDD unit tests)

nox -s unit_tests -- features/session_model.feature

Robot Framework (smoke / integration tests)

nox -s integration_tests -- robot/session_model.robot

Or run the Robot suite directly:

robot --outputdir build/reports/robot robot/session_model.robot

Robot Smoke Suite

The Robot smoke suite (robot/session_model.robot) validates:

• Session creation -- default fields (session_id, namespace, is_empty)
• Message append ordering -- auto-sequencing produces [0, 1, 2, ...]
• Export dict completeness -- all 12 required keys are present
• CLI dict completeness -- required display keys are present
• Export key order -- keys follow the canonical serialization order

The smoke tests delegate to robot/helper_session_model.py, which can also be invoked standalone:

python robot/helper_session_model.py create
python robot/helper_session_model.py append-messages
python robot/helper_session_model.py export
python robot/helper_session_model.py cli-dict
python robot/helper_session_model.py export-key-order

ASV Benchmarks

nox -s benchmark

Benchmark suites in benchmarks/session_model_bench.py cover validation throughput, append performance, and serialization speed.