Skip to content

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

refactor(agent): update subagent execution APIs and documentation

Steven Enamakel7a3580cfd640
diff --git a/crates/openhuman-core/src/agent/README.md b/crates/openhuman-core/src/agent/README.md
index b644d96637..7439204688 100644
--- a/crates/openhuman-core/src/agent/README.md
+++ b/crates/openhuman-core/src/agent/README.md
@@ -188,7 +188,7 @@ The `agent_id` argument selects an allowlisted `AgentDefinition`; the same
orchestration/tools/spawn_subagent.rs
| read ParentExecutionContext (run context `parent`, harness/fork_context.rs)
v
- subagent_host::run_subagent_with_parent
+ registered async sub-agent dispatcher
| resolve definition, model, narrowed tools, narrowed prompt,
| workspace/sandbox, SubagentScope for progress
v
diff --git a/crates/openhuman-core/src/agent/harness/README.md b/crates/openhuman-core/src/agent/harness/README.md
index 79e928cb82..413295f786 100644
--- a/crates/openhuman-core/src/agent/harness/README.md
+++ b/crates/openhuman-core/src/agent/harness/README.md
@@ -63,8 +63,8 @@ recency belongs to ``OpenHumanRunExt` (agent/tinyagents/host/run_context.rs)`.
Adjacent public surface that lives in sibling modules, not here:
`OpenHumanSessionHost`/`SessionHostBuilder`/`TurnOverrides` and the `Agent`
-turn lifecycle are in `../session_host/`; `run_subagent`,
-`SubagentRunOptions`, `SubagentRunError` are in `../subagent_host/`;
+turn lifecycle are in `../session_host/`; `OpenHumanSubagentHost`,
+`SubagentRunOptions`, and `SubagentRunError` are in `../subagent_host/`;
`LastTurnUsage`/`SubagentUsageEntry` are in [`../tinyagents/host/run_context.rs`](../tinyagents/host/run_context.rs).
## Dependencies
diff --git a/crates/openhuman-core/src/agent/harness/test_support.rs b/crates/openhuman-core/src/agent/harness/test_support.rs
index b573b3ffe9..8fc7474d43 100644
--- a/crates/openhuman-core/src/agent/harness/test_support.rs
+++ b/crates/openhuman-core/src/agent/harness/test_support.rs
@@ -56,7 +56,7 @@ pub(crate) fn test_main_def() -> AgentDefinition {
/// prompt. Inherit means the runner uses `parent.provider` verbatim,
/// so a test's scripted `MockProvider` reaches the sub-agent loop —
/// which is exactly what the full-path spawn test needs to assert the
-/// dispatch → run_subagent → result-threading chain end to end.
+/// dispatch → detached child execution → result-threading chain end to end.
/// Provider *routing* for `Hint` sub-agents is covered separately by
/// `subagent_host::ops::tests::resolve_subagent_source_*`.
#[cfg(test)]
diff --git a/crates/openhuman-core/src/security/turn_origin.rs b/crates/openhuman-core/src/security/turn_origin.rs
index f5ec94d60a..548fd547db 100644
--- a/crates/openhuman-core/src/security/turn_origin.rs
+++ b/crates/openhuman-core/src/security/turn_origin.rs
@@ -289,7 +289,7 @@ pub async fn with_inherited_origin<F: std::future::Future>(
/// when the returned future is first polled:
///
/// ```ignore
-/// tokio::spawn(turn_origin::propagate(async move { run_subagent(..).await }));
+/// tokio::spawn(turn_origin::propagate(async move { prepared_host.run(&parent, input).await }));
/// ```
///
/// Fail-closed is preserved: with no ambient origin nothing is scoped, so the
diff --git a/docs/gitbooks/en/developing/architecture/agent-harness.md b/docs/gitbooks/en/developing/architecture/agent-harness.md
index 0bbb0cec2a..3b42cb0679 100644
--- a/docs/gitbooks/en/developing/architecture/agent-harness.md
+++ b/docs/gitbooks/en/developing/architecture/agent-harness.md
@@ -93,7 +93,7 @@ Some settings remain runtime-wide for every agent (the live autonomy policy's
config sub-agents re-read); the crate README lists them under "Still
runtime-wide".
-Every agent turn runs through the published [`tinyagents`](https://crates.io/crates/tinyagents) harness. There are three entry points: `Agent::turn`, the channel and CLI bus path, and `run_subagent`. All of them go through the adapter seam in [`crates/openhuman-core/src/agent/tinyagents/`](https://github.com/tinyhumansai/openhuman/tree/main/crates/openhuman-core/src/agent/tinyagents) (`TurnSpec::run`). Context trimming is `MessageTrimMiddleware`, and cancellation is the tinyagents steering channel. Policy stop hooks (budget, thread-goal and iteration caps) use the upstream `tinyagents-hooks` `StopHookMiddleware` and pause the run on the first stop vote. The channel route forwards live `AgentProgress` like the chat route. The shared `TurnProgress` seam lives in `agent/session_host/tool_progress.rs`.
+Every agent turn runs through the published [`tinyagents`](https://crates.io/crates/tinyagents) harness. Entry points include `Agent::turn`, the channel and CLI bus path, detached async sub-agent dispatch, and direct triage turns through `agent_chat_for`. They converge on the adapter seam in [`crates/openhuman-core/src/agent/tinyagents/`](https://github.com/tinyhumansai/openhuman/tree/main/crates/openhuman-core/src/agent/tinyagents) (`TurnSpec::run`). Context trimming is `MessageTrimMiddleware`, and cancellation is the tinyagents steering channel. Policy stop hooks (budget, thread-goal and iteration caps) use the upstream `tinyagents-hooks` `StopHookMiddleware` and pause the run on the first stop vote. The channel route forwards live `AgentProgress` like the chat route. The shared `TurnProgress` seam lives in `agent/session_host/tool_progress.rs`.
Concurrent work uses separate async sub-agent requests. Detached sub-agent
tasks retain host policy, progress, and product projections; TinyAgents owns
@@ -474,7 +474,7 @@ Why the rules.
Enforcement. Two layers:
1. Loader-time (static). `tinyagents_definition::DefinitionSet::validate_tier_hierarchy` runs over the merged registry (built-ins + workspace TOMLs) and refuses to boot a registry that lists a same-tier or worker-with-subagents entry. Built-in archetypes are checked during loading; user-shipped TOMLs are checked at workspace load.
-2. Runtime depth gate (dynamic). Independent of tier, the sub-agent runner caps total spawn chain depth at `MAX_SPAWN_DEPTH = 3` via a task-local counter incremented across `run_subagent`, surfaced as a `SpawnDepthExceeded` agent error. This makes a user-shipped TOML that drops the tier annotation still unable to recurse past three hops.
+2. Runtime depth gate (dynamic). Independent of tier, child execution caps total spawn chain depth at `MAX_SPAWN_DEPTH = 3` via a task-local counter, surfaced as a `SpawnDepthExceeded` agent error. This makes a user-shipped TOML that drops the tier annotation still unable to recurse past three hops.
> Status: the loader-time tier check, `agent_tier` field, and runtime depth-counter task-local are live. Depth is bounded by both the static loader contract and the runtime `MAX_SPAWN_DEPTH = 3` guard.
diff --git a/tests/composio_list_tools_stack_overflow_regression.rs b/tests/composio_list_tools_stack_overflow_regression.rs
index 469cf65b17..5169296e27 100644
--- a/tests/composio_list_tools_stack_overflow_regression.rs
+++ b/tests/composio_list_tools_stack_overflow_regression.rs
@@ -109,7 +109,7 @@
use async_trait::async_trait;
use openhuman_core::agent::harness::ParentExecutionContext;
-use openhuman_core::agent::subagent_host::{run_subagent, SubagentRunOptions};
+use openhuman_core::agent::subagent_host::{OpenHumanSubagentHost, SubagentRunOptions};
use openhuman_core::agent_registry::host_definition::AgentDefinitionRegistry;
use openhuman_core::config::AgentConfig;
use openhuman_core::integrations::composio::tools::ComposioListToolsTool;
@@ -420,7 +420,12 @@ async fn drive_subagent() {
// The parent is an explicit value on the run options, not ambient state.
let mut options = SubagentRunOptions::default();
options.run_context.parent = Some(parent);
- let _ = run_subagent(&def, "list available gmail actions", options).await;
+ let parent = options.run_context.clone().into_tinyagents(
+ tinyagents_harness::context::RunConfig::new("composio-stack-regression-subagent"),
+ );
+ let _ = OpenHumanSubagentHost::new(def, options)
+ .run(&parent, "list available gmail actions".into())
+ .await;
assert_eq!(
executions.load(std::sync::atomic::Ordering::SeqCst),
1,
diff --git a/tests/in_process/calendar_grounding_e2e.rs b/tests/in_process/calendar_grounding_e2e.rs
index 6cce66fb8b..fa081a32b7 100644
--- a/tests/in_process/calendar_grounding_e2e.rs
+++ b/tests/in_process/calendar_grounding_e2e.rs
@@ -215,12 +215,12 @@ async fn test_subagent_has_current_date_context() -> Result<()> {
// The parent is an explicit value on the run options, not ambient state.
let mut options = openhuman_core::agent::subagent_host::SubagentRunOptions::default();
options.run_context.parent = Some(parent);
- let _ = openhuman_core::agent::subagent_host::run_subagent(
- &def,
- "list my calendar events for today",
- options,
- )
- .await;
+ let parent = options.run_context.clone().into_tinyagents(
+ tinyagents_harness::context::RunConfig::new("calendar-grounding-subagent-test"),
+ );
+ let _ = openhuman_core::agent::subagent_host::OpenHumanSubagentHost::new(def, options)
+ .run(&parent, "list my calendar events for today".into())
+ .await;
let messages = captured_messages.lock();
// Use substring search on all user messages