Trait SessionBackend 

pub trait SessionBackend: Send + Sync {
    // Required methods
    fn load(&self, session_key: &str) -> Vec<ChatMessage>;
    fn append(
        &self,
        session_key: &str,
        message: &ChatMessage,
    ) -> Result<(), Error>;
    fn remove_last(&self, session_key: &str) -> Result<bool, Error>;
    fn list_sessions(&self) -> Vec<String>;

    // Provided methods
    fn load_with_timestamps(&self, session_key: &str) -> Vec<TimestampedMessage> { ... }
    fn update_last(
        &self,
        session_key: &str,
        message: &ChatMessage,
    ) -> Result<bool, Error> { ... }
    fn list_sessions_with_metadata(&self) -> Vec<SessionMetadata> { ... }
    fn compact(&self, _session_key: &str) -> Result<(), Error> { ... }
    fn cleanup_stale(&self, _ttl_hours: u32) -> Result<usize, Error> { ... }
    fn search(&self, _query: &SessionQuery) -> Vec<SessionMetadata> { ... }
    fn clear_messages(&self, session_key: &str) -> Result<usize, Error> { ... }
    fn delete_session(&self, _session_key: &str) -> Result<bool, Error> { ... }
    fn set_session_name(
        &self,
        _session_key: &str,
        _name: &str,
    ) -> Result<(), Error> { ... }
    fn get_session_name(
        &self,
        _session_key: &str,
    ) -> Result<Option<String>, Error> { ... }
    fn set_session_agent_alias(
        &self,
        _session_key: &str,
        _agent_alias: &str,
    ) -> Result<(), Error> { ... }
    fn get_session_agent_alias(
        &self,
        _session_key: &str,
    ) -> Result<Option<String>, Error> { ... }
    fn set_session_context(
        &self,
        _session_key: &str,
        _context: SessionContext<'_>,
    ) -> Result<(), Error> { ... }
    fn get_session_metadata(&self, session_key: &str) -> Option<SessionMetadata> { ... }
    fn set_session_state(
        &self,
        _session_key: &str,
        _state: &str,
        _turn_id: Option<&str>,
    ) -> Result<(), Error> { ... }
    fn get_session_state(
        &self,
        _session_key: &str,
    ) -> Result<Option<SessionState>, Error> { ... }
    fn list_running_sessions(&self) -> Vec<SessionMetadata> { ... }
    fn list_stuck_sessions(&self, _threshold_secs: u64) -> Vec<SessionMetadata> { ... }
}

Trait for session persistence backends.

Implementations must be Send + Sync for sharing across async tasks.

Required Methods

fn load(&self, session_key: &str) -> Vec<ChatMessage>

Load all messages for a session. Returns empty vec if session doesn’t exist.

fn append(&self, session_key: &str, message: &ChatMessage) -> Result<(), Error>

Append a single message to a session.

fn remove_last(&self, session_key: &str) -> Result<bool, Error>

Remove the last message from a session. Returns true if a message was removed.

fn list_sessions(&self) -> Vec<String>

List all session keys.

Provided Methods

fn load_with_timestamps(&self, session_key: &str) -> Vec<TimestampedMessage>

Same as load, but each row carries its persisted created_at when the backend has one. Default impl falls back to load without timestamps so non-SQLite backends keep working.

fn update_last( &self, session_key: &str, message: &ChatMessage, ) -> Result<bool, Error>

Update the content of the last message in a session. Used for incremental persistence of streaming responses — append a placeholder first, then update_last periodically as more content arrives. Returns false if the session is empty. Default implementation is remove_last + append (backends can override for efficiency).

fn list_sessions_with_metadata(&self) -> Vec<SessionMetadata>

List sessions with metadata.

fn compact(&self, _session_key: &str) -> Result<(), Error>

Compact a session file (remove duplicates/corruption). No-op by default.

fn cleanup_stale(&self, _ttl_hours: u32) -> Result<usize, Error>

Remove sessions that haven’t been active within the given TTL hours.

fn search(&self, _query: &SessionQuery) -> Vec<SessionMetadata>

Search sessions by keyword. Default returns empty (backends with FTS override).

fn clear_messages(&self, session_key: &str) -> Result<usize, Error>

Clear all messages from a session, keeping the session itself alive. Returns the number of messages removed.

Override for production use. The default is O(n²) via iterative remove_last — acceptable for tests but may cause latency on sessions with >100 messages.

fn delete_session(&self, _session_key: &str) -> Result<bool, Error>

Delete all messages for a session. Returns true if the session existed.

fn set_session_name(&self, _session_key: &str, _name: &str) -> Result<(), Error>

Set or update the human-readable name for a session.

fn get_session_name(&self, _session_key: &str) -> Result<Option<String>, Error>

Get the human-readable name for a session (if set).

fn set_session_agent_alias( &self, _session_key: &str, _agent_alias: &str, ) -> Result<(), Error>

Record the agent alias that owns a session. Called on WebSocket handshake when the alias is known. No-op for backends that don’t track per-agent attribution.

fn get_session_agent_alias( &self, _session_key: &str, ) -> Result<Option<String>, Error>

Get the agent alias associated with a session, if recorded.

fn set_session_context( &self, _session_key: &str, _context: SessionContext<'_>, ) -> Result<(), Error>

Record the channel / room / sender routing context for a session. Called by channel orchestrators right before the LLM dispatch so the session row can be filtered by platform attribute in the dashboard. No-op default; SQLite override fills the columns added in the structured-routing migration.

fn get_session_metadata(&self, session_key: &str) -> Option<SessionMetadata>

Look up metadata for a single session by key.

The default impl loads all messages to derive the count and calls get_session_name for the name. created_at and last_activity are set to Utc::now() at call time — backends with stored timestamps (e.g. SQLite) should override this method.

fn set_session_state( &self, _session_key: &str, _state: &str, _turn_id: Option<&str>, ) -> Result<(), Error>

Set the session state (e.g. “idle”, “running”, “error”). turn_id identifies the current turn (set when running, cleared on idle).

fn get_session_state( &self, _session_key: &str, ) -> Result<Option<SessionState>, Error>

Get the current session state. Returns None if the backend doesn’t track state.

fn list_running_sessions(&self) -> Vec<SessionMetadata>

List sessions currently in “running” state.

fn list_stuck_sessions(&self, _threshold_secs: u64) -> Vec<SessionMetadata>

List sessions stuck in “running” state longer than threshold_secs.

Implementors

impl SessionBackend for SessionStore

impl SessionBackend for SqliteSessionBackend