Skip to content

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

refactor(subagent_host): update runner dispatching logic and naming

Steven Enamakeldb87d9d38726
diff --git a/crates/openhuman-core/src/agent/subagent_host/ops/mod.rs b/crates/openhuman-core/src/agent/subagent_host/ops/mod.rs
index 5ba62474b4..7b60a9c2c4 100644
--- a/crates/openhuman-core/src/agent/subagent_host/ops/mod.rs
+++ b/crates/openhuman-core/src/agent/subagent_host/ops/mod.rs
@@ -1,7 +1,7 @@
//! Sub-agent execution entry points.
//!
-//! The public runner lives in [`run_subagent`]. It dispatches to
-//! [`runner::run_typed_mode`] (narrow prompt + filtered tools) which builds a
+//! The registered dispatcher reaches this adapter, which dispatches to
+//! [`runner::run_typed_mode`] (narrow prompt + filtered tools) to build a
//! brand-new system prompt and a filtered tool list for the requested
//! archetype, then drives the turn through the tinyagents harness
//! ([`graph::run_subagent_via_graph`]) until the model returns without
@@ -13,7 +13,7 @@
//! | ------------------- | -------------------------------------------------------------- |
//! | `provider.rs` | `resolve_subagent_source`, `user_is_signed_in_to_composio` |
//! | `prompt.rs` | Child role framing and artifact-offload contract |
-//! | `runner.rs` | `run_subagent`, `run_typed_mode` |
+//! | `runner.rs` | direct host execution and `run_typed_mode` |
//! | `graph.rs` | `run_subagent_via_graph` — the sub-agent turn graph + tools |
//! | `checkpoint.rs` | `SubagentCheckpoint` — cap-hit summary |
//! | `pause_checkpoint.rs` | `is_safe_task_id` — validates model-provided checkpoint names |
diff --git a/crates/openhuman-core/src/agent/subagent_host/ops/pause_checkpoint.rs b/crates/openhuman-core/src/agent/subagent_host/ops/pause_checkpoint.rs
index ca14030bfc..cbdf9da0ef 100644
--- a/crates/openhuman-core/src/agent/subagent_host/ops/pause_checkpoint.rs
+++ b/crates/openhuman-core/src/agent/subagent_host/ops/pause_checkpoint.rs
@@ -6,8 +6,8 @@
/// Whether `task_id` is usable as a single filename component.
///
-/// This is untrusted input on its way into a path join. `continue_subagent`
-/// takes `task_id` straight from its tool arguments — which the model authors —
+/// This is untrusted input on its way into a path join. The same-key async
+/// spawn takes `task_id` straight from its tool arguments — which the model authors —
/// and passes it back through `SubagentRunOptions::task_id`, so a re-paused
/// child writes its checkpoint under a name the model chose. Without this,
/// `../../../../tmp/pwn` walks the write clean out of the checkpoint directory.
diff --git a/crates/openhuman-core/src/agent/subagent_host/ops/runner.rs b/crates/openhuman-core/src/agent/subagent_host/ops/runner.rs
index 1d6a858461..b6a66d052a 100644
--- a/crates/openhuman-core/src/agent/subagent_host/ops/runner.rs
+++ b/crates/openhuman-core/src/agent/subagent_host/ops/runner.rs
@@ -1,7 +1,7 @@
//! Top-level sub-agent run entry points.
//!
-//! [`run_subagent`] is the primary entry point for agent delegation and
-//! dispatches to [`run_typed_mode`] which builds a brand-new system prompt
+//! The registered dispatcher reaches this adapter, which dispatches to
+//! [`run_typed_mode`] to build a brand-new system prompt
//! and a filtered tool list for the requested archetype, then drives provider
//! calls and tool execution until the model returns without further tool calls
//! (or the iteration budget is exhausted).
@@ -82,7 +82,7 @@ pub(super) fn tier_gate_decision(
Ok(())
}
-/// Run a sub-agent based on its definition and a task prompt.
+/// Execute a prepared sub-agent based on its definition and a task prompt.
///
/// Creates a task id, checks the root-turn dispatch budget, reads the parent's
/// [`ParentExecutionContext`], then dispatches to `run_typed_mode`.
@@ -97,13 +97,13 @@ pub(crate) async fn run_subagent_direct_with_native_context(
mut options: SubagentRunOptions,
native: crate::agent::tinyagents::NativeSubagentRunContext,
) -> Result<SubagentRunOutcome, SubagentRunError> {
- // Unconditionally heap-allocate the entire run_subagent body so
+ // Unconditionally heap-allocate the entire child execution body so
// every caller doesn't have to carry this future's state inline.
// Tools that delegate run inside the parent agent's already-deep
// turn poll (the boxed tinyagents harness drive future in
// `TurnSpec::run`), so the parent's stack would
// otherwise pile (parent turn state + dispatch_subagent state +
- // run_subagent's wrapper state + run_typed_mode state + child turn
+ // dispatcher state + run_typed_mode state + child turn
// state) onto tokio's 2 MiB worker stack and abort with "thread
// 'tokio-rt-worker' has overflowed its stack, fatal runtime error:
// stack overflow" — observed at `[subagent_host] dispatching
@@ -362,7 +362,7 @@ pub(crate) async fn run_subagent_direct_with_native_context(
.await
}
-/// One spawn's snapshot of the host config, loaded once by [`run_subagent`].
+/// One spawn's snapshot of the host config, loaded once by the host adapter.
///
/// `Config::load_or_init()` is **not cached** — it re-resolves the config dirs
/// and re-reads `config.toml` on every call. `run_typed_mode` needed it in six
@@ -871,7 +871,7 @@ async fn run_typed_mode(
failure_cause,
final_history: history,
usage,
- // Filled in by `run_subagent` once the offload step has had its say, so
+ // Filled in by the host adapter once the offload step has had its say, so
// both the harness-offloaded and worker-authored pointers are counted.
artifact_paths: Vec::new(),
persistence_disposition:
diff --git a/crates/openhuman-core/src/agent/subagent_host/ops/runner_checkpoint_tests.rs b/crates/openhuman-core/src/agent/subagent_host/ops/runner_checkpoint_tests.rs
index 5e8db856bd..f6aab4572b 100644
--- a/crates/openhuman-core/src/agent/subagent_host/ops/runner_checkpoint_tests.rs
+++ b/crates/openhuman-core/src/agent/subagent_host/ops/runner_checkpoint_tests.rs
@@ -26,7 +26,7 @@ fn checkpoint_data(task_id: &str) -> SubagentCheckpointData {
// ── task_id is untrusted on its way into a path (tinysweeper, #5951) ────────
//
-// `continue_subagent` takes `task_id` from its tool arguments — model-authored
+// The same-key async spawn takes `task_id` from its tool arguments — model-authored
// — and feeds it back through `SubagentRunOptions::task_id`, so a re-paused
// child writes a checkpoint under a name the model chose. Joined unchecked,
// `../` walks the write out of the checkpoint directory entirely.
diff --git a/crates/openhuman-core/src/agent/subagent_host/types.rs b/crates/openhuman-core/src/agent/subagent_host/types.rs
index b2e89c2c99..41b2f35036 100644
--- a/crates/openhuman-core/src/agent/subagent_host/types.rs
+++ b/crates/openhuman-core/src/agent/subagent_host/types.rs
@@ -89,8 +89,8 @@ pub enum SubagentRunStatus {
/// The sub-agent completed normally with a final response.
Completed,
/// The sub-agent called `ask_user_clarification` and is waiting
- /// for the orchestrator to relay the user's answer via
- /// `continue_subagent`.
+ /// for the orchestrator to relay the user's answer via a same-key async
+ /// spawn.
AwaitingUser {
question: String,
options: Option<Vec<String>>,
@@ -102,8 +102,8 @@ pub enum SubagentRunStatus {
/// failure in the runner was logged at `warn` and then reported as an
/// ordinary `AwaitingUser` anyway. The orchestrator relayed a question
/// and a `task_id`, and the failure only surfaced much later, when the
- /// user had already answered and `continue_subagent` found nothing on
- /// disk. Carrying the outcome here is what makes a failed write
+ /// user had already answered and the next spawn found nothing on disk.
+ /// Carrying the outcome here is what makes a failed write
/// visible at pause time rather than at resume time (#5928).
///
/// `None` does not mean resumption is impossible: a sub-agent with a