cleveragents-core/docs/reference/session_service.md

Session Service Contract

The SessionService is the abstract interface for session management in CleverAgents. Implementations handle persistence, ULID generation, and lifecycle management for Session objects.

Interface

class SessionService(ABC):
    def create(self, actor_name: str | None = None) -> Session: ...
    def get(self, session_id: str) -> Session: ...
    def list(self) -> list[Session]: ...
    def delete(self, session_id: str) -> None: ...
    def append_message(
        self,
        session_id: str,
        role: MessageRole,
        content: str,
        metadata: dict | None = None,
    ) -> SessionMessage: ...
    def export_session(self, session_id: str) -> dict: ...
    def import_session(self, data: dict) -> Session: ...
    def update_token_usage(
        self,
        session_id: str,
        input_tokens: int,
        output_tokens: int,
        cost: float,
    ) -> None: ...

Methods

create

Create a new session with a fresh ULID. Optionally bind to an actor.

Parameter	Type	Default	Description
actor_name	str | None	None	Namespaced actor to bind

Returns: Session

get

Retrieve a session by its ULID.

Raises: SessionNotFoundError if not found.

list

Return all sessions ordered by creation time.

delete

Remove a session by its ULID.

Raises: SessionNotFoundError if not found.

append_message

Add a message to a session. The implementation generates a ULID for the message and sets the sequence number.

Parameter	Type	Default	Description
session_id	str	--	Target session ULID
role	MessageRole	--	Message role
content	str	--	Message content
metadata	dict | None	None	Optional metadata

Returns: SessionMessage Raises: SessionNotFoundError if session not found.

export_session

Export a session as a JSON-serializable dict including a SHA-256 checksum for integrity verification.

Raises: SessionNotFoundError, SessionExportError

import_session

Import a session from an export dict. Validates schema version and checksum integrity.

Raises: SessionImportError on schema mismatch or corrupt data.

update_token_usage

Increment token usage counters for a session.

Parameter	Type	Description
session_id	str	Target session ULID
input_tokens	int	Input tokens to add
output_tokens	int	Output tokens to add
cost	float	Estimated cost to add (USD)

Raises: SessionNotFoundError if session not found.

Error Hierarchy

Exception
  -> SessionServiceError        (base)
       -> SessionNotFoundError  (session ID not found)
       -> SessionExportError    (export failures)
       -> SessionImportError    (import failures)

CLI Commands

The service backs the following CLI commands:

Command	Service Method
agents session create	create()
agents session list	list()
agents session show	get()
agents session delete	delete()
agents session export	export_session()
agents session import	import_session()
agents session tell	append_message()