# 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)

```bash
nox -s unit_tests -- features/session_model.feature
```

### Robot Framework (smoke / integration tests)

```bash
nox -s integration_tests -- robot/session_model.robot
```

Or run the Robot suite directly:

```bash
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:

```bash
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

```bash
nox -s benchmark
```

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