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
//! Where the harness keeps its state.
//!
//! By default local session history, memory, attachments and skills live
//! beneath one directory. The runtime resolves durable session storage from
//! its configured storage backend; the workspace remains a first-class
//! builder input for local files and scratch data.
//!
//! A host that keeps conversations in its own database instead gives the
//! runtime a session store
//! ([`RuntimeBuilder::session_store`](crate::RuntimeBuilder::session_store))
//! and picks [`Workspace::Stateless`]: then nothing that must outlive the
//! process is written to disk at all.
use std::path::{Path, PathBuf};
use super::error::HarnessError;
/// Which workspace an embedded harness runs against.
#[derive(Debug, Clone, Default)]
pub enum Workspace {
/// A throwaway directory, removed when the [`Harness`](super::Harness) is
/// dropped.
///
/// The default, and deliberately so: a library call that silently wrote
/// into the operator's real install would make "try this out" a destructive
/// act. Sessions do not survive the process — pass [`Workspace::Dir`] when
/// they should.
#[default]
Ephemeral,
/// A caller-owned directory. Created if absent; persists across runs.
Dir(PathBuf),
/// No durable state on disk: every agent's transcripts, journal, goals and
/// todos go through the runtime's session store
/// ([`RuntimeBuilder::session_store`](crate::RuntimeBuilder::session_store)),
/// which is required. Without a host storage backend
/// ([`RuntimeBuilder::storage`](crate::RuntimeBuilder::storage) or
/// `[storage] url`), the core's other documents (run status, cron jobs,
/// flows) are kept in memory and lost with the runtime.
///
/// For a cloud host serving many users from one process, where a pod can
/// be replaced at any moment. A private scratch directory still backs the
/// core's process-local caches (cost log, app state, migration markers);
/// it is created like [`Workspace::Ephemeral`]'s and removed with the
/// runtime, so losing it loses nothing.
Stateless,
/// The machine's configured OpenHuman workspace — the one the desktop app
/// and CLI use, resolved the usual way (`OPENHUMAN_WORKSPACE`,
/// `active_user.toml`, `~/.openhuman/...`).
///
/// Reuses an existing signed-in install, and equally can disturb it. The
/// harness will not copy skills into an inherited workspace for that reason.
Inherit,
}
impl Workspace {
/// A throwaway workspace under the system temp dir.
pub fn ephemeral() -> Self {
Self::Ephemeral
}
/// A workspace with no durable state on disk; see [`Workspace::Stateless`].
pub fn stateless() -> Self {
Self::Stateless
}
/// A caller-owned workspace directory.
pub fn dir(path: impl Into<PathBuf>) -> Self {
Self::Dir(path.into())
}
/// Whether this workspace belongs to the operator rather than the harness.
///
/// `true` only for [`Workspace::Inherit`]. Guards the writes the harness
/// would otherwise make on the caller's behalf — see
/// the internal skill-copy module.
pub fn is_operator_owned(&self) -> bool {
matches!(self, Self::Inherit)
}
}
/// A resolved workspace: concrete paths plus, for [`Workspace::Ephemeral`], the
/// [`tempfile::TempDir`] whose lifetime owns them.
///
/// The `TempDir` is held rather than leaked so the directory is removed on drop.
/// Losing it would turn every ephemeral harness into a permanent temp-dir leak,
/// which on a machine whose `/tmp` is a tmpfs is a RAM leak.
pub(crate) struct ResolvedWorkspace {
pub(crate) workspace_dir: PathBuf,
pub(crate) action_dir: PathBuf,
/// Where `config.toml` would live. **Not** cosmetic: its *parent* is the
/// state directory the credential store, the auth profiles and the keyring
/// file backend all resolve against. Leave it at the default while pointing
/// `workspace_dir` at a temp dir and the harness reads and writes the
/// operator's real `~/.openhuman` credentials while looking hermetic.
pub(crate) config_path: PathBuf,
/// `None` for `Dir` / `Inherit`; those directories outlive the runtime.
pub(crate) _temp: Option<std::sync::Arc<EphemeralRoot>>,
}
/// The temp root of an ephemeral workspace, removed when its last holder
/// drops: the runtime, or a deferred agent cleanup that must keep the files
/// until the MCP module acknowledges its close. Shared on its own so that
/// cleanup never has to hold the whole runtime (and its process slot).
pub(crate) struct EphemeralRoot {
temp: Option<tempfile::TempDir>,
preserve: std::sync::atomic::AtomicBool,
}
impl EphemeralRoot {
pub(crate) fn preserve(&self) {
self.preserve
.store(true, std::sync::atomic::Ordering::Release);
}
}
impl Drop for EphemeralRoot {
fn drop(&mut self) {
let Some(temp) = self.temp.take() else {
return;
};
// Take ownership of the temp path and remove it with a short retry.
// The core's memory/session writers keep running a moment after a
// turn returns and can recreate workspace subdirectories while
// `TempDir`'s own drop-time removal is racing them, leaving an empty
// directory behind. A bounded retry lets those writes settle before
// giving up.
let root = temp.keep();
if self.preserve.load(std::sync::atomic::Ordering::Acquire) {
log::warn!(
"[embed][runtime] unresolved cleanup; preserved ephemeral workspace at {}",
root.display()
);
return;
}
let mut quiet_passes = 0;
for _ in 0..20 {
match std::fs::remove_dir_all(&root) {
Ok(()) => quiet_passes += 1,
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
quiet_passes += 1;
}
Err(_) => quiet_passes = 0,
}
if quiet_passes >= 5 {
break;
}
std::thread::sleep(std::time::Duration::from_millis(50));
}
let _ = std::fs::remove_dir_all(&root);
}
}
impl ResolvedWorkspace {
/// Materialize `workspace`, creating directories as needed.
///
/// The layout for the harness-owned variants mirrors
/// `profile/src/bin/library_profile/harness.rs::fixture()` in openhuman-benchmarks, which is the recipe
/// already proven against real turns: a `workspace/` for internal state and
/// a sibling `action/` for the agent's read/write root. Keeping them
/// siblings rather than nesting matters — `is_workspace_internal_path`
/// blocks agent writes beneath the workspace fail-closed, so an `action_dir`
/// inside it would be an agent that cannot write anywhere.
///
/// `config.toml` sits beside the workspace rather than inside it, which is
/// the same shape `load_or_init` produces (`<root>/config.toml` next to
/// `<root>/workspace`). Credential state follows that file's parent, so the
/// layout is what makes an ephemeral harness actually ephemeral.
pub(crate) fn resolve(
workspace: &Workspace,
action_dir_override: Option<&Path>,
) -> Result<Self, HarnessError> {
match workspace {
Workspace::Ephemeral | Workspace::Stateless => {
let temp = tempfile::Builder::new()
.prefix(if matches!(workspace, Workspace::Stateless) {
"openhuman-scratch-"
} else {
"openhuman-harness-"
})
.tempdir()
.map_err(|source| HarnessError::Workspace {
what: "create a temporary workspace",
source,
})?;
let root = temp.path().to_path_buf();
let workspace_dir = root.join("workspace");
let action_dir = action_dir_override
.map(Path::to_path_buf)
.unwrap_or_else(|| root.join("action"));
create_dirs(&workspace_dir, &action_dir)?;
log::debug!("[embed][harness] ephemeral workspace at {}", root.display());
Ok(Self {
workspace_dir,
action_dir,
config_path: root.join("config.toml"),
_temp: Some(std::sync::Arc::new(EphemeralRoot {
temp: Some(temp),
preserve: Default::default(),
})),
})
}
Workspace::Dir(dir) => {
let workspace_dir = dir.clone();
// `Path::parent()` yields `Some("")` for a single-component
// relative path (e.g. `Workspace::dir("ws")`), not `None`.
// Treating that empty parent as a real directory would make the
// sibling `action/` and `config.toml` resolve against the
// process working directory instead of beside the workspace,
// which breaks the credential-isolation invariant below.
let parent = dir.parent().filter(|parent| !parent.as_os_str().is_empty());
let action_dir = action_dir_override
.map(Path::to_path_buf)
// A sibling, for the `is_workspace_internal_path` reason
// above. `dir.parent()` is `None` (or an empty path) only
// for a filesystem root or a path with no parent — all
// cases where a sibling is meaningless anyway, and using
// the workspace dir itself is the only safe fallback.
.or_else(|| parent.map(|parent| parent.join("action")))
.unwrap_or_else(|| dir.join("action"));
create_dirs(&workspace_dir, &action_dir)?;
let config_path = parent.unwrap_or(dir.as_path()).join("config.toml");
Ok(Self {
workspace_dir,
action_dir,
config_path,
_temp: None,
})
}
Workspace::Inherit => {
// Resolved by `Config::load_or_init` rather than here: the
// chain it walks (OPENHUMAN_WORKSPACE, active_user.toml, the
// per-user `users/` scoping) is the operator's, and
// re-deriving it would be a second implementation that drifts.
// The builder signals this by not overriding the loaded fields.
Ok(Self {
workspace_dir: PathBuf::new(),
action_dir: action_dir_override
.map(Path::to_path_buf)
.unwrap_or_default(),
config_path: PathBuf::new(),
_temp: None,
})
}
}
}
}
fn create_dirs(workspace_dir: &Path, action_dir: &Path) -> Result<(), HarnessError> {
for dir in [workspace_dir, action_dir] {
std::fs::create_dir_all(dir).map_err(|source| HarnessError::Workspace {
what: "create the workspace directory",
source,
})?;
}
Ok(())
}
#[cfg(test)]
#[path = "workspace_tests.rs"]
mod tests;