Skip to content

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

Merge remote-tracking branch 'upstream/main' into epic-7964-ci-green

Steven Enamakelb7349d7914b1
diff --cc crates/openhuman-core/src/channels/host/channel_events.rs
index 3899b1b8fc,0d11ebed0f..4d092bb505
--- a/crates/openhuman-core/src/channels/host/channel_events.rs
+++ b/crates/openhuman-core/src/channels/host/channel_events.rs
@@@ -175,33 -199,37 +175,44 @@@ impl EventHandler<DomainEvent> for Chan
}
/// Projects host turn lifecycle facts into module-owned remote status storage.
+///
+/// Turn state is written through the configured module object that owns the
+/// running providers. A process-wide client reaches a callback-only runtime
+/// with no running provider state, which would not report `remote_control` and
+/// so would silently drop every mark.
pub struct ChannelTurnStateSubscriber {
workspace_dir: PathBuf,
- channels: Arc<HashMap<String, Arc<dyn Channel>>>,
- config: Option<Arc<crate::config::Config>>,
+ objects: Option<Arc<HashMap<String, ModuleObjectClient>>>,
cancellation: tokio_util::sync::CancellationToken,
+ #[cfg(test)]
- test_marks: Option<Arc<Mutex<Vec<(String, String, bool, bool)>>>>,
++ test_marks: Option<TurnStateMarks>,
}
++
++/// Test record of each turn-state mark: channel, reply target, busy flag, and
++/// whether the module accepted the dispatch.
++#[cfg(test)]
++type TurnStateMarks = Arc<Mutex<Vec<(String, String, bool, bool)>>>;
impl ChannelTurnStateSubscriber {
- pub fn with_config(
- channels: Arc<HashMap<String, Arc<dyn Channel>>>,
- config: Arc<crate::config::Config>,
+ pub fn with_objects(
+ workspace_dir: PathBuf,
+ objects: Arc<HashMap<String, ModuleObjectClient>>,
) -> Self {
Self {
- workspace_dir: config.workspace_dir.clone(),
- channels,
- config: Some(config),
+ workspace_dir,
+ objects: Some(objects),
cancellation: super::super::runtime::session::channel_session(),
+ #[cfg(test)]
+ test_marks: None,
}
}
#[cfg(test)]
pub fn new(workspace_dir: PathBuf) -> Self {
Self {
workspace_dir,
- channels: Arc::new(HashMap::new()),
- config: None,
+ objects: None,
cancellation: tokio_util::sync::CancellationToken::new(),
+ #[cfg(test)]
+ test_marks: None,
}
}
async fn mark(&self, channel: &str, reply_target: &str, event_ws: &PathBuf, busy: bool) {
@@@ -211,47 -242,38 +222,59 @@@
{
return;
}
- #[cfg(test)]
- let client = if self.config.is_none() {
- crate::channels::module_fixture::client().await
- } else {
- crate::modules::client(self.config.as_deref().cloned().unwrap_or_default())
- };
- #[cfg(not(test))]
- let client = crate::modules::client(self.config.as_deref().cloned().unwrap_or_default());
- let result: Result<tinychannels_bus::module_remote::RemoteOperationResult, _> = client
- .call_confidential(
- "tinychannels",
- tinychannels_bus::methods::EXECUTE_REMOTE,
- (tinychannels_bus::module_remote::RemoteOperation::MarkTurn {
- workspace_dir: self.workspace_dir.to_string_lossy().into_owned(),
- channel: channel.into(),
- reply_target: reply_target.into(),
- busy,
- },),
- )
- .await;
+ let args = (tinychannels_bus::module_remote::RemoteOperation::MarkTurn {
+ workspace_dir: self.workspace_dir.to_string_lossy().into_owned(),
+ channel: channel.into(),
+ reply_target: reply_target.into(),
+ busy,
+ },);
+ let result: Result<tinychannels_bus::module_remote::RemoteOperationResult, _> =
+ match &self.objects {
+ Some(objects) => {
+ let Some(object) = objects
+ .get(channel)
+ .or_else(|| objects.get(tinychannels_bus::provider_id(channel)))
+ else {
+ tracing::debug!(
+ channel,
+ "[channels] turn state skipped: no configured module object"
+ );
+ return;
+ };
+ object
+ .call_confidential(tinychannels_bus::methods::EXECUTE_REMOTE, args)
+ .await
+ }
+ None => {
+ #[cfg(test)]
+ {
+ crate::channels::module_fixture::client()
+ .await
+ .call_confidential(
+ "tinychannels",
+ tinychannels_bus::methods::EXECUTE_REMOTE,
+ args,
+ )
+ .await
+ }
+ #[cfg(not(test))]
+ {
+ return;
+ }
+ }
+ };
+ #[cfg(test)]
+ if let Some(marks) = &self.test_marks {
+ marks
+ .lock()
+ .unwrap_or_else(|error| error.into_inner())
+ .push((
+ channel.to_owned(),
+ reply_target.to_owned(),
+ busy,
+ result.is_ok(),
+ ));
+ }
if result.is_err() {
tracing::debug!("channel turn status unavailable");
}
diff --cc crates/openhuman-core/src/channels/host/channel_events_tests.rs
index 54a875b583,6b2e29ab6e..24faf1955b
--- a/crates/openhuman-core/src/channels/host/channel_events_tests.rs
+++ b/crates/openhuman-core/src/channels/host/channel_events_tests.rs
@@@ -21,6 -61,48 +21,47 @@@ fn approval_subscriber
ChannelApprovalSurfaceSubscriber::new(Arc::new(map))
}
++/// A turn-state subscriber routed through the module object the runtime lease
++/// opened, as production routes through the configured module objects, with
++/// an in-memory record of every mark and whether its dispatch succeeded.
+ #[cfg(feature = "e2e-test-support")]
+ fn turn_state_subscriber(
+ workspace_dir: PathBuf,
+ names: &[&str],
-) -> (
- ChannelTurnStateSubscriber,
- Arc<StdMutex<Vec<(String, String, bool, bool)>>>,
-) {
- let channels: HashMap<String, Arc<dyn Channel>> = names
++ lease: &crate::modules::channel_runtime::ChannelRuntimeLease,
++) -> (ChannelTurnStateSubscriber, TurnStateMarks) {
++ let objects: HashMap<String, ModuleObjectClient> = names
+ .iter()
- .map(|name| {
- let channel = recording(name);
- ((*name).to_owned(), channel as Arc<dyn Channel>)
- })
++ .map(|name| ((*name).to_owned(), lease.object().clone()))
+ .collect();
- let mut subscriber = ChannelTurnStateSubscriber::new(workspace_dir);
- subscriber.channels = Arc::new(channels);
- let marks = Arc::new(StdMutex::new(Vec::new()));
++ let mut subscriber = ChannelTurnStateSubscriber::with_objects(workspace_dir, Arc::new(objects));
++ let marks = Arc::new(Mutex::new(Vec::new()));
+ subscriber.test_marks = Some(Arc::clone(&marks));
+ (subscriber, marks)
+ }
+
++#[cfg(feature = "e2e-test-support")]
+ struct TurnStateHostCallback;
+
++#[cfg(feature = "e2e-test-support")]
+ #[tinybus::interface(name = "ai.tinyhumans.tinychannels.ChannelsHost")]
+ impl TurnStateHostCallback {
+ async fn dispatch_controller_backend(
+ &self,
+ _request: tinychannels_bus::ChannelBackendRequest,
+ ) -> tinybus::Result<tinychannels_bus::ChannelBackendResult> {
+ Err(tinybus::Error::failed("unused turn-state callback"))
+ }
+ }
+
+ #[cfg(feature = "e2e-test-support")]
+ async fn open_turn_state_runtime() -> crate::modules::channel_runtime::ChannelRuntimeLease {
+ let client = crate::channels::module_fixture::client().await;
+ crate::modules::channel_runtime::ChannelRuntimeLease::open(client, TurnStateHostCallback)
+ .await
+ .expect("retain the host callback for remote turn-state calls")
+ }
+
fn received(channel: &str, reply_target: &str, thread_ts: Option<&str>, ws: &Path) -> DomainEvent {
DomainEvent::ChannelMessageReceived {
channel: channel.into(),
@@@ -153,9 -208,10 +162,10 @@@ async fn approvals_for_web_email_or_unr
#[cfg(feature = "e2e-test-support")]
async fn turn_state_marks_busy_for_every_remote_control_channel() {
let _storage = crate::channels::module_fixture::install_memory_storage();
+ let lease = open_turn_state_runtime().await;
let dir = tempdir().unwrap();
let ws = dir.path().to_path_buf();
- let sub = ChannelTurnStateSubscriber::new(ws.clone());
- let (sub, marks) = turn_state_subscriber(ws.clone(), &["telegram", "discord"]);
++ let (sub, marks) = turn_state_subscriber(ws.clone(), &["telegram", "discord"], &lease);
assert_eq!(sub.name(), "channels::turn_state");
assert_eq!(sub.domains(), Some(&["channel"][..]));
for channel in ["telegram", "discord"] {
@@@ -177,26 -234,25 +188,25 @@@
#[cfg(feature = "e2e-test-support")]
async fn turn_state_ignores_non_remote_channels_and_stale_workspaces() {
let _storage = crate::channels::module_fixture::install_memory_storage();
+ let lease = open_turn_state_runtime().await;
let dir = tempdir().unwrap();
let ws = dir.path().to_path_buf();
- let sub = ChannelTurnStateSubscriber::new(ws.clone());
- let (sub, marks) = turn_state_subscriber(ws.clone(), &["telegram"]);
++ let (sub, marks) = turn_state_subscriber(ws.clone(), &["telegram"], &lease);
let other = tempdir().unwrap().path().to_path_buf();
sub.handle(&received("email", "[email protected]", None, &ws)).await;
- assert!(remote_status(&ws, "email", "[email protected]").await.is_none());
+ assert!(marks.lock().unwrap().is_empty());
sub.handle(&received("telegram", "chat-1", None, &ws)).await;
- let busy = remote_status(&ws, "telegram", "chat-1")
- .await
- .expect("/status should answer after a received event");
- assert!(busy.contains("in progress"), "{busy}");
+ assert_eq!(
+ marks.lock().unwrap().as_slice(),
+ &[("telegram".into(), "chat-1".into(), true, true)]
+ );
sub.handle(&processed("telegram", "chat-1", &other)).await;
- let still_busy = remote_status(&ws, "telegram", "chat-1")
- .await
- .expect("/status should answer after a stale processed event");
- assert!(
- still_busy.contains("in progress"),
- "a stale workspace must not clear turn state: {still_busy}"
+ assert_eq!(
+ marks.lock().unwrap().len(),
+ 1,
+ "a stale workspace is ignored"
);
sub.handle(&processed("telegram", "chat-1", &ws)).await;
diff --cc crates/openhuman-core/src/channels/module_fixture_tests.rs
index c5c58774bf,38ea3cb9ad..20e7d3e155
--- a/crates/openhuman-core/src/channels/module_fixture_tests.rs
+++ b/crates/openhuman-core/src/channels/module_fixture_tests.rs
@@@ -176,9 -123,7 +176,8 @@@ async fn linked_module_prepares_legacy_
envelope: None,
},
namespace: "openhuman".into(),
+ preparation_mode: Default::default(),
session_policy: Default::default(),
- preparation_mode: Default::default(),
},),
)
.await
@@@ -195,7 -140,7 +194,7 @@@
);
assert_eq!(
response.session_key,
-- "openhuman:discord:default:unknown:room#b:thread/c"
++ "v22|namespace=p9:openhuman|channel=p7:discord|account=a|kind=p7:unknown|scope=a|conversation=p6:room#b|parent=a|topic=a|thread=p8:thread/c|participant=a"
);
assert_eq!(response.message.timestamp, 42);
assert_eq!(response.message.sender_name.as_deref(), Some("Display"));
diff --cc crates/openhuman-core/src/channels/runtime/dispatch/processor.rs
index 11541da91a,a8fb39a17a..890365c385
--- a/crates/openhuman-core/src/channels/runtime/dispatch/processor.rs
+++ b/crates/openhuman-core/src/channels/runtime/dispatch/processor.rs
@@@ -194,6 -144,7 +194,7 @@@ pub(crate) async fn run_message_dispatc
&& admitting.len() + admission_order.waiting() + held < budget => {
match received {
Some(message) => {
- tracing::debug!(channel = %message.message.channel.id, message_id = %message.message.message_id, "[dispatch] received module inbound message");
++ tracing::debug!(channel = %message.message.channel, message_id = %message.message.id, "[dispatch] received module inbound message");
let seq = next_seq;
next_seq += 1;
let handle = admitting.spawn(admit_runtime_message(Arc::clone(&ctx), message));
diff --cc crates/openhuman-core/src/channels/runtime/startup/callback.rs
index f1fc3e98c0,a1e69869ab..fe3af4aef0
--- a/crates/openhuman-core/src/channels/runtime/startup/callback.rs
+++ b/crates/openhuman-core/src/channels/runtime/startup/callback.rs
@@@ -109,14 -65,12 +109,15 @@@ impl ChannelHostCallbacks
#[tinybus::interface(name = "ai.tinyhumans.tinychannels.ChannelsHost")]
impl ChannelHostCallbacks {
async fn deliver_inbound(&self, channel: String, message: serde_json::Value) -> Result<()> {
+ tracing::debug!(channel, "[channels] module invoked inbound callback");
Self::validate_callback_size(&message)?;
- if let Ok(delivery) = serde_json::from_value::<
- tinychannels_bus::module_relay::RelayInboundDelivery,
- >(message.clone())
- {
+ let relay_shaped = message.get("envelope").is_some()
+ || message.get("delivered_via_authenticated_relay").is_some();
+ if relay_shaped {
+ let delivery = serde_json::from_value::<
+ tinychannels_bus::module_relay::RelayInboundDelivery,
+ >(message.clone())
+ .map_err(|_| Error::failed("invalid relay delivery"))?;
if delivery.envelope.channel.id != channel {
return Err(Error::failed(
"relay callback channel does not match envelope",
@@@ -129,58 -83,14 +130,59 @@@
return Ok(());
}
- let message: tinychannels_bus::ChannelInboundEnvelope = serde_json::from_value(message)
+ // v22 providers deliver the normalized envelope directly through the
+ // same host callback. Keep it intact until module preparation derives
+ // the legacy prompt projection and scoped identity. A typed-looking
+ // payload must never fall through and be reinterpreted as v21 text.
+ let typed_envelope = message
+ .get("channel")
+ .is_some_and(serde_json::Value::is_object)
+ || ["conversation", "parts", "access"]
+ .iter()
+ .any(|field| message.get(*field).is_some());
+ if typed_envelope {
+ let envelope: tinychannels_bus::ChannelInboundEnvelope =
+ serde_json::from_value(message)
+ .map_err(|_| Error::failed("invalid inbound envelope"))?;
+ let channel_present = !channel.trim().is_empty();
+ let provider_matches = envelope.channel.id == tinychannels_bus::provider_id(&channel);
+ let account_matches = envelope.channel.account_id.as_deref() == Some(channel.as_str());
+ let conversation_present = !envelope.conversation.id.trim().is_empty();
+ let message_present = !envelope.message_id.trim().is_empty();
+ tracing::debug!(
+ channel_present,
+ provider_matches,
+ account_matches,
+ conversation_present,
+ message_present,
+ "typed inbound envelope scope validation"
+ );
+ if !channel_present
+ || !provider_matches
+ || !account_matches
+ || envelope.message_id.trim().is_empty()
+ || envelope.conversation.id.trim().is_empty()
+ {
+ return Err(Error::failed("inbound envelope identity is invalid"));
+ }
+ self.dispatch
+ .send(RuntimeChannelMessage::with_inbound_envelope(
+ tinychannels_bus::ChannelMessage::default(),
+ envelope,
+ ))
+ .await
+ .map_err(|_| Error::failed("channel dispatch is closed"))?;
+ return Ok(());
+ }
+
+ let message: tinychannels_bus::ChannelMessage = serde_json::from_value(message)
.map_err(|_| Error::failed("invalid inbound message"))?;
- if message.channel.id != channel {
+ if message.channel != channel {
return Err(Error::failed("callback channel does not match message"));
}
- tracing::debug!(channel, message_id = %message.message_id, "[channels] module delivered inbound message");
++ tracing::debug!(channel, message_id = %message.id, "[channels] module delivered inbound message");
self.dispatch
- .send(RuntimeChannelMessage::with_inbound_envelope(message))
+ .send(RuntimeChannelMessage::from(message))
.await
.map_err(|_| Error::failed("channel dispatch is closed"))
}
diff --cc crates/openhuman-core/src/web_chat/turn_host.rs
index 3848cc2126,0000000000..13edb1ad1e
mode 100644,000000..100644
--- a/crates/openhuman-core/src/web_chat/turn_host.rs
+++ b/crates/openhuman-core/src/web_chat/turn_host.rs
@@@ -1,619 -1,0 +1,638 @@@
+//! The web chat's [`TurnHost`]: session checkout and the agent run.
+//!
+//! The runner decides when a turn starts, may be cancelled or has overrun;
+//! this port does what only OpenHuman can. [`checkout`](TurnHost::checkout)
+//! resolves the turn's config and working folder and takes the thread's cached
+//! session agent (or builds and cold-boot resumes one, `session.rs`).
+//! [`run`](TurnHost::run) drives the agent under the turn's origin and
+//! approval context, taps its progress stream for the runner (the idle guard's
+//! signals, the idle record and the event projection), applies the thread's
+//! budget correlation, speaks the reply when asked, and keeps the reply for
+//! the runner's reply store and terminal event. [`checkin`](TurnHost::checkin)
+//! returns a healthy agent to the cache, and drops a failed one so the next
+//! request cold-boots from the durable transcript.
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use async_trait::async_trait;
+use tinyagents_harness::run_queue::RunQueue;
+use tinyagents_harness::turn_runner::{
+ QueueDisposition, TurnHost, TurnRequest, TurnResult, TurnSession, TurnSignal, WorkTracker,
+};
+use tinyagents_harness::CancellationToken;
+use tinyinference_llm::failure::is_empty_provider_response_text;
+use tokio::sync::{mpsc, watch, Mutex as AsyncMutex};
+
+use super::ops::{self, BudgetCorrelation};
+use super::progress::ProgressProjection;
+use super::runner::{Admission, Shared};
+use super::session::{
+ checkin_session_agent, checkout_session_agent, normalize_model_override, CheckoutPolicy,
+};
+use super::surface::TurnIds;
+use super::types::WebChatTaskResult;
+use super::web_errors::{
+ inference_budget_exceeded_user_message, is_inference_budget_exceeded_error,
+};
+use crate::agent::queued_turn::QueuedPayload;
+use crate::core::events::DomainEvent;
+use crate::core::runtime::DispatchCtx;
+use crate::security::turn_origin::AgentTurnOrigin;
+use tinyagents_harness::progress::AgentProgress;
+
+#[path = "turn_host_progress.rs"]
+mod progress_helpers;
+#[cfg(test)]
+use progress_helpers::spawn_heartbeat_with_interval;
+use progress_helpers::{
+ settle_turn_snapshot, spawn_heartbeat, tap_progress, AbortOnDrop, LateSubagentSink,
+};
+
+/// How long a finished turn waits for its progress tap to forward every event
+/// the turn queued before the terminal `chat_done`/`chat_error` is published.
+/// Bounded: a detached sub-agent can hold a sender clone and keep the channel
+/// open past the turn, and a missing `TurnCompleted` (failed turn) must not
+/// stall delivery.
+pub(super) const PROGRESS_DRAIN_TIMEOUT: Duration = Duration::from_secs(3);
+
+/// Capacity of the agent's progress channel. A heavy-event sub-agent (50+
+/// events per run) can overflow a smaller buffer, and the sender side uses
+/// `try_send`, so an overflow silently drops events, including the ones that
+/// create a sub-agent's timeline row.
+const PROGRESS_CHANNEL_CAPACITY: usize = 256;
+
+pub(super) struct WebHost {
+ shared: Arc<Shared>,
+}
+
+impl WebHost {
+ pub(super) fn new(shared: Arc<Shared>) -> Self {
+ Self { shared }
+ }
+
+ fn ctx_of(request: &TurnRequest<QueuedPayload>) -> Result<DispatchCtx, String> {
+ request
+ .payload
+ .ctx
+ .clone()
+ .ok_or_else(|| "web chat turn carries no core context".to_owned())
+ }
+
+ async fn open(
+ &self,
+ request: &TurnRequest<QueuedPayload>,
+ policy: CheckoutPolicy,
+ ) -> Result<TurnSession, String> {
+ let ctx = Self::ctx_of(request)?;
+ let id = request.request_id.as_str();
+ let payload = &request.payload;
+ // The runner has not checked out a session yet, so per-request state
+ // cannot contain a resolved config at this point. Load it from the
+ // request's trusted dispatch context before deriving the durable
+ // session identity; the resolved copy is saved in the slot below.
+ let mut config = ctx.load_config().await?;
+ // The harness lock is local to this WebRuntime. Native channel and
+ // relay runners use the same agent-domain lease before checking out
+ // this durable identity, so separate surface runners cannot resume
+ // and commit the same transcript concurrently.
+ let tenant = ctx.tenant().map_err(|error| error.to_string())?;
+ let tenant_scope = crate::core::runtime::tenant::tenant_key(&tenant, "");
+ let agent_id = super::session::pick_target_agent_id(&config);
+ // A parallel fork has its own transcript identity, while the other
+ // queue modes resume the canonical thread session.
+ let session_identity = if policy == CheckoutPolicy::Fork {
+ format!("fork:{}", request.request_id)
+ } else {
+ crate::core::runtime::tenant::tenant_key(&tenant, &request.thread_id)
+ };
+ let lease = crate::agent::session_lease::SessionLease::acquire(
+ crate::agent::session_lease::SessionLeaseKey::new(
+ tenant_scope,
+ agent_id,
+ session_identity,
+ ),
+ None,
+ )
+ .await
+ .map_err(|()| "agent session lease was cancelled".to_owned())?;
+ // Every runner acquires locks in this order: durable session first,
+ // then the profile-wide chat/cron gate. This keeps native, relay and
+ // web runner instances from forming an inverse-lock cycle.
+ let profile_turn = crate::profiles::turn_gate::acquire(&ctx).await;
+ self.shared.with(id, |slot| {
+ slot.session_lease = Some(lease);
+ slot.profile_turn = profile_turn;
+ });
+ // A follow-up the runner dispatches after its predecessor finished was
+ // admitted when it was queued; one started directly still has its
+ // admission to answer.
+ let was_queued = self.shared.was_queued(id);
+ if was_queued && request.disposition == QueueDisposition::Followup {
+ crate::core::bus::BUS.publish(DomainEvent::RunQueueFollowupDispatched {
+ thread_id: request.thread_id.clone(),
+ followup_count: 1,
+ item_id: Some(id.to_owned()),
+ text_preview: Some(crate::agent::queued_turn::text_preview(&request.text)),
+ });
+ }
+ self.shared.admit(id, Admission::Started);
+ let session = TurnSession {
+ session_id: request.thread_id.clone(),
+ fingerprint: None,
+ };
+
+ // A test that parks or fails the turn does so before any session is
+ // built, like a turn wedged in checkout.
+ #[cfg(any(test, debug_assertions))]
+ if ops::test_hooks_active().await {
+ log::debug!("[web-channel][test] checkout skipped by a test hook request_id={id}");
+ return Ok(session);
+ }
+
+ // A thread started in a chosen folder acts there, not in the global
+ // `action_dir`. Applied before checkout so the session agent, its
+ // security policy (which grants `action_dir` as a trusted root) and its
+ // tools are all built on the thread's folder.
+ let thread_dir = crate::threads::ops::thread_working_dir(
+ &ctx,
+ config.workspace_dir.clone(),
+ &request.thread_id,
+ )
+ .await?;
+ if let Some(dir) = &thread_dir {
+ log::debug!(
+ "[web-channel] thread working folder applied thread_id={}",
+ request.thread_id
+ );
+ config.action_dir = dir.clone();
+ }
+ // A guard that stops this turn closes it from this turn's own config
+ // and reply language, not from whatever profile is active when it fires.
+ let activity = self.shared.with(id, |slot| slot.activity.clone());
+ activity.remember_turn(Arc::new(config.clone()), payload.locale.clone());
+ let checked = checkout_session_agent(
+ &ctx,
+ &config,
+ &payload.client_id,
+ &request.thread_id,
+ normalize_model_override(payload.model_override.clone()),
+ payload.temperature,
+ payload.locale.as_deref(),
+ policy,
+ )
+ .await?;
+
+ // Stamp the resolved agent onto the metadata so the trace exporter can
+ // attribute the run.
+ let mut metadata = payload.metadata.clone();
+ metadata.agent_id = Some(checked.fingerprint.target_agent_id.clone());
+ let projection = ProgressProjection::new(
+ &ctx,
+ TurnIds {
+ client_id: payload.client_id.clone(),
+ thread_id: request.thread_id.clone(),
+ request_id: id.to_owned(),
+ },
+ metadata,
+ config.clone(),
+ crate::storage::sessions::turn_states_for(&config.workspace_dir),
+ )
+ .await;
+ self.shared.with(id, |slot| {
+ slot.session = Some(checked);
+ slot.fork = policy == CheckoutPolicy::Fork;
+ slot.config = Some(Arc::new(config));
+ slot.thread_dir = thread_dir;
+ slot.projection = Some(Arc::new(AsyncMutex::new(projection)));
+ });
+ Ok(session)
+ }
+
+ /// The turn body: `run_single` on the checked-out agent, and everything
+ /// that follows from its outcome.
+ async fn run_turn(
+ &self,
+ request: &TurnRequest<QueuedPayload>,
+ cancellation: CancellationToken,
+ queue: Arc<RunQueue<TurnRequest<QueuedPayload>>>,
+ progress: mpsc::Sender<TurnSignal>,
+ ) -> Result<TurnResult, String> {
+ let ctx = Self::ctx_of(request)?;
+ let id = request.request_id.as_str();
+ let thread_id = request.thread_id.as_str();
+ let payload = &request.payload;
+ #[cfg(any(test, debug_assertions))]
+ if let Some(outcome) = ops::run_test_hooks(&self.shared, request).await {
+ return outcome;
+ }
+
+ let (config, thread_dir, checked, projection, activity) = self.shared.with(id, |slot| {
+ (
+ slot.config.clone(),
+ slot.thread_dir.clone(),
+ slot.session.take(),
+ slot.projection.clone(),
+ slot.activity.clone(),
+ )
+ });
+ let (Some(config), Some(mut checked), Some(projection)) = (config, checked, projection)
+ else {
+ return Err("web chat turn started without a checked-out session".to_owned());
+ };
+ let fingerprint = checked.fingerprint.clone();
+ let agent = &mut checked.agent;
+
+ // The agent's progress goes through a tap: every event is folded into
+ // the idle record and the work tracker, then handed to the runner,
+ // which projects it in order.
+ let (progress_tx, progress_rx) = mpsc::channel(PROGRESS_CHANNEL_CAPACITY);
+ // The channel is fresh here. Record the user input even if the turn
+ // fails before a committed reply can emit its final TurnContent event.
+ let _ = progress_tx.try_send(AgentProgress::TurnContent {
+ input: Some(request.text.clone()),
+ output: None,
+ });
+ let (drained_tx, mut drained_rx) = watch::channel(false);
+ // The tap outlives the turn on purpose: a detached sub-agent may still
+ // report through its sender clone after the parent finished, and the
+ // tap ends when the last sender drops.
+ let _tap = tap_progress(
+ &ctx,
+ progress_rx,
+ progress,
+ activity,
+ drained_tx,
+ Some(LateSubagentSink {
+ client_id: payload.client_id.clone(),
+ thread_id: thread_id.to_owned(),
+ request_id: id.to_owned(),
+ }),
+ );
+ let _beat = AbortOnDrop(spawn_heartbeat(&ctx, projection.clone()));
+
+ let origin = AgentTurnOrigin::WebChat {
+ thread_id: thread_id.to_owned(),
+ client_id: payload.client_id.clone(),
+ request_id: Some(id.to_owned()),
+ };
+ let approval = crate::security::approval::ApprovalTurnContext::chat(
+ crate::security::approval::ApprovalChatContext {
+ thread_id: thread_id.to_owned(),
+ client_id: payload.client_id.clone(),
+ request_id: Some(id.to_owned()),
+ },
+ );
+
+ let message_input = if payload.deferred_user_message {
+ let staged_parts = payload
+ .pending_attachments
+ .as_ref()
+ .map(|pending| pending.parts.as_slice())
+ .unwrap_or_default();
+ let persisted = crate::threads::ops::persist_queued_user_message(
+ &ctx,
+ thread_id,
+ id,
+ &request.text,
+ staged_parts,
+ )
+ .await?;
+ if staged_parts.is_empty() {
+ None
+ } else {
+ let parts = crate::threads::attachments::resolve_persisted_parts(
+ &ctx,
+ thread_id,
+ &persisted.id,
+ staged_parts,
+ )
+ .await?;
+ Some(crate::agent::message_convert::user_message_from_parts(
+ &request.text,
+ &parts,
+ )?)
+ }
+ } else if let Some(stored) = payload.stored_attachments.as_ref() {
+ let parts = crate::threads::attachments::resolve_persisted_parts(
+ &ctx,
+ thread_id,
+ &stored.persisted_message_id,
+ &stored.parts,
+ )
+ .await?;
+ Some(crate::agent::message_convert::user_message_from_parts(
+ &request.text,
+ &parts,
+ )?)
+ } else {
+ None
+ };
+
++ // Keep the resolved owner alive through the complete delegated run. The
++ // run context receives only a weak handle, so stored sessions do not pin
++ // tenant contexts after the request ends; tools that open tenant-scoped
++ // persistence after the task-local scope ended still reach it.
++ let core_lease = ctx.resolved();
+ // `run_single`'s future is very large; box it so the origin scope holds
+ // a pointer rather than inlining it into this frame.
+ let turn = Box::pin(crate::agent::turn_host::AgentTurnHost::run(
+ agent,
+ crate::agent::turn_host::AgentTurnRequest {
+ message: request.text.clone(),
+ message_input,
+ thread_id: Some(thread_id.to_owned()),
+ origin,
+ approval,
+ progress: Some(progress_tx),
+ run_queue: Some(queue),
+ cancellation,
+ turn_deadline: request.deadline,
+ native_staged_parts: Vec::new(),
+ native_staged_lease: None,
+ native_message_id: None,
+ // Also the turn's workspace, so attachment reads and
+ // delegated sub-agents use the upload folder (#7714).
+ workspace: thread_dir
+ .map(tinytools::WorkspaceDescriptor::new)
+ .map(crate::agent::turn_host::WorkspaceBinding::Set)
+ .unwrap_or(crate::agent::turn_host::WorkspaceBinding::Clear),
- host_env: Default::default(),
++ host_env: turn_host_env(core_lease.as_ref()),
+ },
+ ));
+ let outcome = turn.await;
++ drop(core_lease);
+ let result = match outcome {
+ Ok(response) => {
+ // A successful turn proves the thread's balance is usable, so
+ // drop any stale budget-exhausted signal before it could
+ // mislabel a later genuine empty response. See #3386.
+ ops::clear_budget_signal(&ctx, thread_id).await;
+ Ok(WebChatTaskResult {
+ full_response: response,
+ citations: crate::web_chat::citations::take_turn_citations(&ctx, thread_id),
+ usage: agent.take_last_turn_usage_totals(),
+ workspace_dir: config.workspace_dir.clone(),
+ timing: None,
+ })
+ }
+ Err(err) => {
+ self.budget_outcome(
+ &ctx,
+ request,
+ &fingerprint.provider_binding,
+ &config,
+ err.to_string(),
+ )
+ .await
+ }
+ };
+
+ if let Ok(task_result) = result.as_ref() {
+ speak_and_publish(&ctx, &config, request, task_result).await;
+ }
+
+ // Test hook: wedge the turn after its run, as a stuck save would.
+ #[cfg(any(test, debug_assertions))]
+ if ops::TEST_PARK_AFTER_RUN.load(std::sync::atomic::Ordering::SeqCst) {
+ log::debug!("[web-channel][test] parking the turn after the run request_id={id}");
+ std::future::pending::<()>().await;
+ }
+
+ agent.set_on_progress(None);
+
+ // The runner publishes the terminal event as soon as this returns. Let
+ // the tap forward everything the turn queued first, so the terminal
+ // cannot overtake the turn's own last tool results and narration.
+ // Bounded (see `PROGRESS_DRAIN_TIMEOUT`).
+ if tokio::time::timeout(PROGRESS_DRAIN_TIMEOUT, drained_rx.wait_for(|done| *done))
+ .await
+ .is_err()
+ {
+ log::warn!(
+ "[web-channel] progress did not drain within {PROGRESS_DRAIN_TIMEOUT:?}; delivering anyway thread={thread_id} request_id={id}"
+ );
+ }
+ settle_turn_snapshot(&config, request, result.is_ok());
+
+ match result {
+ Ok(mut task_result) => {
+ // The projection stamps its timing once it has seen the
+ // parent's `TurnCompleted`, which the drain above waited for.
+ task_result.timing = projection.lock().await.timing_snapshot();
+ let reply = task_result.full_response.clone();
+ self.shared.with(id, |slot| slot.result = Some(task_result));
+ // Only a turn that completed leaves its agent for the cache.
+ // A harness error can leave its session prefix committed even
+ // when the turn did not complete (an in-stream credential
+ // failure after partial text); re-caching that host makes the
+ // next request fail with "cannot change a session prefix after
+ // a committed turn". The durable transcript stays
+ // authoritative, so a failed agent is dropped and cold-boots.
+ self.shared.with(id, |slot| slot.session = Some(checked));
+ Ok(TurnResult {
+ reply,
+ data: serde_json::Value::Null,
+ })
+ }
+ Err(error) => {
+ log::warn!(
+ "[web-channel] dropping session agent after failed turn — next turn cold-boots from the durable transcript client={} thread={thread_id} request_id={id}",
+ payload.client_id
+ );
+ Err(error)
+ }
+ }
+ }
+
+ /// A failed turn that is really an exhausted balance becomes the
+ /// actionable out-of-credits reply (#3386); anything else is the error.
+ async fn budget_outcome(
+ &self,
+ ctx: &DispatchCtx,
+ request: &TurnRequest<QueuedPayload>,
+ provider_binding: &str,
+ config: &crate::config::Config,
+ err_message: String,
+ ) -> Result<WebChatTaskResult, String> {
+ let thread_id = request.thread_id.as_str();
+ let is_budget = is_inference_budget_exceeded_error(&err_message);
+ let is_empty = is_empty_provider_response_text(&err_message.to_lowercase());
+ // Only consult the cross-turn signal for an empty response that is not
+ // already a budget error: avoids taking the lock on every turn.
+ let has_fresh_signal = !is_budget
+ && is_empty
+ && ops::has_fresh_budget_signal(ctx, thread_id, provider_binding).await;
+ let placeholder = || WebChatTaskResult {
+ full_response: inference_budget_exceeded_user_message().to_string(),
+ citations: Vec::new(),
+ usage: None,
+ workspace_dir: config.workspace_dir.clone(),
+ timing: None,
+ };
+ match ops::classify_budget_correlation(is_budget, is_empty, has_fresh_signal) {
+ BudgetCorrelation::BudgetExhausted => {
+ // Remember the exhaustion (scoped to this provider binding) so
+ // a follow-up empty 200 on this thread+provider (the managed
+ // route closes the SSE clean under credit exhaustion, with no
+ // inline marker) reclassifies as budget. #3386.
+ ops::record_budget_signal(ctx, thread_id, provider_binding).await;
+ log::warn!(
+ "[web-channel] inference budget exhausted for client={} thread={thread_id} request_id={} error_category=budget_exhausted",
+ request.payload.client_id,
+ request.request_id
+ );
+ Ok(placeholder())
+ }
+ BudgetCorrelation::UpgradeEmptyToBudget => {
+ // An empty provider response inside the budget-signal window
+ // most likely failed for the same out-of-credits reason but
+ // arrived as a clean empty 200 with no budget marker. #3386.
+ log::warn!(
+ "[web-channel] reclassifying empty provider response as budget-exhausted from recent same-thread signal client={} thread={thread_id} request_id={} error_category=budget_exhausted_correlated",
+ request.payload.client_id,
+ request.request_id
+ );
+ Ok(placeholder())
+ }
+ BudgetCorrelation::PassThrough => Err(err_message),
+ }
+ }
+}
+
++/// The host environment a web turn starts with: the caller's resolved
++/// [`CoreContext`](crate::core::runtime::CoreContext), held weakly so a stored
++/// session does not pin the tenant once the request ends. The caller keeps the
++/// strong lease alive for the turn's duration.
++fn turn_host_env(
++ core: Option<&Arc<crate::core::runtime::CoreContext>>,
++) -> crate::agent::turn_env::HostTurnEnv {
++ crate::agent::turn_env::HostTurnEnv {
++ core: core.map(Arc::downgrade),
++ ..Default::default()
++ }
++}
++
+/// Speak the reply when the request, the thread or the voice mode asks for it,
+/// and tell a push-to-talk session what was committed.
+async fn speak_and_publish(
+ ctx: &crate::core::runtime::DispatchCtx,
+ config: &crate::config::Config,
+ request: &TurnRequest<QueuedPayload>,
+ task_result: &WebChatTaskResult,
+) {
+ let metadata = &request.payload.metadata;
+ let thread_id = request.thread_id.as_str();
+ let speak_reply = super::voice_notes::should_speak_reply(
+ config,
+ thread_id,
+ metadata.speak_reply,
+ metadata.source.as_deref(),
+ );
+ if speak_reply && !task_result.full_response.trim().is_empty() {
+ match crate::voice::reply_synthesis::synthesize_reply(
+ config,
+ &task_result.full_response,
+ config.channel_voice.resolve_voice("web"),
+ )
+ .await
+ {
+ Ok(outcome) => {
+ let stored = super::voice_notes::store_synthesized_reply(
+ ctx,
+ &config.workspace_dir,
+ &request.request_id,
+ &outcome.value.audio_base64,
+ &outcome.value.audio_mime,
+ );
+ if stored {
+ if let Err(err) = super::voice_notes::persist_reply_visemes(
+ ctx,
+ &config.workspace_dir,
+ &request.request_id,
+ &outcome.value.visemes,
+ ) {
+ log::warn!(
+ "[web_channel][voice_note] could not store reply timeline request_id={}: {err}",
+ request.request_id
+ );
+ }
+ }
+ log::debug!(
+ "[web_channel] reply_speech dispatched chars={} stored={stored} client_id={} thread_id={thread_id} request_id={}",
+ task_result.full_response.len(),
+ request.payload.client_id,
+ request.request_id,
+ );
+ }
+ Err(err) => log::warn!(
+ "[web_channel] reply_speech failed: {err} client_id={} thread_id={thread_id} request_id={}",
+ request.payload.client_id,
+ request.request_id,
+ ),
+ }
+ }
+ // Upstream removed the push-to-talk `voice::bus` transcript-committed
+ // event; the PTT session no longer needs a host-side notification here.
+}
+
+#[async_trait]
+impl TurnHost<QueuedPayload> for WebHost {
+ async fn checkout(&self, request: &TurnRequest<QueuedPayload>) -> Result<TurnSession, String> {
+ self.open(request, CheckoutPolicy::Exact).await
+ }
+
+ async fn checkout_fork(
+ &self,
+ request: &TurnRequest<QueuedPayload>,
+ ) -> Result<TurnSession, String> {
+ self.open(request, CheckoutPolicy::Fork).await
+ }
+
+ fn run_origin(&self, request: &TurnRequest<QueuedPayload>) -> serde_json::Value {
+ serde_json::json!({
+ "channel": "web",
+ "thread_id": request.thread_id,
+ "client_id": request.payload.client_id,
+ "request_id": request.request_id,
+ })
+ }
+
+ async fn run(
+ &self,
+ request: &TurnRequest<QueuedPayload>,
+ _session: &TurnSession,
+ _origin: &serde_json::Value,
+ cancellation: CancellationToken,
+ queue: Arc<RunQueue<TurnRequest<QueuedPayload>>>,
+ progress: mpsc::Sender<TurnSignal>,
+ ) -> Result<TurnResult, String> {
+ self.run_turn(request, cancellation, queue, progress).await
+ }
+
+ async fn checkin(&self, request: &TurnRequest<QueuedPayload>) {
+ let (session, fork) = self
+ .shared
+ .with(&request.request_id, |slot| (slot.session.take(), slot.fork));
+ let (Some(checked), false, Some(ctx)) = (session, fork, request.payload.ctx.as_ref())
+ else {
+ return;
+ };
+ checkin_session_agent(ctx, &request.thread_id, checked.agent, checked.fingerprint).await;
+ }
+
+ async fn cancel_children(&self, request: &TurnRequest<QueuedPayload>) {
+ // A scoped cancel names one turn and leaves detached sub-agents alone;
+ // an unscoped Stop stops them in `cancel_chat` before it cancels the
+ // turn. The guards close the turn, they do not widen a cancel.
+ log::debug!(
+ "[web-channel] turn stopped; detached sub-agents are left running thread_id={} request_id={}",
+ request.thread_id,
+ request.request_id
+ );
+ }
+}
+
+#[cfg(test)]
+#[path = "turn_host_tests.rs"]
+mod tests;
diff --cc crates/openhuman-core/src/web_chat/turn_host_tests.rs
index 715d216da9,0000000000..3ea955d686
mode 100644,000000..100644
--- a/crates/openhuman-core/src/web_chat/turn_host_tests.rs
+++ b/crates/openhuman-core/src/web_chat/turn_host_tests.rs
@@@ -1,242 -1,0 +1,266 @@@
+use super::*;
+use crate::web_chat::turn_activity::TurnActivity;
+
+fn iteration() -> AgentProgress {
+ AgentProgress::IterationStarted {
+ iteration: 1,
+ max_iterations: 5,
+ }
+}
+
+fn model_replied() -> AgentProgress {
+ AgentProgress::ModelCallCompleted {
+ model: "m".into(),
+ provider_id: "p".into(),
+ subagent_task_id: None,
+ input: None,
+ output: None,
+ iteration: 1,
+ input_tokens: 0,
+ output_tokens: 0,
+ cached_input_tokens: 0,
+ cache_creation_tokens: 0,
+ reasoning_tokens: 0,
+ cost_usd: None,
+ }
+}
+
+fn kind(signal: &TurnSignal) -> &'static str {
+ match signal {
+ TurnSignal::WorkStarted => "started",
+ TurnSignal::WorkFinished => "finished",
+ TurnSignal::Progress(event) => match **event {
+ AgentProgress::IterationStarted { .. } => "iteration",
+ AgentProgress::ModelCallCompleted { .. } => "model",
+ AgentProgress::TurnCompleted { .. } => "completed",
+ _ => "other",
+ },
+ }
+}
+
+/// The tap forwards every event in order, brackets open model and tool calls
+/// with the work signals the runner's idle guard needs, folds each event into
+/// the activity record, and releases the drain once the parent completed.
+#[tokio::test]
+async fn the_tap_forwards_in_order_brackets_open_work_and_signals_the_drain() {
+ let (agent_tx, agent_rx) = mpsc::channel(8);
+ let (runner_tx, mut runner_rx) = mpsc::channel(16);
+ let (drained_tx, mut drained_rx) = watch::channel(false);
+ let activity = TurnActivity::default();
+ let _tap = tap_progress(
+ &DispatchCtx::ambient(),
+ agent_rx,
+ runner_tx,
+ activity.clone(),
+ drained_tx,
+ None,
+ );
+
+ for event in [
+ iteration(),
+ model_replied(),
+ AgentProgress::turn_completed(1),
+ ] {
+ agent_tx.send(event).await.expect("tap listens");
+ }
+ let mut seen = Vec::new();
+ while seen.last() != Some(&"completed") {
+ seen.push(kind(&runner_rx.recv().await.expect("signal")));
+ }
+ assert_eq!(
+ seen,
+ ["started", "iteration", "finished", "model", "completed"]
+ );
+
+ tokio::time::timeout(Duration::from_secs(5), drained_rx.wait_for(|done| *done))
+ .await
+ .expect("drained once the parent completed")
+ .expect("watch open");
+ assert_eq!(
+ activity.stuck_point(),
+ super::super::turn_activity::StuckPoint::AfterRun
+ );
+ drop(agent_tx);
+}
+
+/// A turn whose events stop without `TurnCompleted` (a failed turn) still
+/// releases the drain when its stream ends.
+#[tokio::test]
+async fn the_drain_is_released_when_the_stream_ends_without_a_completion() {
+ let (agent_tx, agent_rx) = mpsc::channel(8);
+ let (runner_tx, mut runner_rx) = mpsc::channel(16);
+ let (drained_tx, mut drained_rx) = watch::channel(false);
+ let _tap = tap_progress(
+ &DispatchCtx::ambient(),
+ agent_rx,
+ runner_tx,
+ TurnActivity::default(),
+ drained_tx,
+ None,
+ );
+ agent_tx.send(AgentProgress::TurnStarted).await.unwrap();
+ assert_eq!(kind(&runner_rx.recv().await.unwrap()), "other");
+ assert!(!*drained_rx.borrow());
+ drop(agent_tx);
+ tokio::time::timeout(Duration::from_secs(5), drained_rx.wait_for(|done| *done))
+ .await
+ .expect("the closed stream drains")
+ .expect("watch open");
+}
+
+#[tokio::test]
+async fn a_dropped_runner_stops_the_tap() {
+ let (agent_tx, agent_rx) = mpsc::channel(8);
+ let (runner_tx, runner_rx) = mpsc::channel(1);
+ let (drained_tx, drained_rx) = watch::channel(false);
+ let tap = tap_progress(
+ &DispatchCtx::ambient(),
+ agent_rx,
+ runner_tx,
+ TurnActivity::default(),
+ drained_tx,
+ None,
+ );
+ drop(runner_rx);
+ agent_tx.send(AgentProgress::TurnStarted).await.unwrap();
+ tokio::time::timeout(Duration::from_secs(5), tap)
+ .await
+ .expect("the tap ends with its consumer")
+ .expect("no panic");
+ assert!(*drained_rx.borrow());
+}
+
+/// A detached sub-agent that fails after its parent turn has finished (a child
+/// aborted by `subagent_cancel`) still settles its card: the tap keeps running
+/// past the runner and publishes the failure under the turn's ids.
+#[tokio::test]
+async fn a_late_subagent_failure_is_published_after_the_runner_is_gone() {
+ let mut bus = crate::web_chat::subscribe_web_channel_events();
+ let (agent_tx, agent_rx) = mpsc::channel(8);
+ let (runner_tx, runner_rx) = mpsc::channel(1);
+ let (drained_tx, _drained_rx) = watch::channel(false);
+ let _tap = tap_progress(
+ &DispatchCtx::ambient(),
+ agent_rx,
+ runner_tx,
+ TurnActivity::default(),
+ drained_tx,
+ Some(LateSubagentSink {
+ client_id: "late-client".into(),
+ thread_id: "late-thread".into(),
+ request_id: "late-request".into(),
+ }),
+ );
+ drop(runner_rx);
+ agent_tx.send(AgentProgress::TurnStarted).await.unwrap();
+ agent_tx
+ .send(AgentProgress::SubagentFailed {
+ agent_id: "researcher".into(),
+ task_id: "task-late".into(),
+ error: "cancelled".into(),
+ })
+ .await
+ .unwrap();
+ let event = tokio::time::timeout(Duration::from_secs(5), async {
+ loop {
+ let event = bus.recv().await.expect("event bus");
+ if event.context().request_id == "late-request" {
+ return event;
+ }
+ }
+ })
+ .await
+ .expect("the late failure is published");
+ assert_eq!(event.event_name(), "subagent_failed");
+ assert_eq!(event.context().client_id, "late-client");
+ assert_eq!(event.context().thread_id, "late-thread");
+ let wire = serde_json::to_value(&event).expect("wire event");
+ assert_eq!(wire["skill_id"], "task-late");
+ assert_eq!(wire["success"], false);
+}
+
+#[tokio::test]
+async fn the_heartbeat_beats_only_for_a_live_turn() {
+ use super::super::surface::TurnIds;
+ #[cfg(all(feature = "channels", feature = "modules"))]
+ let _module = crate::channels::module_fixture::client().await;
+ let mut bus = crate::web_chat::subscribe_web_channel_events();
+ let ids = TurnIds {
+ client_id: "hb-client".into(),
+ thread_id: "host-hb-thread".into(),
+ request_id: "host-hb-request".into(),
+ };
+ let projection = Arc::new(AsyncMutex::new(
+ ProgressProjection::new(
+ &DispatchCtx::ambient(),
+ ids,
+ Default::default(),
+ crate::config::Config::default(),
+ std::sync::Arc::new(tinyagents_session::port::InMemoryTurnStates::default()),
+ )
+ .await,
+ ));
+ let beat = AbortOnDrop(spawn_heartbeat_with_interval(
+ &DispatchCtx::ambient(),
+ projection.clone(),
+ Duration::from_millis(25),
+ ));
+
+ // Before `TurnStarted` the turn is not live: no beat, however long it waits.
+ tokio::time::sleep(Duration::from_millis(100)).await;
+ loop {
+ match bus.try_recv() {
+ Ok(event) => assert_ne!(
+ event.context().thread_id,
+ "host-hb-thread",
+ "the inactive turn must not publish a heartbeat"
+ ),
+ Err(
+ tokio::sync::broadcast::error::TryRecvError::Empty
+ | tokio::sync::broadcast::error::TryRecvError::Closed,
+ ) => break,
+ Err(tokio::sync::broadcast::error::TryRecvError::Lagged(_)) => continue,
+ }
+ }
+
+ projection
+ .lock()
+ .await
+ .on_event(AgentProgress::TurnStarted)
+ .await;
+ tokio::time::sleep(Duration::from_millis(100)).await;
+ let mut names = Vec::new();
+ while let Ok(event) = bus.try_recv() {
+ if event.context().thread_id == "host-hb-thread" {
+ names.push(event.event_name());
+ }
+ }
+ assert_eq!(names[0], "inference_start");
+ assert!(names.len() >= 2, "{names:?}");
+ assert!(names[1..].iter().all(|name| *name == "inference_heartbeat"));
+ drop(beat);
+}
++
++/// A runner-driven web turn carries its caller's owner context, so tools that
++/// open tenant-scoped persistence after the task-local scope has ended still
++/// reach it; the env holds it weakly and never pins the tenant itself.
++#[test]
++fn the_turn_env_carries_the_callers_core_context_weakly() {
++ let core =
++ crate::core::runtime::CoreContext::for_test(crate::core::runtime::DomainSet::full(), None);
++ let env = turn_host_env(Some(&core));
++ let carried = env
++ .core
++ .as_ref()
++ .and_then(std::sync::Weak::upgrade)
++ .expect("web turn carries its caller CoreContext");
++ assert!(Arc::ptr_eq(&carried, &core));
++ drop(carried);
++ let weak = env.core.clone().expect("weak handle");
++ drop(core);
++ assert!(
++ weak.upgrade().is_none(),
++ "the env must not keep the tenant alive"
++ );
++ assert!(turn_host_env(None).core.is_none());
++}
diff --cc docs/gitbooks/en/developing/architecture/agent-harness.md
index 3919e80055,e79ac3b948..19c918d273
--- a/docs/gitbooks/en/developing/architecture/agent-harness.md
+++ b/docs/gitbooks/en/developing/architecture/agent-harness.md
@@@ -96,15 -93,9 +96,9 @@@ Some settings remain runtime-wide for e
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. 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. Web chat admission and queue mechanics use TinyAgents' `TurnRunner`; OpenHuman's `web_chat` host supplies ingress, session checkout, approvals, persistence, and terminal-event policy. Channel provider transport and the typed web-event schema/projection are supplied by the TinyChannels v2 module over TinyBus. OpenHuman publishes those canonical events on its process event bus and retains only host routing metadata. The shared `TurnProgress` seam lives in `agent/session_host/tool_progress.rs`.
- Multi-agent orchestration runs on the tinyagents graph layer, through `tinyagents-orchestration`'s `parallel` module, the host `spawn_parallel` adapter and the shared `graph::orchestration` `TaskStore` lifecycle primitives re-exported from [`orchestration/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-core/src/agent/orchestration/mod.rs):
-
- - The delegation graph is a `plan → execute ⇄ review → finalize` `CompiledGraph`. It has conditional routing, `RecursionPolicy`, a durable `FileCheckpointer`, a `CancellationToken` and a `GraphTracingSink`.
- - The workflow phase engine fans each phase's agents out on the graph (`with_max_concurrency`). The durable `WorkflowRun` ledger stays the source of truth for resume.
- - `spawn_parallel_agents` runs its fan-out through the host `spawn_parallel` adapter over `tinyagents_orchestration::parallel`.
- - The agent-teams member runtime is a conditional-routing graph (`execute → complete | fail → done`).
- - The detached-sub-agent registry is backed by a typed `TaskStore` lifecycle ledger (Pending, Running, then Completed, Failed or Cancelled).
+ TinyAgents' `tinyagents-orchestration` crate owns the host-neutral sub-agent lifecycle. OpenHuman supplies the product adapters for spawn policy, durable session resolution, cancellation, progress, and completion delivery. The current host surface is documented in [`agent/orchestration/README.md`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-core/src/agent/orchestration/README.md); [`spawn_subagent_host_impl.rs`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-core/src/agent/orchestration/tools/spawn_subagent_host_impl.rs) binds a child run to its caller's execution context.
## TinyAgents crate: features and compatibility
diff --cc vendor/tinyagents
index 3020f2e2b2,dfa5f161ad..5ece4ab0a0
--- a/vendor/tinyagents
+++ b/vendor/tinyagents
@@@ -1,1 -1,1 +1,1 @@@
- Subproject commit 3020f2e2b2178beb356703bf7988dead6aaffcc5
-Subproject commit dfa5f161ad4ba0c5bd9bd73c7c91785dcbed1c95
++Subproject commit 5ece4ab0a096f8c9dbae76125ea916341a59437e