Struct SessionManager 

pub struct SessionManager<P: Platform> { /* private fields */ }

Manages conversation sessions with in-memory caching and JSONL persistence.

Sessions are identified by a string key (typically "{channel}:{chat_id}"). The manager uses a write-through cache: reads check the in-memory cache first, then fall back to loading from disk. Writes update both the cache and the JSONL file.

JSONL format

Each session file is named {sanitized_key}.jsonl and contains:

• Line 1: metadata object with _type, created_at, updated_at, metadata, and last_consolidated fields.
• Lines 2+: message objects with role, content, and timestamp fields.

Platform abstraction

All filesystem I/O goes through the Platform::fs() trait, making SessionManager testable with mock filesystems and WASM-portable.

Implementations

impl<P: Platform> SessionManager<P>

pub async fn new(platform: Arc<P>) -> Result<Self>

Create a new session manager using the given platform.

Discovers the sessions directory by checking:

1. ~/.clawft/workspace/sessions/
2. ~/.nanobot/workspace/sessions/ (legacy fallback)

If neither exists, defaults to ~/.clawft/workspace/sessions/ and creates it. Returns an error if the home directory cannot be determined.

pub fn with_dir(platform: Arc<P>, sessions_dir: PathBuf) -> Self

Create a session manager with an explicit sessions directory.

Useful for testing or when the directory is already known.

pub async fn get_or_create(&self, key: &str) -> Result<Session>

Get an existing session or create a new one.

Checks the in-memory cache first, then attempts to load from disk. If neither succeeds, creates a fresh empty session and caches it.

Errors

Returns an error if key fails session-ID validation.

pub async fn load_session(&self, key: &str) -> Result<Session>

Load a session from its JSONL file on disk.

Parses the first line as metadata and remaining lines as messages. Returns an error if the file does not exist or contains invalid JSON.

Includes a migration path: if the percent-encoded file does not exist but the old underscore-encoded file does, the content is copied to the new filename (the old file is preserved for safety).

pub async fn save_session(&self, session: &Session) -> Result<()>

Save a session to its JSONL file on disk.

Writes the full session: metadata line followed by all message lines. Also updates the in-memory cache.

pub async fn append_turn( &self, key: &str, role: &str, content: &str, ) -> Result<()>

Append a single conversation turn to a session.

Updates both the in-memory cache and appends to the JSONL file on disk. If the session does not exist yet, it is created via [get_or_create].

pub async fn list_sessions(&self) -> Result<Vec<String>>

List all session keys (derived from .jsonl filenames on disk).

Decodes percent-encoded filenames back to the original session key. Files that cannot be decoded as valid UTF-8 are skipped with a warning.

pub async fn invalidate(&self, key: &str)

Remove a session from the in-memory cache.

The JSONL file on disk is not deleted; only the cached copy is evicted. The next [get_or_create] call will reload from disk.

pub async fn delete_session(&self, key: &str) -> Result<()>

Delete a session file from disk and remove from cache.

pub fn sessions_dir(&self) -> &PathBuf

Get the sessions directory path.