Skip to content

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

docs(orchestration): align sub-agent docs and tests with delivery behaviour

Steven Enamakel9ab4d73ecd8c
diff --git a/crates/openhuman-core/src/agent/orchestration/README.md b/crates/openhuman-core/src/agent/orchestration/README.md
index f51e302d34..8330af6160 100644
--- a/crates/openhuman-core/src/agent/orchestration/README.md
+++ b/crates/openhuman-core/src/agent/orchestration/README.md
@@ -8,8 +8,8 @@ and UI-facing projections.
## Responsibilities
-- Host adapters that dispatch work through `agent::subagent_host::run_subagent`.
-- Background sub-agent task tracking, cancellation, steering, completion
+- Host adapters for detached spawns and durable session reuse.
+- 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.
@@ -21,7 +21,7 @@ and UI-facing projections.
- `background_completions.rs`, `completion_notice.rs`, and
`background_delivery.rs`: host delivery policy over TinyAgents completion
routing.
-- `subagent_control.rs`: manual cancel RPC.
+- `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.
@@ -52,4 +52,4 @@ sandbox context, spawn depth, and progress derive from the parent
- `agent/registration.rs` registers the callable tools; `tools::ops` composes that family.
- `threads` cancels detached work when a thread closes.
- `crate::core::all` registers the remaining controller pairs.
-- The frontend uses the background run and sub-agent controls.
+- The frontend uses the background run and sub-agent cancellation controls.
diff --git a/crates/openhuman-core/src/agent/orchestration/background_completions_pause_tests.rs b/crates/openhuman-core/src/agent/orchestration/background_completions_pause_tests.rs
index 1ebacd754c..7ba9fccf1a 100644
--- a/crates/openhuman-core/src/agent/orchestration/background_completions_pause_tests.rs
+++ b/crates/openhuman-core/src/agent/orchestration/background_completions_pause_tests.rs
@@ -202,9 +202,8 @@ fn repeated_pauses_are_distinct_and_inline_collection_sweeps_them() {
.collect();
assert_eq!(pause_ids.len(), 2, "each pause gets a unique router key");
- assert!(mark_collected(w, "sub-repeat-pause"));
assert!(
- pending_for(w, "thread-repeat-pause").is_empty(),
- "collecting the final result also withdraws its queued pause notices"
+ pending_for(w, "thread-repeat-pause").len() == 3,
+ "pause notices and the final result remain available for automatic delivery"
);
}
diff --git a/crates/openhuman-core/src/agent/orchestration/subagent_events.rs b/crates/openhuman-core/src/agent/orchestration/subagent_events.rs
index 1741a7a488..0bb8cfdc87 100644
--- a/crates/openhuman-core/src/agent/orchestration/subagent_events.rs
+++ b/crates/openhuman-core/src/agent/orchestration/subagent_events.rs
@@ -3,9 +3,8 @@
//! Sub-agent lifecycle (`SubagentSpawned` / `SubagentCompleted` /
//! `SubagentFailed` / `SubagentAwaitingUser`) used to be hand-constructed and
//! `publish_global`-ed inline across every turn/orchestration path
-//! (`tools/dispatch.rs`, `tools/spawn_subagent.rs`,
-//! `tools/spawn_subagent.rs`, and `tools/continue_subagent.rs`). That scattered
-//! the ordering/rate-limiting decision across many call sites.
+//! (`tools/dispatch.rs` and the single `tools/spawn_subagent` surface). That
+//! scattered the ordering/rate-limiting decision across many call sites.
//!
//! This module centralizes construction + publish so there is exactly one place
//! future ordering / rate-limiting / journal-mirroring will hook. It is a pure
diff --git a/crates/openhuman-core/src/agent/orchestration/tools/spawn_subagent_surface.rs b/crates/openhuman-core/src/agent/orchestration/tools/spawn_subagent_surface.rs
index 9f1f249e85..66e15194aa 100644
--- a/crates/openhuman-core/src/agent/orchestration/tools/spawn_subagent_surface.rs
+++ b/crates/openhuman-core/src/agent/orchestration/tools/spawn_subagent_surface.rs
@@ -379,9 +379,8 @@ fn finish_spawn_registration(
/// Format the user-facing acceptance text around a structured async sub-agent reference.
///
-/// The wording follows what the parent can actually do: a parent without
-/// `wait_subagent` (the orchestrator, #5701) is told the result arrives on its
-/// own and not to poll, instead of being invited to "wait for completion".
+/// The wording follows the tool contract: the child runs asynchronously and
+/// its result arrives through the parent's completion channel.
fn format_async_subagent_accepted(agent_id: &str, payload_json: &str) -> String {
format!(
"Accepted async sub-agent `{agent_id}`. Its result is delivered automatically. To continue or answer a clarification, call `spawn_subagent` again with the same task_key.