cleveragents-core/docs/reference/session_model.md

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)