The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
//! The host-installed session store.
//!
//! A host that keeps conversations in its own database (a cloud deployment
//! serving many users from one process) installs a
//! [`SessionStoreProvider`] here once, before agents run. From then on every
//! agent's transcripts, turn journal, run status, goals and todos go through
//! that agent's [`AgentStores`] instead of files under `workspace_dir`. For a
//! store that is not file-backed ([`replaces_files`]) the file-era mirrors
//! (the session dual-write and its shadow reads) stand down: the host store
//! is the only record.
//!
//! Like the memory engine's host binding
//! ([`crate::memory::engine::install_host_engine`]), this is process-wide:
//! OpenHuman runs one runtime per process. With nothing installed, the core
//! keeps today's on-disk layout.
use std::sync::{Arc, LazyLock, PoisonError, RwLock};
use tinyagents_session::port::{AgentStores, SessionStoreProvider};
mod host_stores;
mod rebound;
mod tenant_router;
pub use host_stores::{
artifact_blobs_for, artifact_scoped_for_in, attachment_stash_for, current_documents_for,
default_turn_states_for, ledger_for, provider_for_workspace, provider_for_workspace_in,
release_workspace, release_workspace_defaults, require_ledger, session_scope, status_store_for,
stores_for, stores_or_ephemeral, turn_states_for, with_ledger, with_ledger_async,
WorkspaceSessionStores,
};
pub use rebound::{rebind_all, ReboundSessionStores, StoreRegistry};
pub use tenant_router::TenantSessionStores;
/// Drops cached stores for a profile after its lease is released. Existing
/// handles retain their original fence; a later profile open gets fresh ones.
pub fn release_profile(profile: &str) {
rebound::release_profile(profile);
}
static PROVIDER: LazyLock<RwLock<Option<Arc<dyn SessionStoreProvider>>>> =
LazyLock::new(|| RwLock::new(None));
/// Routes every agent's session state through `provider`, replacing any
/// earlier one.
pub fn install(provider: Arc<dyn SessionStoreProvider>) -> Option<Arc<dyn SessionStoreProvider>> {
tracing::info!(
destination = ?provider.destination_key(),
"[session_store] host session store installed"
);
PROVIDER
.write()
.unwrap_or_else(PoisonError::into_inner)
.replace(provider)
}
/// Removes the installed provider; the on-disk layout applies again. Returns
/// whether one was installed.
pub fn clear() -> bool {
let had = PROVIDER
.write()
.unwrap_or_else(PoisonError::into_inner)
.take()
.is_some();
if had {
tracing::info!("[session_store] host session store removed");
}
had
}
/// Clears the installed provider only when it is still the provider claimed
/// by the caller. This keeps a runtime from removing a replacement installed
/// by another owner after the runtime itself has been dropped.
pub fn clear_if(expected: &Arc<dyn SessionStoreProvider>) -> bool {
let mut installed = PROVIDER.write().unwrap_or_else(PoisonError::into_inner);
if installed
.as_ref()
.is_some_and(|current| Arc::ptr_eq(current, expected))
{
installed.take();
tracing::info!("[session_store] host session store removed");
true
} else {
false
}
}
pub fn restore(provider: Option<Arc<dyn SessionStoreProvider>>) {
*PROVIDER.write().unwrap_or_else(PoisonError::into_inner) = provider;
}
/// The provider in effect for the calling task's ambient context: see
/// [`installed_in`].
#[must_use]
pub fn installed() -> Option<Arc<dyn SessionStoreProvider>> {
installed_in(&crate::core::runtime::DispatchCtx::ambient())
}
/// The provider in effect for `ctx`: the host-override one of the agent it
/// runs for, else the installed one, if any.
#[must_use]
pub fn installed_in(
ctx: &crate::core::runtime::DispatchCtx,
) -> Option<Arc<dyn SessionStoreProvider>> {
ctx.host_overrides()
.and_then(|local| local.session_store.clone())
.or_else(|| {
PROVIDER
.read()
.unwrap_or_else(PoisonError::into_inner)
.clone()
})
}
/// Whether a host session store is in effect.
#[must_use]
pub fn is_installed() -> bool {
installed().is_some()
}
/// Whether the store in effect keeps conversations somewhere other than the
/// classic workspace files ([`SessionStoreProvider::workspace_dir`] is
/// `None`), so companions that read those files back have nothing to read.
#[must_use]
pub fn replaces_files() -> bool {
installed().is_some_and(|provider| provider.workspace_dir().is_none())
}
/// `agent_id`'s stores from the installed provider, or `None` when the core
/// keeps the on-disk layout.
#[must_use]
pub fn for_agent(agent_id: &str) -> Option<AgentStores> {
installed().map(|provider| provider.for_agent(agent_id))
}
/// `agent_id`'s transcripts from the store in effect, or `None` when the core
/// keeps them as workspace files.
#[must_use]
pub fn transcripts_for(
agent_id: &str,
) -> Option<Arc<dyn tinyagents_session::transcript::TranscriptLocator>> {
let stores = for_agent(agent_id)?;
log::debug!("[session_store] transcripts via the host store agent={agent_id}");
Some(stores.transcripts)
}
/// [`transcripts_for`] `agent_id`, or the workspace's own transcript store
/// ([`workspace_transcripts`]) when no host store is in effect — the session
/// host's resolution.
#[must_use]
pub fn transcripts_or_files(
agent_id: &str,
workspace_dir: &std::path::Path,
) -> Arc<dyn tinyagents_session::transcript::TranscriptLocator> {
transcripts_for(agent_id).unwrap_or_else(|| workspace_transcripts(agent_id, workspace_dir))
}
/// [`transcripts_or_files`] for the store `core` selects, never the ambient
/// context's: `core`'s own host-override provider, else the installed one,
/// else the workspace's store. For work that carries its context explicitly
/// (a detached sub-agent on a bare `tokio::spawn`, which has no ambient one).
#[must_use]
pub fn transcripts_or_files_in(
core: &crate::core::runtime::CoreContext,
agent_id: &str,
workspace_dir: &std::path::Path,
) -> Arc<dyn tinyagents_session::transcript::TranscriptLocator> {
let provider = core
.host_overrides()
.and_then(|overrides| overrides.session_store.clone())
.or_else(|| {
PROVIDER
.read()
.unwrap_or_else(PoisonError::into_inner)
.clone()
});
match provider {
Some(provider) => {
log::debug!(
"[session_store] transcripts via the carried context's store agent={agent_id}"
);
provider.for_agent(agent_id).transcripts
}
None => workspace_transcripts(agent_id, workspace_dir),
}
}
/// `agent_id`'s transcripts for a host that has a workspace path but no
/// separately installed provider. The workspace default backend and owner
/// session collections are used; a refused backend returns refusing stores.
#[must_use]
pub fn workspace_transcripts(
agent_id: &str,
workspace_dir: &std::path::Path,
) -> Arc<dyn tinyagents_session::transcript::TranscriptLocator> {
host_stores::provider_for_workspace(workspace_dir)
.for_agent(agent_id)
.transcripts
}
/// The stores of the tenant the current [`CoreContext`] works for, keyed by
/// [`session_key`](crate::core::runtime::session_key): the agent it was
/// derived for ([`CoreContext::session_agent`]), else [`DEFAULT_AGENT`],
/// prefixed by its SaaS profile when it serves one — or `None` when the core
/// keeps the on-disk layout.
///
/// For code that has a workspace path but no agent id of its own (goals,
/// todos, the turn journal): under an embedded agent's context it lands in
/// that agent's stores. A SaaS task with no scope gets none rather than the
/// shared default bucket.
///
/// [`CoreContext`]: crate::core::runtime::CoreContext
/// [`CoreContext::session_agent`]: crate::core::runtime::CoreContext::session_agent
#[must_use]
pub fn current(ctx: &crate::core::runtime::DispatchCtx) -> Option<AgentStores> {
let provider = installed()?;
let tenant = match ctx.tenant() {
Ok(tenant) => tenant,
Err(no_tenant) => {
log::warn!("[session_store] current: {no_tenant}");
return None;
}
};
Some(provider.for_agent(&crate::core::runtime::session_key(&tenant)))
}
/// The agent id a session host resolves transcripts under for the current
/// tenant: the [`session_key`](crate::core::runtime::session_key) when it
/// serves a SaaS profile, else the context's agent, else `fallback` (the
/// session's own definition id), as before profiles existed.
#[must_use]
pub fn current_agent_key_or(ctx: &crate::core::runtime::DispatchCtx, fallback: &str) -> String {
agent_key_for(
&crate::core::runtime::tenant::isolated_unless_tenant(ctx.tenant(), "session_locator"),
fallback,
)
}
/// The agent id `tenant`'s transcripts are kept under, for a caller that
/// already holds the request's tenant (an RPC handler's context): the
/// [`session_key`](crate::core::runtime::session_key) when it serves a SaaS
/// profile, else its agent, else `fallback` (the session's definition id).
/// [`current_agent_key_or`] is this over a context's tenant, so a reader that
/// passes its tenant here resolves the same store the session host wrote to.
#[must_use]
pub fn agent_key_for(tenant: &crate::core::runtime::Tenant, fallback: &str) -> String {
if tenant.profile.is_some() {
return crate::core::runtime::session_key(tenant);
}
tenant.agent.clone().unwrap_or_else(|| fallback.to_string())
}
/// The workspace the current [`CoreContext`](crate::core::runtime::CoreContext)
/// is bound to, for a file-backed store that must follow it (the desktop
/// rebinds it when a different user signs in). Before the core has booted —
/// when no store is asked for anything — the default config's workspace.
#[must_use]
pub fn context_workspace_dir() -> std::path::PathBuf {
crate::core::runtime::CoreContext::current()
.and_then(|context| context.workspace_dir().ok())
.unwrap_or_else(|| {
log::warn!("[session_store] no booted context; using the default workspace");
crate::config::Config::default().workspace_dir
})
}
/// The agent whose stores a turn without a definition id uses. Root turns of
/// the desktop app have no per-user agent; a single shared bucket keeps them
/// together, as the shared workspace always did.
pub const DEFAULT_AGENT: &str = "default";
#[cfg(test)]
#[path = "splice_fixture_tests.rs"]
pub(crate) mod splice_fixture_tests;
#[cfg(test)]
#[path = "mod_tests.rs"]
mod tests;