# Session Domain Model

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

## MessageRole

| Value       | Description                    |
|-------------|--------------------------------|
| `user`      | Human input                    |
| `assistant` | AI/agent response              |
| `system`    | System-level instructions      |
| `tool`      | Tool invocation result         |

## SessionMessage

Each message within a session:

| Field          | Type              | Default         | Description                              |
|----------------|-------------------|-----------------|------------------------------------------|
| `message_id`   | `str`             | (required)      | Unique ULID identifier                   |
| `role`         | `MessageRole`     | (required)      | Role of the message sender               |
| `content`      | `str`             | (required)      | Message content (min 1 char, no whitespace-only) |
| `sequence`     | `int`             | (required)      | Ordering index within the session (>= 0) |
| `timestamp`    | `datetime`        | `datetime.now()`| When the message was created             |
| `metadata`     | `dict[str, Any]`  | `{}`            | Optional metadata                        |
| `tool_call_id` | `str \| None`     | `None`          | Required when role is `tool`             |

**Constraints**:
- `content` must not be whitespace-only
- `tool_call_id` is required when `role` is `tool`

## SessionTokenUsage

Accumulated token usage for a session:

| Field            | Type    | Default | Description                    |
|------------------|---------|---------|--------------------------------|
| `input_tokens`   | `int`   | `0`     | Total input tokens consumed    |
| `output_tokens`  | `int`   | `0`     | Total output tokens generated  |
| `estimated_cost` | `float` | `0.0`   | Estimated total cost (USD)     |

All fields must be >= 0.

## Session Fields

| Field              | Type                      | Default                  | Description                            |
|--------------------|---------------------------|--------------------------|----------------------------------------|
| `session_id`       | `str`                     | (required)               | Unique ULID identifier                 |
| `actor_name`       | `str \| None`             | `None`                   | Namespaced actor reference             |
| `namespace`        | `str`                     | `"local"`                | Namespace for ownership                |
| `messages`         | `list[SessionMessage]`    | `[]`                     | Ordered messages                       |
| `linked_plan_ids`  | `list[str]`               | `[]`                     | ULID references to linked plans        |
| `automation_level` | `str \| None`             | `None`                   | Session-level automation override      |
| `token_usage`      | `SessionTokenUsage`       | `SessionTokenUsage()`    | Accumulated token usage                |
| `created_at`       | `datetime`                | `datetime.now()`         | Creation timestamp                     |
| `updated_at`       | `datetime`                | `datetime.now()`         | Last modification timestamp            |
| `metadata`         | `dict[str, Any]`          | `{}`                     | Arbitrary session metadata             |

**Constraints**:
- `session_id` must match ULID format (`^[0-9A-HJKMNP-TV-Z]{26}$`)
- `actor_name` if provided must match `namespace/name` pattern
- `messages` must be ordered by `sequence`

## Properties

- `session.message_count` -- Number of messages
- `session.last_message` -- Most recent message (or None)
- `session.is_empty` -- True if no messages

## Methods

- `session.append_message(role, content, metadata=None, tool_call_id=None)` -- Append a message with auto-generated ULID and sequence
- `session.get_messages(limit=None, offset=0)` -- Paginated message retrieval
- `session.link_plan(plan_id)` -- Link a plan (deduplicated)
- `session.as_cli_dict()` -- Stable ordered dict for CLI rendering
- `session.as_export_dict()` -- JSON-serializable dict with checksum

## CLI Dict Output

The `as_cli_dict()` output matches `agents session show`:

- `session_id`, `actor_name`, `namespace`, `message_count`
- `created_at`, `updated_at`, `automation_level`
- `recent_messages` (last 5), `linked_plan_ids`
- `token_usage` (input/output/cost), `metadata`

## Export Dict

The `as_export_dict()` output includes:

- `schema_version`, `session_id`, `actor_name`, `namespace`
- `messages` (full history), `linked_plan_ids`
- `automation_level`, `token_usage`, `metadata`
- `created_at`, `updated_at`, `checksum` (SHA-256)

## Error Types

| Error                  | Base                    | Description                        |
|------------------------|-------------------------|------------------------------------|
| `SessionServiceError`  | `Exception`             | Base error for session operations  |
| `SessionNotFoundError` | `SessionServiceError`   | Session ID not found               |
| `SessionExportError`   | `SessionServiceError`   | Export failures                    |
| `SessionImportError`   | `SessionServiceError`   | Import failures (schema, corrupt)  |