forked from cleveragents/cleveragents-core
Jeff
106 lines
5.2 KiB
Markdown
106 lines
5.2 KiB
Markdown
# 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) |
|