Skip to content

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

refactor(orchestration): move root parent context builder to triage

Steven Enamakel1ebfe731b949
diff --git a/crates/openhuman-core/src/agent/README.md b/crates/openhuman-core/src/agent/README.md
index ba295a0abe..c981a83729 100644
--- a/crates/openhuman-core/src/agent/README.md
+++ b/crates/openhuman-core/src/agent/README.md
@@ -346,7 +346,7 @@ Persistence, setup and RPC:
- `AgentDefinition`, `AgentDefinitionRegistry`, `ToolScope`, `SandboxMode`
(`../agent_registry/host_definition.rs` + `tinyagents-definition`): what an agent is.
- `ParentExecutionContext` ([`harness/fork_context.rs`](./harness/fork_context.rs)): explicit parent
- state a sub-agent reads from the run context (`parent`); `orchestration::parent_context::build_root_parent`
+ state a sub-agent reads from the run context (`parent`); `triage::parent_context::build_root_parent`
builds one for runs with no parent turn.
- `run_subagent`, `run_subagent_with_parent`, `SubagentRunOptions`
([`subagent_host/lifecycle.rs`](./subagent_host/lifecycle.rs), [`subagent_host/types.rs`](./subagent_host/types.rs)).
diff --git a/crates/openhuman-core/src/agent/harness/fork_context.rs b/crates/openhuman-core/src/agent/harness/fork_context.rs
index d460d93cbe..ca88ef25cf 100644
--- a/crates/openhuman-core/src/agent/harness/fork_context.rs
+++ b/crates/openhuman-core/src/agent/harness/fork_context.rs
@@ -7,7 +7,7 @@
//! [`OpenHumanRunContext`](crate::agent::tinyagents::host::OpenHumanRunContext)
//! (`parent`), tools read it from there, and controller-spawned background
//! surfaces (such as the workflow engine) build a root one with
-//! [`crate::agent::orchestration::parent_context::with_root_parent`] and pass it
+//! [`crate::triage::parent_context::build_root_parent`] and pass it
//! to the spawns they make. There is no ambient copy.
//!
//! Stashed in `Arc`s so cloning into a child costs a refcount bump
diff --git a/crates/openhuman-core/src/agent/orchestration/README.md b/crates/openhuman-core/src/agent/orchestration/README.md
index 8330af6160..4fc4aa702d 100644
--- a/crates/openhuman-core/src/agent/orchestration/README.md
+++ b/crates/openhuman-core/src/agent/orchestration/README.md
@@ -12,7 +12,6 @@ and UI-facing projections.
- Background sub-agent task tracking, cancellation, completion
delivery, and run-ledger projection.
- Manual cancellation for detached `spawn_subagent` runs.
-- The shared root `ParentExecutionContext` builder used by background tasks.
## Key files
@@ -23,7 +22,6 @@ and UI-facing projections.
routing.
- `subagent_control.rs`: manual cancel RPC over the driver-owned job registry.
- `subagent_sessions/`: durable session reuse and deduplication.
-- `parent_context/builder.rs`: construction for tasks without a parent turn.
- `tools.rs`: callable sub-agent tools.
## RPC
diff --git a/crates/openhuman-core/src/agent/orchestration/mod.rs b/crates/openhuman-core/src/agent/orchestration/mod.rs
index dfc004e9e6..a475cc4541 100644
--- a/crates/openhuman-core/src/agent/orchestration/mod.rs
+++ b/crates/openhuman-core/src/agent/orchestration/mod.rs
@@ -18,8 +18,6 @@ pub(crate) mod completion_notice;
pub(crate) mod completion_owners;
pub(crate) mod completion_target;
pub(crate) mod delivery_drain;
-#[path = "parent_context/builder.rs"]
-pub(crate) mod parent_context;
pub(crate) mod running_subagents;
pub(crate) mod subagent_events;
pub(crate) mod subagent_sessions;
diff --git a/crates/openhuman-core/src/agent/orchestration/parent_context/builder_tests.rs b/crates/openhuman-core/src/agent/orchestration/parent_context/builder_tests.rs
deleted file mode 100644
index 7e470420aa..0000000000
--- a/crates/openhuman-core/src/agent/orchestration/parent_context/builder_tests.rs
+++ /dev/null
@@ -1,103 +0,0 @@
-use super::*;
-
-fn test_config() -> (tempfile::TempDir, Config) {
- let dir = tempfile::tempdir().expect("tempdir");
- let config = Config {
- workspace_dir: dir.path().to_path_buf(),
- ..Config::default()
- };
- (dir, config)
-}
-
-/// Regression (TAURI-RUST-HMW / #4337): `with_root_parent` must hand a real
-/// parent to the wrapped closure so a background orchestration surface (cron
-/// job, workflow engine, team runtime) can spawn sub-agents without hitting
-/// `NoParentContext`. Proven by observing the parent the closure receives.
-#[tokio::test]
-async fn with_root_parent_hands_a_root_parent_to_the_closure() {
- let (_dir, config) = test_config();
- let observed = with_root_parent(
- &crate::core::runtime::DispatchCtx::ambient(),
- None,
- &config,
- "cron",
- "cron",
- "cron",
- |parent| async move { parent.agent_definition_id },
- )
- .await
- .expect("root parent builds from config");
- assert_eq!(
- observed, "cron",
- "the closure must receive the root parent built from config"
- );
-}
-
-/// When a parent is passed explicitly, `with_root_parent` uses it instead of
-/// building a second root, so a test can drive a surface under a mock parent
-/// (and thus a mock provider) hermetically.
-#[tokio::test]
-async fn with_root_parent_uses_an_explicit_parent_override() {
- let (_dir, config) = test_config();
- let outer = build_root_parent(
- &crate::core::runtime::DispatchCtx::ambient(),
- &config,
- "outer",
- "outer",
- "outer",
- )
- .await
- .expect("build explicit parent");
- let observed = with_root_parent(
- &crate::core::runtime::DispatchCtx::ambient(),
- Some(outer),
- &config,
- "inner",
- "inner",
- "inner",
- |parent| async move { parent.agent_definition_id },
- )
- .await
- .expect("uses the override, no build error");
- assert_eq!(
- observed, "outer",
- "with_root_parent must use the explicit parent, not build a new 'inner' root"
- );
-}
-
-/// The parent a surface spawns under is the value the closure received, not
-/// something read from the executing task: two concurrent surfaces on one
-/// runtime each see their own root.
-#[tokio::test]
-async fn concurrent_root_parents_do_not_cross() {
- let (_dir, config) = test_config();
- let ctx = crate::core::runtime::DispatchCtx::ambient();
- let (a, b) = tokio::join!(
- with_root_parent(
- &ctx,
- None,
- &config,
- "surface_a",
- "a",
- "a",
- |parent| async move {
- tokio::task::yield_now().await;
- parent.agent_definition_id
- }
- ),
- with_root_parent(
- &ctx,
- None,
- &config,
- "surface_b",
- "b",
- "b",
- |parent| async move {
- tokio::task::yield_now().await;
- parent.agent_definition_id
- }
- ),
- );
- assert_eq!(a.expect("a"), "surface_a");
- assert_eq!(b.expect("b"), "surface_b");
-}
diff --git a/crates/openhuman-core/src/triage/README.md b/crates/openhuman-core/src/triage/README.md
index 279eb3520d..47baea6dc2 100644
--- a/crates/openhuman-core/src/triage/README.md
+++ b/crates/openhuman-core/src/triage/README.md
@@ -30,7 +30,7 @@ notification ingest); those build a `TriggerEnvelope` and call in.
`TriggerEvaluated` for every action. `drop`/`acknowledge` do no further
work. `react`/`escalate` first pass `ApprovalGate::intercept_audited` with
tool key `triage.react` / `triage.escalate`, then build a root
- `ParentExecutionContext` (`orchestration::parent_context::build_root_parent`)
+ `ParentExecutionContext` (`parent_context::build_root_parent`)
and run `trigger_reactor` or `orchestrator` as a direct one-shot agent turn
under the triage context.
4. Origin ([`origin.rs`](./origin.rs)): every caller scopes an `AgentTurnOrigin` around
diff --git a/crates/openhuman-core/src/triage/escalation.rs b/crates/openhuman-core/src/triage/escalation.rs
index 49f28f6850..7ffcf6b67c 100644
--- a/crates/openhuman-core/src/triage/escalation.rs
+++ b/crates/openhuman-core/src/triage/escalation.rs
@@ -17,7 +17,7 @@ use crate::core::runtime::DispatchCtx;
use anyhow::{anyhow, Context};
use crate::agent::harness::fork_context::ParentExecutionContext;
-use crate::agent::orchestration::parent_context::build_root_parent;
+use super::parent_context::build_root_parent;
use crate::agent_registry::host_definition::AgentDefinitionRegistry;
use crate::config::Config;
diff --git a/crates/openhuman-core/src/triage/mod.rs b/crates/openhuman-core/src/triage/mod.rs
index 6c9ce1bb7f..c9851d99a0 100644
--- a/crates/openhuman-core/src/triage/mod.rs
+++ b/crates/openhuman-core/src/triage/mod.rs
@@ -37,6 +37,7 @@ pub mod escalation;
pub mod evaluator;
pub mod events;
pub mod origin;
+pub(crate) mod parent_context;
pub mod routing;
pub mod runner;
pub mod trigger_reactor_prompt;
diff --git a/crates/openhuman-core/src/agent/orchestration/parent_context/builder.rs b/crates/openhuman-core/src/triage/parent_context.rs
similarity index 60%
rename from crates/openhuman-core/src/agent/orchestration/parent_context/builder.rs
rename to crates/openhuman-core/src/triage/parent_context.rs
index b35a195a29..0994b4d889 100644
--- a/crates/openhuman-core/src/agent/orchestration/parent_context/builder.rs
+++ b/crates/openhuman-core/src/triage/parent_context.rs
@@ -1,25 +1,9 @@
-//! Shared root [`ParentExecutionContext`] builder for controller-spawned
-//! orchestration tasks.
+//! Root [`ParentExecutionContext`] builder for triage escalation.
//!
-//! Background host tasks that spawn real sub-agents have **no** enclosing agent
-//! turn on the stack, so there is no live parent execution context for the spawn
-//! to inherit — a naive spawn fails with `NoParentContext`.
-//!
-//! The fix (proven in `triage::escalation::dispatch_target_agent`) is to build a
-//! *root* [`ParentExecutionContext`] from a config-built [`Agent`] and hand it,
-//! explicitly, to the loop that spawns. Every `spawn_agent` call then names this
-//! root, inheriting a real provider, tool registry, memory, and model — the same
-//! construction path `agent_chat` uses.
-//!
-//! [`with_root_parent`] is the single blessed entry point that builds the root
-//! and passes it to the surface's closure, so a surface can neither hand-roll the
-//! parent nor forget to supply one. Every background orchestration surface goes
-//! through it.
-//!
-//! This was originally inlined in the workflow engine; #3374 PR4 lifted it here
-//! so each surface reuses the exact same construction (and the single
-//! registry-initialisation defense) rather than carrying a second copy of the
-//! ~20-field context literal that could drift.
+//! Triage escalation has no enclosing agent turn on the stack, so there is no
+//! live parent execution context for its sub-agent dispatch to inherit. This
+//! builds the root context from a config-built [`Agent`] using the same path as
+//! `agent_chat`, including a real provider, tool registry, memory, and model.
use std::collections::HashSet;
use std::sync::Arc;
@@ -119,49 +103,3 @@ pub(crate) async fn build_root_parent(
host_env: agent.host_env().clone(),
})
}
-
-/// Build (or accept) the parent execution context for a **controller-spawned
-/// background orchestration surface** that has no enclosing agent turn (the
-/// cron jobs), then run
-/// `run(parent)` with it.
-///
-/// Folds [`build_root_parent`] and the hand-off into one call so a surface
-/// cannot supply a hand-rolled parent, and cannot *forget* to supply one and
-/// have every nested `spawn_subagent` die at runtime with
-/// [`SubagentRunError::NoParentContext`](crate::agent::subagent_host::SubagentRunError::NoParentContext).
-/// The parent is a value the closure receives and passes to the spawns it makes
-/// (the host sub-agent dispatch path); nothing reads it ambiently.
-///
-/// `parent_override` is the explicit injection point for a parent the caller
-/// already has (a test driving a surface under a mock parent, and thus a mock
-/// provider, hermetically): when `Some`, it is used unchanged and no root is
-/// built. Production surfaces pass `None` and a root is built from `config`.
-///
-/// Returns the closure's output on success, or the [`build_root_parent`] error
-/// when the root context can't be constructed — the caller decides how to
-/// degrade (fail the run, or fall back to an un-grounded path).
-pub(crate) async fn with_root_parent<F, Fut>(
- ctx: &crate::core::runtime::DispatchCtx,
- parent_override: Option<ParentExecutionContext>,
- config: &Config,
- agent_definition_id: &str,
- channel: &str,
- session_prefix: &str,
- run: F,
-) -> Result<Fut::Output>
-where
- F: FnOnce(ParentExecutionContext) -> Fut,
- Fut: std::future::Future,
-{
- let parent = match parent_override {
- Some(parent) => parent,
- None => {
- build_root_parent(ctx, config, agent_definition_id, channel, session_prefix).await?
- }
- };
- Ok(run(parent).await)
-}
-
-#[cfg(test)]
-#[path = "builder_tests.rs"]
-mod tests;