Struct JsonlSessionStore 

pub struct JsonlSessionStore { /* private fields */ }

JSONL file-based session store.

Each session is a single .jsonl file in the configured directory. Line 1 is SessionMeta (JSON), lines 2+ are one LlmMessage each.

Concurrent writes to the same session may corrupt the file. Callers are expected to enforce single-writer access.

With the search feature enabled, a tantivy index is maintained in <sessions_dir>/.search_index/ and used by SessionStore::search(). Without the feature, search falls back to a linear scan of all JSONL files.

Implementations

impl JsonlSessionStore

pub fn new(sessions_dir: PathBuf) -> Result<Self>

Create a new store rooted at the given directory.

Creates the directory (and parents) if it does not exist.

pub fn open_search_index(&self) -> Result<()>

Open (or create) the tantivy search index eagerly.

Normally the index is opened lazily on the first search() call. Call this method if you want to detect index-creation errors at startup rather than at search time.

Only available with the search feature.

pub fn rebuild_search_index(&self) -> Result<()>

Build (or rebuild) the tantivy index from all current JSONL files.

Existing index data is replaced. Use this after bulk-importing sessions outside of the store API.

Only available with the search feature.

pub fn with_migrators(self, migrators: Vec<Box<dyn SessionMigrator>>) -> Self

Register session migrators for automatic schema upgrades on load.

pub fn default_dir() -> Option<PathBuf>

Default sessions directory: <config_dir>/swink-agent/sessions.

Returns None if the platform config directory cannot be determined.

pub fn new_session_id() -> String

Generate a new unique session ID using a UTC timestamp plus UUID suffix.

impl JsonlSessionStore

pub fn save_entries( &self, id: &str, meta: &SessionMeta, entries: &[SessionEntry], ) -> Result<()>

Save a session with rich entry types.

Lines 2+ are SessionEntry values serialized with an entry_type tag.

When the search feature is enabled, the tantivy index is updated after the file is written (best-effort — index errors are logged but do not fail the save).

pub fn append_entries( &self, id: &str, meta: &SessionMeta, entries: &[SessionEntry], ) -> Result<SessionMeta>

Append entries to an existing session without rewriting the whole file.

This is the append-only counterpart to Self::save_entries. Instead of rewriting every record on each turn, it appends only the new entries and patches the metadata line in place (reusing the same on-disk machinery and locking guarantees as the internal append path).

The caller’s meta.sequence must match the on-disk sequence (optimistic concurrency, identical to Self::save_entries); a mismatch returns an error. Every other meta field is written as provided — only id and sequence are set by the store. The returned SessionMeta carries the incremented sequence so callers stay in sync without re-reading the file.

If the metadata line can no longer be patched in place — its serialized form would outgrow the slot reserved on disk — this transparently falls back to a full rewrite that preserves all existing lines.

Errors if the session file does not exist; use Self::save_entries to create a new session.

When the search feature is enabled, only the newly appended entries are added to the tantivy index afterwards — the session’s existing documents are untouched (best-effort — index errors are logged but do not fail the append).

pub fn load_entries(&self, id: &str) -> Result<(SessionMeta, Vec<SessionEntry>)>

Load a session with rich entry types.

Parses each line after metadata as a SessionEntry. Old-format lines (raw LlmMessage without entry_type) are interpreted as SessionEntry::Message for backward compatibility.

Trait Implementations

impl SessionStore for JsonlSessionStore

fn save( &self, id: &str, meta: &SessionMeta, messages: &[AgentMessage], ) -> Result<()>

Persist a session, including both LLM and custom messages.

fn save_full( &self, id: &str, meta: &SessionMeta, messages: &[AgentMessage], state: &Value, ) -> Result<SessionMeta>

Persist a session transcript plus its state snapshot.

fn append(&self, id: &str, messages: &[AgentMessage]) -> Result<()>

Append messages to an existing session without rewriting the entire file.

fn load( &self, id: &str, registry: Option<&CustomMessageRegistry>, ) -> Result<(SessionMeta, Vec<AgentMessage>)>

Load a session by ID.

fn load_full( &self, id: &str, registry: Option<&CustomMessageRegistry>, ) -> Result<(SessionMeta, Vec<AgentMessage>, Option<Value>)>

Load a session transcript plus its state snapshot from one consistent read boundary.

fn list(&self) -> Result<Vec<SessionMeta>>

List all saved sessions, sorted by last updated (newest first).

fn delete(&self, id: &str) -> Result<()>

Delete a session by ID.

fn save_state(&self, id: &str, state: &Value) -> Result<()>

Save session state snapshot.

fn load_state(&self, id: &str) -> Result<Option<Value>>

Load session state snapshot.

fn save_interrupt(&self, id: &str, state: &InterruptState) -> Result<()>

Persist interrupt state for a session.

fn load_interrupt(&self, id: &str) -> Result<Option<InterruptState>>

Load interrupt state for a session.

fn clear_interrupt(&self, id: &str) -> Result<()>

Clear interrupt state for a session.

fn load_with_options( &self, id: &str, options: &LoadOptions, ) -> Result<(SessionMeta, Vec<SessionEntry>)>

Load a session with filtering options.

fn search( &self, query: &str, options: &SessionSearchOptions, ) -> Result<Vec<SessionHit>>

Search across persisted sessions.