# 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

```python
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()`  |