Skip to content

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

docs(agent-harness): document completion delivery and spawn options

Steven Enamakelcafc7aebfaef
diff --git a/crates/openhuman-core/src/agent/orchestration/tools/tools_e2e_tests.rs b/crates/openhuman-core/src/agent/orchestration/tools/tools_e2e_tests.rs
index a4ba3df120..9b6ccc9389 100644
--- a/crates/openhuman-core/src/agent/orchestration/tools/tools_e2e_tests.rs
+++ b/crates/openhuman-core/src/agent/orchestration/tools/tools_e2e_tests.rs
@@ -250,6 +250,10 @@ async fn failed_async_child_is_reported_to_the_parent_without_a_success_result()
})
.await
.expect("asynchronous child failure reaches the parent");
+ assert!(
+ failure.starts_with("spawn_subagent failed and did not complete."),
+ "failure copy remains recognizable to the parent: {failure}"
+ );
assert!(failure.contains("scripted provider outage"), "{failure}");
assert!(!failure.contains("completed successfully"), "{failure}");
}
diff --git a/docs/gitbooks/en/developing/architecture/agent-harness.md b/docs/gitbooks/en/developing/architecture/agent-harness.md
index 023f2b0bcb..c8b76377e9 100644
--- a/docs/gitbooks/en/developing/architecture/agent-harness.md
+++ b/docs/gitbooks/en/developing/architecture/agent-harness.md
@@ -439,7 +439,7 @@ neutral TinyAgents lifecycle:
The model-facing orchestration surface has one child tool: `spawn_subagent`. It always returns asynchronously and accepts `agent_id` to select a specialist. A matching `task_key` reuses the compatible durable child session; when that child is paused on clarification, another spawn with the same key resumes its checkpoint and preserves the original task identity. The child result is delivered to the parent chat when a delivery thread exists. Headless callers remain asynchronous and record completion in the run log.
-Former specialist delegation aliases are represented by `agent_id` values on `spawn_subagent`, so the model sees one spawn schema. The asynchronous result path delivers child completions to a parent chat when available; otherwise it records the result in the run log. Compatible follow-ups use the durable session keyed by `task_key`, and clarification checkpoints resume through the same spawn tool.
+The completion router deduplicates by task and holds a claimed batch until the delivery turn has been persisted. Failed delivery releases the batch for retry, and startup recovery drains completions that were not delivered before a restart. The OpenHuman host debounces nearby completions into one system turn and persists that reply under a deterministic run id before it publishes `chat_done`; the frontend can reuse that id without appending a duplicate row. If retries are exhausted, the host writes an undelivered notice into the thread. The completion store uses the caller's profile-scoped storage backend. A `workflow_proposal` in a child's history is also persisted as a parent-thread message so the frontend can restore the proposal after reload.
### Spawn hierarchy and tiers
diff --git a/docs/gitbooks/en/features/native-tools/agent-coordination.md b/docs/gitbooks/en/features/native-tools/agent-coordination.md
index 16b7e4ad13..37e7f0631c 100644
--- a/docs/gitbooks/en/features/native-tools/agent-coordination.md
+++ b/docs/gitbooks/en/features/native-tools/agent-coordination.md
@@ -17,7 +17,7 @@ Besides doing the work, the agent has tools for organizing it: planning multi-st
| `ask_user_clarification` | Pauses and asks you a precise question instead of guessing. |
| `plan_exit` | Leaves the planning phase and starts executing. |
-`spawn_subagent` accepts an `agent_id` to choose a specialist and an optional `model` to pin that child to a model for one call. If omitted, model selection uses the configured pin or normal routing hints. Calls return an asynchronous task reference; they do not wait for the child. Reusing the same `task_key` continues a compatible child and resumes a clarification-paused child when its checkpoint is available. Without a chat delivery thread, the child still runs asynchronously and its completion is recorded in the parent run log.
+`spawn_subagent` accepts an `agent_id` to choose a specialist, an optional `model` to pin that child to a model for one call, and an optional `task_key` to reuse a compatible child. If `model` is omitted, model selection uses the configured pin or normal routing hints. Calls return an asynchronous task reference; they do not wait for the child. Reusing the same `task_key` continues a compatible child and resumes a clarification-paused child when its checkpoint is available. Set `fresh: true` when the task needs a new child instead of reusing a matching session. Without a chat delivery thread, the child still runs asynchronously and its completion is recorded in the parent run log.
The returned task reference identifies the asynchronous child. Its result is delivered to the parent chat when a delivery thread is available; headless runs retain the result in the run log.