Struct SessionRepository 

pub struct SessionRepository { /* private fields */ }

Framework-owned coordinator over a session’s cache / storage / persistence tiers. Cheap to clone (all fields are Arc).

Implementations

impl SessionRepository

pub fn new( cache: SessionCache, storage: Arc<dyn Storage>, persistence: Arc<LockedSessionStore>, ) -> Self

pub fn cache(&self) -> &SessionCache

pub fn storage(&self) -> &Arc<dyn Storage>

pub fn persistence(&self) -> &Arc<LockedSessionStore>

pub async fn load(&self, session_id: &str) -> Option<Session>

Load a session from the memory cache, falling back to durable storage (and back-filling the cache on a storage hit). None if absent in both.

pub async fn try_load(&self, session_id: &str) -> Result<Option<Session>>

Like load, but surfaces storage errors instead of swallowing them to None. Cache hit short-circuits; a storage hit back-fills the cache.

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

Persist the session (merge-on-write) and refresh the cache, surfacing storage errors. Use save_and_cache for the fire-and-forget variant that logs and continues on failure.

pub async fn update_runtime_session<F>( &self, session_id: &str, metadata_keys: &[&str], mutate: F, ) -> Result<Option<Session>>

where F: FnOnce(&mut Session),

Atomically mutate the latest durable runtime session and refresh the cache with the saved value. This is the safe path for narrow metadata indexes that can be updated concurrently with runner message writes.

pub async fn load_or_create(&self, session_id: &str, model: &str) -> Session

Load a session, creating a fresh Session::new(id, model) if absent.

pub async fn load_merged(&self, session_id: &str) -> Option<Session>

Load a session, reconciling the memory and storage copies via a preference heuristic: storage wins when it is strictly newer, or when it is the same age but still carries a pending question memory lost. Storage is never preferred when it is strictly older than memory.

The cache is refreshed cache-aside but with a no-regression guarantee: load_merged never overwrites a newer cached session with an older storage copy, so it is safe to call from hot read paths.

pub async fn save_and_cache(&self, session: &mut Session)

Persist the session (merge-on-write, preserving concurrent UI edits to the authoritative metadata group) and refresh the in-memory cache.

Trait Implementations

impl Clone for SessionRepository

fn clone(&self) -> SessionRepository

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl RuntimeSessionPersistence for SessionRepository

SessionRepository is the canonical RuntimeSessionPersistence: the runtime can persist a session through the same coordinator (merge-on-write + cache refresh) instead of a bespoke adapter.

fn save_runtime_session<'life0, 'life1, 'async_trait>( &'life0 self, session: &'life1 mut Session, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Persist the session, merging any newer authoritative metadata from disk.

fn checkpoint_runtime_session<'life0, 'life1, 'async_trait>( &'life0 self, session: &'life1 mut Session, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Append-safe checkpoint used at the shared engine execute boundary.

fn load_runtime_session<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<Session>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Load the latest runtime-visible session snapshot when the persistence implementation can coordinate reads. Tools may update a repository-owned clone while an agent loop holds its own live Session; the loop uses this hook to merge narrowly-scoped tool side effects before its next save.

fn append_token_usage_record<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session_id: &'life1 str, json_line: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Append one JSON-line analysis record to the session’s append-only token-usage log (see Storage::append_token_usage_record). Defaults to a no-op so non-file-backed persisters are unaffected.

impl SessionAccess for SessionRepository

The framework-owned SessionRepository is the canonical SessionAccess. Server AppState delegates to its session_repo; SDK / in-process callers can use a SessionRepository directly as a SessionAccess.

fn load_session<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<Session>, SessionLoadError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Load a session by ID (from cache or storage).

fn load_or_create<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, id: &'life1 str, model: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<Session, SessionLoadError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Load an existing session or create a new one with the given model.

fn load_merged<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<Session>, SessionLoadError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Load a session, merging memory and storage using a preference heuristic.

fn save_session<'life0, 'life1, 'async_trait>( &'life0 self, session: &'life1 mut Session, ) -> Pin<Box<dyn Future<Output = Result<(), SessionSaveError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Save a session to persistent storage only.

fn save_and_cache<'life0, 'life1, 'async_trait>( &'life0 self, session: &'life1 mut Session, ) -> Pin<Box<dyn Future<Output = Result<(), SessionSaveError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Save a session to persistent storage and update the in-memory cache.