Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

docs(storage): limit the runtime-isolation claim to connection-time tasks

oxoxDev372276513faa
diff --git a/crates/openhuman-core/src/storage/README.md b/crates/openhuman-core/src/storage/README.md
index 4ff9cf4b98..c000bf3a3b 100644
--- a/crates/openhuman-core/src/storage/README.md
+++ b/crates/openhuman-core/src/storage/README.md
@@ -91,8 +91,10 @@ it with the core stopped.
- `configured_url(&Config)` / `url_from(env, &Config)`: the URL in effect.
- `open(url)`: parse and open a backend (credentials are redacted in logs) The
driver connects on the process's storage runtime (two `openhuman-storage`
- worker threads, alive for the whole process), so a driver's background tasks
- (MongoDB's connection pool and monitors) never depend on the host runtime.
+ worker threads, alive for the whole process), so MongoDB's connection-time
+ pool and monitor tasks do not depend on the host runtime. Cleanup tasks
+ registered by later object drops can run on the internal `storage::block_on`
+ runtime instead.
- `install(backend)` / `installed()` / `clear()`: the process slot domains
read the backend from.
- `scope_for_agent(agent_id)`: the storage scope (`local/agent:<id>`) an agent's records live
diff --git a/crates/openhuman-core/src/storage/mod.rs b/crates/openhuman-core/src/storage/mod.rs
index 222e6cd19f..f106741cdb 100644
--- a/crates/openhuman-core/src/storage/mod.rs
+++ b/crates/openhuman-core/src/storage/mod.rs
@@ -305,9 +305,10 @@ pub async fn open(url: &str) -> Result<Arc<dyn StorageBackend>, StorageError> {
}
/// The process's storage runtime: two worker threads that live as long as the
-/// process. A driver connected here keeps its background tasks (MongoDB's
-/// connection pool and monitors) here, off the host runtime, so callers parked
-/// on [`block_on`] cannot starve them.
+/// process. A driver connected here starts its connection-time background tasks
+/// (MongoDB's connection pool and monitors) here, off the host runtime, so
+/// callers parked on [`block_on`] cannot starve them. Cleanup tasks registered
+/// by later object drops can run on the internal [`block_on`] runtime instead.
fn storage_runtime() -> Result<&'static tokio::runtime::Runtime, StorageError> {
static RUNTIME: OnceLock<Result<tokio::runtime::Runtime, String>> = OnceLock::new();
RUNTIME
diff --git a/docs/gitbooks/en/developing/architecture/storage.md b/docs/gitbooks/en/developing/architecture/storage.md
index c596982317..7d34ab520b 100644
--- a/docs/gitbooks/en/developing/architecture/storage.md
+++ b/docs/gitbooks/en/developing/architecture/storage.md
@@ -100,7 +100,7 @@ On a shared backend (MongoDB) other processes may write the same records, so boo
### The storage runtime
-`storage::open` connects the driver on a process-wide tokio runtime of its own (two `openhuman-storage` worker threads, never shut down). A driver's background tasks, such as the MongoDB client's connection pool and server monitors, live there and not on the host's runtime. Synchronous stores reach the ports through `storage::block_on`, which parks the calling thread; with the backend on the storage runtime, any number of parked callers cannot leave the host runtime without the threads the backend needs to answer them. An embedder that wants this isolation passes its storage as a URL (`StorageSource::Url`) rather than a backend it opened on its own runtime.
+`storage::open` connects the driver on a process-wide tokio runtime of its own (two `openhuman-storage` worker threads, never shut down). MongoDB's connection-time pool and server-monitor tasks live there and not on the host's runtime. Cleanup tasks registered by later object drops can run on the internal `storage::block_on` runtime instead. Synchronous stores reach the ports through `storage::block_on`, which parks the calling thread; with the backend on the storage runtime, any number of parked callers cannot leave the host runtime without the threads the backend needs to answer them. An embedder that wants this isolation passes its storage as a URL (`StorageSource::Url`) rather than a backend it opened on its own runtime.
## Drivers and on-disk layout