Skip to content

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

feat(session_host): enable headless descendant settlement

Steven Enamakel2eda85244424
diff --git a/crates/openhuman-core/src/agent/session_host/builder/builder_build.rs b/crates/openhuman-core/src/agent/session_host/builder/builder_build.rs
index eb95041ecd..1cacccc621 100644
--- a/crates/openhuman-core/src/agent/session_host/builder/builder_build.rs
+++ b/crates/openhuman-core/src/agent/session_host/builder/builder_build.rs
@@ -433,6 +433,7 @@ impl SessionHostBuilder {
task_recency_window: None,
autonomous_iter_cap: None,
host_env: crate::agent::turn_env::HostTurnEnv::default(),
+ settle_headless_descendants: false,
thread_id: None,
agent_definition_name: agent_definition_name.clone(),
// Canonical registry id — captured here at build time
diff --git a/crates/openhuman-core/src/agent/session_host/runtime/accessors/runtime.rs b/crates/openhuman-core/src/agent/session_host/runtime/accessors/runtime.rs
index 3f244ff73c..b7d5783a74 100644
--- a/crates/openhuman-core/src/agent/session_host/runtime/accessors/runtime.rs
+++ b/crates/openhuman-core/src/agent/session_host/runtime/accessors/runtime.rs
@@ -1,6 +1,10 @@
use super::*;
impl OpenHumanSessionHost {
+ pub(crate) fn enable_headless_descendant_settlement(&mut self) {
+ self.settle_headless_descendants = true;
+ }
+
/// Restricts integration task-fetch tools to tasks touched within `window`
/// on every later turn of this agent; `None` clears the restriction.
pub fn set_task_recency_window(&mut self, window: Option<std::time::Duration>) {
diff --git a/crates/openhuman-core/src/agent/session_host/runtime_session_turn.rs b/crates/openhuman-core/src/agent/session_host/runtime_session_turn.rs
index de62640755..0d425b3753 100644
--- a/crates/openhuman-core/src/agent/session_host/runtime_session_turn.rs
+++ b/crates/openhuman-core/src/agent/session_host/runtime_session_turn.rs
@@ -42,7 +42,27 @@ impl OpenHumanSessionHost {
origin,
)
.await?;
- let mut context = OpenHumanRunContext::new().with_host_env(&self.host_env);
+ let mut host_env = self.host_env.clone();
+ let headless = self.settle_headless_descendants;
+ let root_cancellation = if headless {
+ let cancellation = host_env
+ .cancellation
+ .as_ref()
+ .map(tinyagents_harness::cancel::CancellationToken::child_token)
+ .unwrap_or_default();
+ host_env.cancellation = Some(cancellation.clone());
+ if host_env.turn_deadline.is_none() {
+ host_env.turn_deadline = Some(
+ tinyagents_harness::turn_deadline::TurnDeadline::starting_now(
+ std::time::Duration::from_secs(900),
+ ),
+ );
+ }
+ Some(RootRunCancellationGuard(cancellation))
+ } else {
+ None
+ };
+ let mut context = OpenHumanRunContext::new().with_host_env(&host_env);
context.untrusted_input_turn = self.untrusted_input;
context.origin = origin.cloned();
context.approval = approval;
@@ -59,6 +79,26 @@ impl OpenHumanSessionHost {
// down before it instead of being dropped by it.
let cancellation = context.cancellation.clone();
let root_config = context.root_run_config("openhuman-session");
+ let settlement_deadline = host_env.turn_deadline.map(|deadline| {
+ tokio::time::Instant::from_std(deadline.started() + deadline.backstop())
+ });
+ let descendant_lease = if headless {
+ let dispatch = context.dispatch_ctx();
+ let jobs = crate::core::runtime::slot_for::<
+ tinyagents_harness_tools::subagents::SubAgentJobRegistry,
+ >(&dispatch);
+ let owner = crate::agent::tinyagents::tool_registration::subagent_owner_key(
+ &self.workspace_dir,
+ &self.event_session_id,
+ self.thread_id.as_deref(),
+ );
+ Some(
+ jobs.retain_root_run_descendants(&root_config.run_id, owner)
+ .map_err(|error| anyhow::anyhow!("retain headless sub-agent results: {error}"))?,
+ )
+ } else {
+ None
+ };
let mut options = TurnOptions {
request_id: origin.and_then(|origin| match origin {
crate::security::turn_origin::AgentTurnOrigin::WebChat { request_id, .. } => {
@@ -141,10 +181,51 @@ impl OpenHumanSessionHost {
SessionTurnRequest::new(user_message_from_text(staged.as_str())),
options,
);
- let outcome = Box::pin(turn)
- .await
- .map_err(|error| anyhow::anyhow!(error.to_string()))?;
- Ok(outcome.output.unwrap_or_default())
+ let outcome = match Box::pin(turn).await {
+ Ok(outcome) => outcome,
+ Err(error) => {
+ drop(descendant_lease);
+ drop(root_cancellation);
+ return Err(anyhow::anyhow!(error.to_string()));
+ }
+ };
+ let mut output = outcome.output.unwrap_or_default();
+ if let Some(lease) = descendant_lease {
+ let deadline = settlement_deadline.expect("headless turns always have a deadline");
+ let jobs = lease
+ .settle(deadline, &cancellation)
+ .await
+ .map_err(|error| anyhow::anyhow!("settle headless sub-agent results: {error}"))?;
+ for job in jobs {
+ match job.status {
+ tinyagents_orchestration::subagent::SubAgentJobStatus::Completed => {
+ if let Some(child_output) = job.output.filter(|text| !text.trim().is_empty()) {
+ output.push_str("\n\n[Sub-agent result: ");
+ output.push_str(&job.agent);
+ output.push_str("]\n");
+ output.push_str(&child_output);
+ }
+ }
+ status => {
+ return Err(anyhow::anyhow!(
+ "headless sub-agent '{}' ended with {status:?}: {}",
+ job.agent,
+ job.error.unwrap_or_else(|| "no error details".to_string())
+ ));
+ }
+ }
+ }
+ }
+ drop(root_cancellation);
+ Ok(output)
+ }
+}
+
+struct RootRunCancellationGuard(tinyagents_harness::cancel::CancellationToken);
+
+impl Drop for RootRunCancellationGuard {
+ fn drop(&mut self) {
+ self.0.cancel();
}
}
diff --git a/crates/openhuman-core/src/agent/session_host/types.rs b/crates/openhuman-core/src/agent/session_host/types.rs
index d5526f63f3..b13e367d9d 100644
--- a/crates/openhuman-core/src/agent/session_host/types.rs
+++ b/crates/openhuman-core/src/agent/session_host/types.rs
@@ -293,6 +293,9 @@ pub struct OpenHumanSessionHost {
/// Per-turn host environment (budget, cancellation, deadline, hooks, ...)
/// handed in by the entry point; copied onto every turn's run context.
pub(super) host_env: crate::agent::turn_env::HostTurnEnv,
+ /// Whether this specific single-shot host turn should settle all native
+ /// driver descendants before returning its result. Normal chat stays async.
+ pub(super) settle_headless_descendants: bool,
/// Backend/session thread explicitly owned by this agent run. It is kept
/// separate from event identity: CLI and worker event sessions are not
/// necessarily user conversation threads.
diff --git a/crates/openhuman-core/src/flows/tinyflows/caps/agent.rs b/crates/openhuman-core/src/flows/tinyflows/caps/agent.rs
index a7867e49b1..70a17f3597 100644
--- a/crates/openhuman-core/src/flows/tinyflows/caps/agent.rs
+++ b/crates/openhuman-core/src/flows/tinyflows/caps/agent.rs
@@ -319,18 +319,11 @@ impl OpenHumanAgentRunner {
/// a custom flow agent's model pin (e.g. `hint:reasoning`) silently
/// dropped to the default chat model once routed through the harness.
///
- /// **Synchronous only (B40 / Gap 4).** A flow `agent` node runs here with
- /// no explicit chat thread on its run context. If the
- /// agent it runs is a delegating agent (e.g. the orchestrator) and
- /// calls `spawn_subagent` directly, the tool now refuses (see the
- /// `parent_thread_id.is_none()` guard in
- /// `agent_orchestration::tools::spawn_subagent`) rather than
- /// silently discarding the background result once it finishes —
- /// `background_delivery` has nowhere to deliver it without a thread id.
- /// This module does not bridge async subagent delivery into flow runs.
- /// For work that needs to happen in parallel, model it as parallel flow
- /// nodes (the tinyflows engine already fans those out) instead of
- /// reaching for a background sub-agent from inside a single node.
+ /// **Headless settlement.** A flow `agent` node has no chat thread, so it
+ /// opts its fresh session into bounded descendant settlement: the native
+ /// `spawn_subagent` call remains asynchronous, then this runner waits for
+ /// the root-owned descendant tree and folds completed child output into
+ /// the node result before returning.
async fn run_via_harness(
&self,
dispatch: &crate::core::runtime::DispatchCtx,
@@ -397,6 +390,7 @@ impl OpenHumanAgentRunner {
))
})?;
agent.set_agent_definition_name(agent_ref.to_string());
+ agent.enable_headless_descendant_settlement();
let prompt = build_harness_run_prompt(&request);
@@ -418,6 +412,13 @@ impl OpenHumanAgentRunner {
let effective_iteration_cap = agent.agent_config().max_tool_iterations;
let timeout_secs =
resolve_run_timeout_secs(requested_timeout_secs, effective_iteration_cap);
+ let deadline = tinyagents_harness::turn_deadline::TurnDeadline::starting_now(
+ std::time::Duration::from_secs(timeout_secs),
+ );
+ let absolute_deadline = tokio::time::Instant::from_std(deadline.started() + deadline.backstop());
+ let mut host_env = agent.host_env().clone();
+ host_env.turn_deadline = Some(deadline);
+ agent.set_host_env(host_env);
tracing::debug!(
target: "flows",
@@ -483,7 +484,7 @@ impl OpenHumanAgentRunner {
None => run,
};
let final_text =
- match tokio::time::timeout(std::time::Duration::from_secs(timeout_secs), run).await {
+ match tokio::time::timeout_at(absolute_deadline, run).await {
Ok(Ok(text)) => text,
Ok(Err(e)) => {
tracing::warn!(