The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
//! Whole-turn validation, observation, cancellation, deadlines and dispatch.
use super::*;
struct CancellationRelay(tokio::task::JoinHandle<()>);
impl Drop for CancellationRelay {
fn drop(&mut self) {
self.0.abort();
}
}
impl Turn {
/// Run the turn.
///
/// Establishes the origin and progress scopes described in the module docs,
/// then dispatches through the shared call handler so the
/// `{result, logs}` envelope, [`DomainSet`](openhuman_core::core::runtime::DomainSet)
/// gating and error classification are handled the same way as every other
/// facade method.
///
/// # Errors
///
/// [`CoreError::Unavailable`] when the `inference` domain family is off —
/// that is a build/composition fact, not a failure, and a host should hide
/// the surface rather than report an error.
pub async fn send(self) -> Result<TurnOutcome, CoreError> {
let environment = self.tool_env.clone();
let dispatch = Box::pin(self.send_scoped());
match environment {
Some(environment) => {
let command_environment =
tinyagents_harness_tools::exec::timeout::CommandEnvironment::new(
environment
.iter()
.map(|(name, value)| (name.clone(), value.clone())),
);
command_environment.scope(dispatch).await
}
None => dispatch.await,
}
}
async fn send_scoped(mut self) -> Result<TurnOutcome, CoreError> {
// External cancellation cascades inward; cancelling this turn through
// its acknowledgement handle/deadline must not cancel a shared parent.
let token = self
.token_cancellation
.clone()
.unwrap_or_default()
.child_token();
// A synchronously ready model stream can stay inside one dispatch poll.
// Relay control independently so its native cancellation checks also
// interrupt that poll; abort the relay when this turn ends or is dropped.
self.control_deadline = self
.timeout
.and_then(|duration| tokio::time::Instant::now().checked_add(duration));
let cancellation = self.cancellation.clone();
let deadline = self.control_deadline;
let _relay = (cancellation.is_some() || deadline.is_some()).then(|| {
let native = token.clone();
CancellationRelay(tokio::spawn(async move {
tokio::select! {
_ = async {
match cancellation {
Some(handle) => handle.cancelled().await,
None => std::future::pending().await,
}
} => {},
_ = async {
match deadline {
Some(deadline) => tokio::time::sleep_until(deadline).await,
None => std::future::pending().await,
}
} => {},
}
native.cancel();
}))
});
// The native token is minted here and travels as an explicit value:
// the relay above fires it, and `send_inner` hands it to the core on
// the turn's host environment.
self.native_cancellation = Some(token);
self.send_traced().await
}
async fn send_traced(mut self) -> Result<TurnOutcome, CoreError> {
// Keep cancellation acknowledgement behind the terminal callback too.
let _observer_guard = self.cancellation.as_ref().map(|handle| handle.enter());
let Some(observer) = self.observer.take() else {
return self.send_events().await;
};
let capture = self.trace_content;
let session_id = self
.session_id
.clone()
.filter(|id| !id.trim().is_empty())
.unwrap_or_else(|| format!("embed-{}", uuid::Uuid::new_v4()));
self.session_id = Some(session_id.clone());
let message = self.request.message.clone();
crate::observe::observe_turn(observer, capture, &session_id, &message, self.send_events())
.await
}
// Runtime lifecycle events enclose control/cleanup, while progress delivery
// keeps polling that control future even when the caller stops draining.
async fn send_events(mut self) -> Result<TurnOutcome, CoreError> {
let (hub, agent_id) = match &self.target {
TurnTarget::Agent(agent) => (
Some(agent._runtime_guard.events.clone()),
Some(agent.id.clone()),
),
TurnTarget::Runtime(_) => (None, None),
};
let Some(hub) = hub else {
return self.send_controlled().await;
};
let session_id = self
.session_id
.clone()
.filter(|id| !id.trim().is_empty())
.unwrap_or_else(|| format!("embed-{}", uuid::Uuid::new_v4()));
self.session_id = Some(session_id.clone());
let thread_id = event_thread_id(self.origin.as_ref(), &session_id);
let turn_id = hub.begin_turn(agent_id.clone(), &thread_id);
let mut end = ObservedTurn {
hub: hub.clone(),
agent_id: agent_id.clone(),
thread_id,
turn_id: turn_id.clone(),
success: false,
};
let forward = self.progress.take();
let token = self.native_cancellation.clone().unwrap_or_default();
let acknowledgement = self.cancellation.clone();
let deadline = self.control_deadline;
let (tx, mut rx) = tokio::sync::mpsc::channel(64);
self.progress = Some(tx);
let mut dispatch = self.send_controlled();
let mut pending_progress = None;
let mut outcome = loop {
tokio::select! {
biased;
result = &mut dispatch => break result,
item = rx.recv() => if let Some(item) = item {
observe_progress(&hub, &agent_id, &turn_id, &item);
if let Some(sink) = &forward {
let retained = item.clone();
tokio::select! {
_ = sink.send(item) => {},
_ = token.cancelled() => {},
result = &mut dispatch => { pending_progress = Some(retained); break result; },
}
}
} else { break (&mut dispatch).await; },
}
};
drop(dispatch);
while let Some((item, observed)) = pending_progress
.take()
.map(|item| (item, true))
.or_else(|| rx.try_recv().ok().map(|item| (item, false)))
{
if !observed {
observe_progress(&hub, &agent_id, &turn_id, &item);
}
if outcome.is_ok() {
if let Some(sink) = &forward {
tokio::select! {
_ = sink.send(item) => {},
_ = token.cancelled() => outcome = Err(CoreError::TurnCancelled { method: AGENT_CHAT }),
_ = async {
match &acknowledgement {
Some(handle) => handle.cancelled().await,
None => std::future::pending().await,
}
} => outcome = Err(CoreError::TurnCancelled { method: AGENT_CHAT }),
_ = async {
match deadline {
Some(deadline) => tokio::time::sleep_until(deadline).await,
None => std::future::pending().await,
}
} => outcome = Err(CoreError::DeadlineExceeded { method: AGENT_CHAT }),
}
}
}
}
end.success = outcome.is_ok();
outcome
}
// Erase this large dispatch future at the control boundary: composing
// several observed/cancellable turns must not multiply caller stack use.
fn send_controlled(
mut self,
) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<TurnOutcome, CoreError>> + Send>>
{
Box::pin(async move {
let deadline = self.control_deadline;
let token = self.token_cancellation.clone();
let native = self.native_cancellation.clone().unwrap_or_default();
let cancellation = self.cancellation.take().or_else(|| {
(deadline.is_some() || token.is_some()).then(crate::TurnCancellation::default)
});
let _guard = cancellation.as_ref().map(crate::TurnCancellation::enter);
let meter = crate::turn_meter::TurnMeter::new(self.meter.take());
let Some(cancellation) = cancellation else {
return Box::pin(self.send_inner(&meter.usage)).await;
};
let outcome = cancellation
.cleanup()
.scope(async {
tokio::select! {
biased;
_ = async {
match &token {
Some(token) => token.cancelled().await,
None => std::future::pending().await,
}
} => Err(CoreError::TurnCancelled { method: AGENT_CHAT }),
_ = cancellation.cancelled() => {
native.cancel();
log::debug!("[embed][agent] turn cancelled");
Err(CoreError::TurnCancelled { method: AGENT_CHAT })
}
_ = async {
match deadline {
Some(deadline) => tokio::time::sleep_until(deadline).await,
None => std::future::pending().await,
}
} => {
native.cancel();
Err(CoreError::DeadlineExceeded { method: AGENT_CHAT })
},
outcome = Box::pin(self.send_inner(&meter.usage)) => {
controlled_outcome(outcome, &native, token.as_ref(), &cancellation, deadline)
},
}
})
.await;
// The dispatch future is dropped before waiting for its command
// waiters. No new command can register after this point.
cancellation.cleanup().wait().await;
outcome
})
}
/// Observe completion and, on runtime-owned agents, model and tool events.
/// Caller-built core runtimes provide terminal metadata only. Payloads are
/// omitted unless [`Self::trace_content`] explicitly enables them.
pub fn observer(mut self, observer: Arc<dyn crate::observe::TurnObserver>) -> Self {
self.observer = Some(observer);
self
}
/// Explicitly consent to model messages and tool payloads in observations.
pub fn trace_content(mut self, content: crate::observe::TraceContent) -> Self {
self.trace_content = content;
self
}
/// Bound the entire turn, including tool calls and answer repair.
/// Deadline errors are returned only after registered subprocess cleanup.
pub fn timeout(mut self, duration: std::time::Duration) -> Self {
self.timeout = Some(duration);
self
}
/// Obtain a cloneable handle that cancels only this turn and awaits its
/// subprocess cleanup. Acquire it before moving the turn to `send()`.
pub fn cancellation_handle(&mut self) -> crate::TurnCancellation {
self.cancellation
.get_or_insert_with(Default::default)
.clone()
}
/// Obtain a cloneable handle that adds messages to this turn while it
/// runs. Acquire it before moving the turn to `send()`.
///
/// Each [`TurnSteering::steer`](crate::TurnSteering::steer) is applied at
/// the agent loop's next safe checkpoint: before the first model call,
/// after a tool batch, or in place of finishing when the model has just
/// written its final answer, which earns the turn one more model call.
/// Steers the turn did not apply come back on
/// [`TurnOutcome::unapplied_steers`] (or, when the turn fails,
/// [`TurnSteering::take_unapplied`](crate::TurnSteering::take_unapplied)),
/// and a steer sent after the turn ended is refused with its text.
pub fn steering_handle(&mut self) -> crate::TurnSteering {
self.steering.get_or_insert_with(Default::default).clone()
}
async fn send_inner(mut self, usage: &UsageSink) -> Result<TurnOutcome, CoreError> {
// Declared first so it drops last, after the dispatch future: by then
// every steer the turn did not apply is back in the queue.
let steering = crate::turn_steering::SteeringScope::new(self.steering.take());
// The core neither mints nor returns a session id, so continuing a
// conversation would otherwise be impossible without the caller
// inventing an id scheme — which every embedder has then done
// differently. Mint one here and hand it back.
let session_id = self
.session_id
.take()
.filter(|id| !id.trim().is_empty())
.unwrap_or_else(|| format!("embed-{}", uuid::Uuid::new_v4()));
self.request.thread_id = Some(session_id.clone());
log::debug!(
"[embed][agent] turn session={session_id} model={:?} routed={} cwd_set={}",
self.request.model_override,
self.request.inference_url.is_some(),
self.request.cwd.is_some(),
);
validate_route(&self.request)?;
self.validate_turn_options()?;
// Never transmit the bearer over a non-TLS channel. The route accepts
// an arbitrary base URL, so guard here — before any request is built —
// rather than trusting every embedder to only name https endpoints. A
// `Route` is refused when it pairs a credential with a non-HTTPS
// endpoint; a route without a credential is allowed through (some
// embedders run a local, unauthenticated OpenAI-compatible server over
// plain http, and there is nothing sensitive on the wire for them).
if self
.request
.api_key
.as_deref()
.is_some_and(|k| !k.is_empty())
{
if let Some(endpoint) = self.request.inference_url.as_deref() {
if !is_safe_endpoint_for_bearer(endpoint) {
return Err(crate::error::CoreError::InsecureRoute {
method: AGENT_CHAT,
endpoint: sanitize_url_for_display(endpoint),
});
}
}
}
// Filled by the turn itself, before any error is raised, so a failed
// turn is still metered. Read back below whether the dispatch returned
// a reply or an error.
let wants_json = self
.response_format
.as_ref()
.is_some_and(crate::complete::ResponseFormat::wants_json);
let validator =
crate::structured::Validator::new(self.response_format.as_ref()).map_err(|reason| {
CoreError::StructuredOutput {
method: AGENT_CHAT,
failure: crate::structured::StructuredOutputFailure {
attempts: 0,
reason,
finish_reason: None,
answered_model: None,
usage: None,
},
}
})?;
let budget = self.budget.take().map(|budget| crate::budget::ModelBudget {
ledger: budget.ledger.child(crate::budget::SpendLimits::default()),
call: budget.call,
});
// Everything the core honours for this turn rides one explicit value;
// nothing is recovered from an ambient scope below this point.
// `HostTurnEnv` carries crate-private native channel fields, so it is
// built by assignment rather than a struct literal from this crate.
let mut host_env = openhuman_core::agent::turn_env::HostTurnEnv::default();
host_env.command_environment = self.tool_env.take();
host_env.model_budget = budget.clone();
host_env.dispatch_admission = self.dispatch_admission.take();
host_env.spawn_depth_limit = self.spawn_depth_limit;
host_env.cancellation = self.native_cancellation.clone();
host_env.hooks = std::mem::take(&mut self.hooks);
host_env.fresh_tool_snapshot = self.tools.is_some();
host_env.approval = openhuman_core::security::approval::ApprovalTurnContext {
flow_run: self.flow_run.take().map(|(flow_id, run_id)| {
openhuman_core::security::approval::FlowRunContext { flow_id, run_id }
}),
..Default::default()
};
let chat_env = openhuman_core::agent_runs::agent_chat::AgentChatEnv {
progress: self.progress.take(),
host: host_env,
run_queue: steering.queue(),
};
let options = AgentTurnOptions {
chat_env,
// Captured here, before the dispatch can hop to a core worker that
// does not inherit task locals; the core re-establishes it around
// the turn.
observer: tinyagents_harness::observability::turn_observer::current_scope(),
shape: tinyagents_harness::middleware::ResponseShapeScope::new(
tinyagents_harness::middleware::ResponseShape {
response_format: self
.response_format
.take()
.map(crate::complete::ResponseFormat::into_wire),
max_output_tokens: self.max_tokens,
top_p: self.top_p,
validator: wants_json.then(|| {
std::sync::Arc::new(validator)
as std::sync::Arc<dyn tinyagents_harness::middleware::ResponseValidator>
}),
structured_retries: self.structured_retries,
provider_options: self.provider_options.clone(),
require_tool_call: self.require_tool_call,
},
),
untrusted_input: self.untrusted_input,
tools: self.tools.take(),
attachments: std::mem::take(&mut self.attachments),
};
let dispatch = dispatch(self.target, self.request, self.seed.take(), usage, options);
let reply = match self.origin {
Some(origin) => {
openhuman_core::security::turn_origin::with_origin(origin, dispatch).await
}
None => dispatch.await,
}
.inspect_err(|err| {
// Log a redacted failure event so dispatch errors are visible in
// host logs without spilling the request, credentials, working
// directory, or the error's full payload (CoreError::Domain can
// carry arbitrary `data`). Only the session id and the coarse
// variant classification are logged; the error itself propagates
// to the caller untouched.
let tag = match err {
crate::error::CoreError::TurnCancelled { .. } => "turn_cancelled",
crate::error::CoreError::Cancelled { .. } => "cancelled",
crate::error::CoreError::DeadlineExceeded { .. } => "deadline",
crate::error::CoreError::StructuredOutput { .. } => "structured_output",
crate::error::CoreError::BudgetExceeded { .. } => "budget_exceeded",
crate::error::CoreError::Domain { .. } => "domain",
crate::error::CoreError::Unavailable { .. } => "unavailable",
crate::error::CoreError::Rpc { .. } => "rpc",
crate::error::CoreError::Encode { .. } => "encode",
crate::error::CoreError::Decode { .. } => "decode",
crate::error::CoreError::InsecureRoute { .. } => "insecure_route",
crate::error::CoreError::InvalidRoute { .. } => "invalid_route",
crate::error::CoreError::AgentRemoved { .. } => "agent_removed",
crate::error::CoreError::DispatchAdmission { .. } => "dispatch_admission",
};
log::debug!("[embed][agent] turn_failed session={session_id} kind={tag}");
});
let reply = reply.map_err(|error| {
match budget.as_ref().and_then(|budget| budget.ledger.refusal()) {
Some(source) => CoreError::BudgetExceeded {
method: AGENT_CHAT,
source,
},
None => error,
}
});
let (reply, report) = reply?;
let structured = if wants_json {
serde_json::from_str(reply.trim()).ok()
} else {
None
};
log::debug!(
"[embed][agent] turn_completed session={session_id} reply_len={} structured={} \
finish_reason={:?}",
reply.len(),
structured.is_some(),
report.as_ref().and_then(|r| r.finish_reason.as_deref())
);
let report = report.unwrap_or_default();
let unapplied_steers = steering.close();
if !unapplied_steers.is_empty() {
log::debug!(
"[embed][agent] turn session={session_id} ended with {} unapplied steer(s)",
unapplied_steers.len()
);
}
Ok(TurnOutcome {
reply,
session_id,
usage: usage
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.clone(),
structured,
finish_reason: report.finish_reason,
answered_model: report.answered_model,
unapplied_steers,
})
}
/// Refuse the per-turn options the target cannot honour, before anything
/// is dispatched.
fn validate_turn_options(&self) -> Result<(), CoreError> {
if self.structured_retries > 3 {
return Err(CoreError::StructuredOutput {
method: AGENT_CHAT,
failure: crate::structured::StructuredOutputFailure {
attempts: 0,
reason: crate::structured::StructuredFailureReason::RetryLimit,
finish_reason: None,
answered_model: None,
usage: None,
},
});
}
let refuse = |message: &str, kind: &str| {
Err(CoreError::Domain {
method: AGENT_CHAT,
message: message.to_owned(),
kind: Some(kind.to_owned()),
data: None,
expected_user_state: true,
})
};
if self
.top_p
.is_some_and(|p| !p.is_finite() || !(0.0..=1.0).contains(&p))
{
return refuse(
"top_p must be finite and between zero and one",
"invalid_model_parameter",
);
}
let host_only = match &self.target {
TurnTarget::Agent(agent) => agent.host_only,
TurnTarget::Runtime(_) => {
if self.tools.is_some() {
return refuse(
"per-turn host tools need a runtime-owned Agent",
"turn_tools_unsupported",
);
}
if self.response_format.is_some()
|| self.max_tokens.is_some()
|| self.top_p.is_some()
|| self.structured_retries != 0
|| !self.provider_options.is_null()
|| self.require_tool_call
{
return refuse(
"response_format and max_tokens need a runtime-owned Agent",
"turn_shape_unsupported",
);
}
false
}
};
if self.untrusted_input && !host_only {
return refuse(
"untrusted_input is only allowed on a HostOnly agent",
"untrusted_input_requires_host_only",
);
}
Ok(())
}
}
// Classify the result at the control boundary after a native dispatch poll.
fn controlled_outcome<T>(
outcome: Result<T, CoreError>,
native: &crate::CancellationToken,
token: Option<&crate::CancellationToken>,
cancellation: &crate::TurnCancellation,
deadline: Option<tokio::time::Instant>,
) -> Result<T, CoreError> {
// The native session runtime currently crosses the RPC boundary as this
// cancellation error. Only that interrupted dispatch needs classification;
// completed replies and unrelated failures retain their original result.
let interrupted = native.is_cancelled()
&& matches!(&outcome, Err(CoreError::Rpc { method, message })
if *method == AGENT_CHAT && message == "session turn cancelled");
if !interrupted {
return outcome;
}
if token.is_some_and(|token| token.is_cancelled()) || cancellation.is_cancelled() {
Err(CoreError::TurnCancelled { method: AGENT_CHAT })
} else if deadline.is_some_and(|deadline| tokio::time::Instant::now() >= deadline) {
Err(CoreError::DeadlineExceeded { method: AGENT_CHAT })
} else {
outcome
}
}
#[cfg(test)]
#[path = "turn_control_tests.rs"]
mod tests;