Skip to content

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

37.3 KB
Raw Blame
//! One agent turn, typed.
//!
//! A [`Turn`] is built by [`Agent::turn`](crate::Agent::turn) (a runtime-owned
//! agent, dispatched natively under that agent's own context) or by
//! [`CoreAgent::turn`](crate::CoreAgent::turn) (the orchestrator of a runtime
//! the caller built themselves, dispatched as the `inference.agent_chat` RPC).
//! Both add the two things a turn needs that a plain config read does not:
//! **ambient scopes** and a **session identity**.
//!
//! # Why the params are a struct rather than `json!`
//!
//! The controller behind this method deserializes
//! the `agent_runs::agent_chat` controller params — which
//! carries no `#[serde(rename_all)]`, so its wire names are the Rust field names
//! exactly as spelled. Every embedder that hand-writes that JSON is therefore
//! depending on an unmarked, unversioned naming coincidence: rename a field
//! upstream and the call keeps compiling, keeps dispatching, and silently loses
//! the value. [`TurnRequest`] pins the spelling in one place, next to a test
//! that decodes it as the controller does.
//!
//! # The ambient origin scope, and why it is not optional
//!
//! A turn reads one `tokio` task-local that no parameter can carry yet:
//!
//! - **origin** ([`turn_origin`](openhuman_core::security::turn_origin)) — the
//!   caller's statement of authority. The approval gate is *fail-closed*: an
//!   unlabelled call gets the `Cli` default, and a caller wanting anything
//!   else — a workflow's blanket automation grant, say — must scope it around
//!   the dispatch. Miss it and the turn still succeeds while every acting tool
//!   quietly refuses, which reads as a bad model rather than a missing scope.
//!
//! Everything else a turn needs rides explicit values handed to the core
//! (`AgentChatEnv`): the **progress** sink
//! ([`AgentProgress`](openhuman_core::progress::AgentProgress)) and the host
//! environment (shared budget, delegation depth, cancellation, hooks, tool-belt
//! authority).
//!
//! The origin is established by [`Turn::send`], so a host never has to know it
//! exists. That is the whole reason this facade is worth having over `invoke`.

use std::path::{Path, PathBuf};
use std::sync::Arc;

use super::error::CoreError;
use openhuman_core::agent_runs::INFERENCE_AGENT_CHAT as AGENT_CHAT;
use openhuman_core::core::runtime::CoreRuntime;
use openhuman_core::progress::AgentProgress;
use openhuman_core::security::turn_origin::AgentTurnOrigin;

#[path = "turn_types.rs"]
mod types;
pub(crate) use types::{is_safe_endpoint_for_bearer, sanitize_url_for_display};
pub use types::{Route, TurnOutcome, TurnRequest};
#[path = "turn_control.rs"]
mod control;

/// Where a [`Turn`] is dispatched.
pub(crate) enum TurnTarget {
    /// The orchestrator of a caller-built runtime, via the
    /// `inference.agent_chat` RPC.
    Runtime(Arc<CoreRuntime>),
    /// A runtime-owned [`Agent`](crate::Agent), natively, under that agent's
    /// own [`CoreContext`](openhuman_core::core::runtime::CoreContext).
    Agent(Arc<crate::agent::AgentInner>),
}

/// One pending turn. Configure, then [`send`](Self::send).
///
/// Owned rather than borrowed: it holds an `Arc` to whatever it dispatches
/// on, so a host can build it in one place and send it from another.
pub struct Turn {
    budget: Option<crate::budget::ModelBudget>,
    dispatch_admission: Option<Arc<dyn crate::budget::PhysicalDispatchAdmission>>,
    /// A narrower model-directed delegation depth for this turn (fanout leaves).
    spawn_depth_limit: Option<usize>,
    /// The native token this turn's run tree observes, minted by `send` and
    /// handed to the core on the turn's host environment.
    native_cancellation: Option<crate::CancellationToken>,
    target: TurnTarget,
    request: TurnRequest,
    session_id: Option<String>,
    origin: Option<AgentTurnOrigin>,
    flow_run: Option<(String, String)>,
    progress: Option<tokio::sync::mpsc::Sender<AgentProgress>>,
    seed: Option<Vec<(String, String)>>,
    attachments: Vec<openhuman_core::agent::HostAttachment>,
    meter: Option<Box<dyn FnOnce(Option<LastTurnUsage>) + Send>>,
    response_format: Option<crate::complete::ResponseFormat>,
    structured_retries: u8,
    max_tokens: Option<u32>,
    top_p: Option<f64>,
    token_cancellation: Option<crate::CancellationToken>,
    provider_options: serde_json::Value,
    require_tool_call: bool,
    untrusted_input: bool,
    cancellation: Option<crate::TurnCancellation>,
    steering: Option<crate::TurnSteering>,
    timeout: Option<std::time::Duration>,
    control_deadline: Option<tokio::time::Instant>,
    observer: Option<Arc<dyn crate::observe::TurnObserver>>,
    trace_content: crate::observe::TraceContent,
    hooks: tinyagents_hooks::scope::HookScope<
        openhuman_core::agent::tinyagents::host::OpenHumanRunContext,
        tinyagents_harness::cost::TurnCost,
    >,
    tools: Option<openhuman_core::agent::HostTools>,
    tool_env: Option<Arc<std::collections::BTreeMap<String, String>>>,
}

impl Turn {
    pub(crate) fn new(target: TurnTarget, message: impl Into<String>) -> Self {
        Self {
            target,
            budget: None,
            dispatch_admission: None,
            spawn_depth_limit: None,
            native_cancellation: None,
            request: TurnRequest::new(message),
            session_id: None,
            origin: None,
            flow_run: None,
            progress: None,
            seed: None,
            attachments: Vec::new(),
            meter: None,
            response_format: None,
            structured_retries: 0,
            max_tokens: None,
            top_p: None,
            token_cancellation: None,
            provider_options: serde_json::Value::Null,
            require_tool_call: false,
            untrusted_input: false,
            cancellation: None,
            steering: None,
            timeout: None,
            control_deadline: None,
            observer: None,
            trace_content: crate::observe::TraceContent::MetadataOnly,
            hooks: Default::default(),
            tools: None,
            tool_env: None,
        }
    }

    pub(crate) fn with_agent_id(mut self, id: &str) -> Self {
        self.request.agent_id = Some(id.to_string());
        self
    }

    pub(crate) fn with_hooks(
        mut self,
        hooks: tinyagents_hooks::scope::HookScope<
            openhuman_core::agent::tinyagents::host::OpenHumanRunContext,
            tinyagents_harness::cost::TurnCost,
        >,
    ) -> Self {
        self.hooks = hooks;
        self
    }

    /// Add a tool callback for this turn only, after runtime and agent hooks.
    /// Does not change the agent or any other concurrent turn.
    pub fn tool_hook(
        mut self,
        hook: Arc<dyn crate::seams::ToolHook<crate::seams::OpenHumanRunContext>>,
    ) -> Self {
        self.hooks.push_tool(hook);
        self
    }

    /// Replace this turn's host tools, including attached sources. An empty
    /// belt revokes them. Builtin tools remain governed by the agent definition;
    /// the agent's original host tools return on its next turn.
    pub fn tools(
        mut self,
        factory: impl for<'a> Fn(
                openhuman_core::agent::TurnContext<'a>,
            ) -> openhuman_core::agent::HostTurnTools
            + Send
            + Sync
            + 'static,
    ) -> Self {
        self.tools = Some(Arc::new(factory));
        self
    }

    /// Replace the environment of owned builtin tool subprocesses for this
    /// turn. Variables absent from this map are not inherited from the daemon.
    /// Interpreter pools are bypassed so a pooled process cannot carry another
    /// turn's environment. Independently spawned host tasks must carry the scope.
    pub fn tool_env(mut self, env: impl IntoIterator<Item = (String, String)>) -> Self {
        self.tool_env = Some(Arc::new(env.into_iter().collect()));
        self
    }

    /// Await the host's permission decision before each tool executes.
    /// The callback may wait for UI approval, then return `Proceed`, `Deny`,
    /// or `ProceedWith`. Returning `Ask` denies the call; this callback itself
    /// owns the approval wait. Static tool/security restrictions still apply.
    /// Agent and turn callbacks are additive: a denial cannot be overridden.
    pub fn can_use_tool<F>(self, callback: F) -> Self
    where
        F: for<'a> Fn(&'a crate::seams::ToolHookContext) -> crate::PermissionFuture<'a>
            + Send
            + Sync
            + 'static,
    {
        self.tool_hook(std::sync::Arc::new(crate::permission::PermissionHook::new(
            callback,
        )))
    }

    /// Observe cumulative usage after each model call or vote to stop before
    /// the next call. Return `StopDecision::Continue` for observation alone;
    /// a budget policy can return `StopDecision::Stop`. Scoped to this turn; no runtime-global policy is replaced.
    pub fn stop_hook(
        mut self,
        hook: std::sync::Arc<dyn crate::seams::StopHook<crate::seams::TurnCost>>,
    ) -> Self {
        self.hooks.push_stop(hook);
        self
    }

    /// Add a completed-turn callback for this turn only. The callback runs
    /// asynchronously with an owned snapshot after the turn completes.
    pub fn post_turn_hook(mut self, hook: Arc<dyn crate::seams::LearningSink>) -> Self {
        self.hooks.push_learning(hook);
        self
    }

    /// Continue an existing conversation. Without this a fresh session id is
    /// minted and returned in [`TurnOutcome::session_id`].
    pub fn session(mut self, session_id: impl Into<String>) -> Self {
        self.session_id = Some(session_id.into());
        self
    }

    /// Run this turn against `history` instead of whatever the session holds.
    ///
    /// Rows are `(role, content)` -- `"system"`, `"user"`, `"assistant"` --
    /// and they replace resume rather than adding to it: the session's own
    /// history is dropped, these are put in its place, and the durable
    /// transcript is not reloaded for this turn.
    ///
    /// # When a host wants this
    ///
    /// A host whose conversations live in its own log -- a journal, a board,
    /// an episode -- is the only thing that can say what a turn should have
    /// seen. That view is rarely the session's: it may be scoped to one
    /// conversation, filtered to what this agent is allowed to read, windowed,
    /// or cut at a watermark. Seeding is how it reaches the model with roles
    /// intact. Passing the same thing as prose in the message would flatten
    /// the agent's own prior turns into quoted text, which is not the same
    /// input.
    ///
    /// # It replaces, silently
    ///
    /// Seeding a session that already holds a conversation **discards that
    /// conversation** -- the history is cleared and these rows put in its
    /// place. Nothing refuses the call, because the case this exists for is a
    /// host re-deriving the whole view every turn, for which replacement is
    /// the point rather than a hazard.
    ///
    /// So pair it with a [`session`](Self::session) id of its own. A turn that
    /// seeds, or that varies its belt or its prompt, wants a session it is not
    /// sharing with turns that expect their history to still be there.
    ///
    /// Only a runtime-owned [`Agent`](crate::Agent) can honour this; a turn on
    /// a caller-built runtime's orchestrator is refused rather than run
    /// unseeded, since silently dropping the history would run the agent
    /// blind.
    ///
    /// ```no_run
    /// # use openhuman_embed::Agent;
    /// # async fn go(agent: &Agent, rows: Vec<(String, String)>) -> anyhow::Result<()> {
    /// agent.turn("what did we decide?")
    ///     .session(format!("turn-{}", uuid::Uuid::new_v4()))
    ///     .seed(rows)
    ///     .send()
    ///     .await?;
    /// # Ok(()) }
    /// ```
    pub fn seed(mut self, history: Vec<(String, String)>) -> Self {
        self.seed = Some(history);
        self
    }

    /// Attach a file to this turn's message, after any already attached.
    ///
    /// The host hands over the bytes; the file is staged into the agent's
    /// acting workspace and reaches the model ahead of the message, as an
    /// image block (`image/*`) or a document block (anything else). A model
    /// that cannot take the file natively gets the core's fallback instead:
    /// extracted text for documents, a vision readout for images. The
    /// configured multimodal count and size limits apply, and a turn over
    /// them fails before it runs. No local path is read, so attachments are
    /// accepted whatever the turn's [`origin`](Self::origin).
    ///
    /// Only a runtime-owned [`Agent`](crate::Agent) can honour this; a turn on
    /// a caller-built runtime's orchestrator is refused rather than run
    /// without its files.
    ///
    /// ```no_run
    /// # use openhuman_embed::{Agent, HostAttachment};
    /// # async fn go(agent: &Agent, photo: Vec<u8>) -> anyhow::Result<()> {
    /// agent.turn("what is in this picture?")
    ///     .attach(HostAttachment::new(photo, "image/jpeg").named("photo.jpg"))
    ///     .send()
    ///     .await?;
    /// # Ok(()) }
    /// ```
    #[must_use]
    pub fn attach(mut self, attachment: openhuman_core::agent::HostAttachment) -> Self {
        self.attachments.push(attachment);
        self
    }

    /// Attach every file in `attachments`, in order; see [`attach`](Self::attach).
    #[must_use]
    pub fn attachments(
        mut self,
        attachments: impl IntoIterator<Item = openhuman_core::agent::HostAttachment>,
    ) -> Self {
        self.attachments.extend(attachments);
        self
    }

    /// Report what this turn spent, whether or not it succeeded.
    ///
    /// [`TurnOutcome::usage`] carries the same figures, but only when there is
    /// an outcome to carry them on. A host that meters its agents cannot let a
    /// failed turn go unbilled -- a turn that ran, called tools and then
    /// errored spent real tokens, and an agent whose failures are free is an
    /// agent whose costs are understated exactly where they run highest.
    ///
    /// `f` is called once, after the turn settles and before its error (if
    /// any) is returned -- so a turn that ran and then failed is reported.
    ///
    /// It does **not** fire for a turn refused before dispatch, such as one
    /// whose [`route`](Self::route) pairs a bearer with a plain-http endpoint:
    /// nothing ran, so there is nothing to bill. `None` means the turn ran but
    /// the session reported no usage, which is not the same as zero.
    ///
    /// ```no_run
    /// # use openhuman_embed::Agent;
    /// # async fn go(agent: &Agent) -> anyhow::Result<()> {
    /// let (tx, rx) = std::sync::mpsc::channel();
    /// let result = agent.turn("go")
    ///     .meter(move |spent| { let _ = tx.send(spent); })
    ///     .send()
    ///     .await;
    /// let spent = rx.recv().ok().flatten();   // arrives even if `result` is an error
    /// # let _ = (result, spent); Ok(()) }
    /// ```
    #[must_use]
    pub fn meter(mut self, f: impl FnOnce(Option<LastTurnUsage>) + Send + 'static) -> Self {
        self.meter = Some(Box::new(f));
        self
    }

    /// Ask every model call of this turn for `format`.
    ///
    /// Applied to each call of the tool loop, so a provider that honours
    /// structured outputs keeps calling tools and shapes its final answer.
    /// Allow up to three extra attempts to repair invalid structured output.
    #[must_use]
    pub fn structured_retries(mut self, attempts: u8) -> Self {
        self.structured_retries = attempts;
        self
    }

    /// Set the requested structured output shape.
    pub fn response_format(mut self, format: crate::complete::ResponseFormat) -> Self {
        self.response_format = Some(format);
        self
    }

    /// Pass gateway routing/reasoning options to every model call in this turn.
    #[must_use]
    pub fn provider_options(mut self, options: serde_json::Value) -> Self {
        self.provider_options = options;
        self
    }

    /// Require a successful tool execution before accepting the final answer.
    /// The first calls advertise required tools and omit the final schema;
    /// gateways that ignore the tool hint are refused deterministically.
    #[must_use]
    pub fn require_tool_call(mut self, required: bool) -> Self {
        self.require_tool_call = required;
        self
    }

    /// Cap every model call of this turn at `n` output tokens, replacing the
    /// agent turn's default cap. Runtime-owned agents only, as
    /// [`response_format`](Self::response_format).
    #[must_use]
    pub fn max_tokens(mut self, n: u32) -> Self {
        self.max_tokens = Some(n);
        self
    }

    /// The message is untrusted data to read, not an instruction: skip the
    /// prompt-injection guard.
    ///
    /// An analyst must be able to read a document that says "ignore previous
    /// instructions"; the guard would refuse it. Allowed **only** on an agent
    /// built with [`ToolScopeSpec::HostOnly`](crate::ToolScopeSpec::HostOnly),
    /// which has nothing it could be talked into doing. On any other agent
    /// the turn is refused with a [`CoreError::Domain`] of kind
    /// `untrusted_input_requires_host_only`. Fence and label the data in the
    /// message all the same.
    #[must_use]
    pub fn untrusted_input(mut self, untrusted: bool) -> Self {
        self.untrusted_input = untrusted;
        self
    }

    /// Pin this turn to a model id.
    pub fn model(mut self, model: impl Into<String>) -> Self {
        self.request.model_override = Some(model.into());
        self
    }

    /// Enforce the ledger across this tool loop, retries and synchronous children.
    pub fn budget(mut self, budget: crate::budget::ModelBudget) -> Self {
        self.budget = Some(budget);
        self
    }

    /// Share a host-owned physical-dispatch policy with this turn and its children.
    pub fn dispatch_admission(
        mut self,
        admission: Arc<dyn crate::budget::PhysicalDispatchAdmission>,
    ) -> Self {
        self.dispatch_admission = Some(admission);
        self
    }

    /// Narrow the model-directed delegation depth for this turn tree.
    pub(crate) fn with_spawn_depth_limit(mut self, limit: usize) -> Self {
        self.spawn_depth_limit = Some(limit);
        self
    }

    /// Set the sampling temperature for this turn.
    pub fn temperature(mut self, temperature: f64) -> Self {
        self.request.temperature = Some(temperature);
        self
    }

    /// Root this turn's filesystem and shell tools at `dir`.
    pub fn cwd(mut self, dir: impl AsRef<Path>) -> Self {
        self.request.cwd = Some(dir.as_ref().to_string_lossy().into_owned());
        self
    }

    /// Send this turn to a specific endpoint instead of the account's route.
    pub fn route(mut self, route: Route) -> Self {
        self.request.inference_url = Some(route.base_url);
        self.request.api_key = Some(route.api_key);
        self.request.inference_headers = route.headers;
        self.request.inference_provider_options = route.provider_options;
        self.request.inference_reasoning_effort = route
            .reasoning_effort
            .map(|effort| effort.as_str().to_string());
        self
    }

    /// Declare the authority this turn runs with.
    ///
    /// Unset means the core's own default for a direct chat dispatch (`Cli`),
    /// which is a trusted-operator allowance. Set it when the turn is *not* a
    /// human at a terminal — a workflow node, a scheduled job — so the approval
    /// gate applies the narrower grant the caller actually meant.
    pub fn origin(mut self, origin: AgentTurnOrigin) -> Self {
        self.origin = Some(origin);
        self
    }

    /// Binds the turn to one run of a saved flow, so an approval a tool call
    /// parks on this turn is correlated back to that exact flow and run. Pair
    /// it with a [`TrustedAutomationSource::Workflow`] [`origin`](Self::origin):
    /// the origin only names the flow, not the run.
    ///
    /// [`TrustedAutomationSource::Workflow`]: crate::TrustedAutomationSource::Workflow
    pub fn flow_run(mut self, flow_id: impl Into<String>, run_id: impl Into<String>) -> Self {
        self.flow_run = Some((flow_id.into(), run_id.into()));
        self
    }

    /// Nucleus sampling for this turn; must be finite and between zero and one.
    pub fn top_p(mut self, probability: f64) -> Self {
        self.top_p = Some(probability);
        self
    }

    /// Bind caller cancellation to the turn and its recursive tool/agent tree.
    pub fn cancellation(mut self, token: crate::CancellationToken) -> Self {
        self.token_cancellation = Some(token);
        self
    }

    pub(crate) fn stream_cancellation(&self) -> crate::CancellationToken {
        self.token_cancellation.clone().unwrap_or_default()
    }

    /// Start this configured turn as an owned stream, cancelled when dropped.
    pub fn stream(self) -> crate::TurnStream {
        crate::TurnStream::start(self)
    }

    /// Stream live turn progress — tool calls, deltas, turn boundaries.
    ///
    /// The core **awaits** its sends, so the channel's capacity is real
    /// backpressure on the turn: a receiver that stops draining stalls it.
    pub fn on_progress(mut self, sink: tokio::sync::mpsc::Sender<AgentProgress>) -> Self {
        self.progress = Some(sink);
        self
    }

    /// The wire params this turn will send, for inspection and tests.
    pub fn request(&self) -> &TurnRequest {
        &self.request
    }
}

/// Run `request` on `target`.
///
/// The RPC target goes through [`call`], so the `{result, logs}` envelope,
/// [`DomainSet`](openhuman_core::core::runtime::DomainSet) gating and error
/// classification are handled like every other facade method. The agent
/// target reaches `agent_chat_for` natively under the agent's own context —
/// the definition it carries cannot travel as JSON — so it applies the
/// DomainSet gate itself before touching the core.
use openhuman_core::agent::tinyagents::host::LastTurnUsage;

use crate::turn_meter::UsageSink;

use tinyagents_harness::middleware::{FinalResponse, ResponseShapeScope};

/// A turn's reply text and, for an agent target, its final-response report.
type AgentReply = (String, Option<FinalResponse>);

/// A boxed, sendable future, without a `futures` dependency for one alias.
mod futures_box {
    pub(super) type BoxFuture<'a, T> =
        std::pin::Pin<Box<dyn std::future::Future<Output = T> + Send + 'a>>;
}

/// What only an agent target can honour, already validated by
/// [`Turn::validate_turn_options`].
struct AgentTurnOptions {
    tools: Option<openhuman_core::agent::HostTools>,
    shape: std::sync::Arc<ResponseShapeScope>,
    observer:
        Option<std::sync::Arc<tinyagents_harness::observability::turn_observer::ObserverScope>>,
    untrusted_input: bool,
    attachments: Vec<openhuman_core::agent::HostAttachment>,
    /// The explicit per-turn values the core honours: live progress and the
    /// host environment (budget, depth, cancellation, hooks, tool-belt authority).
    chat_env: openhuman_core::agent_runs::agent_chat::AgentChatEnv,
}

async fn dispatch(
    target: TurnTarget,
    request: TurnRequest,
    seed: Option<Vec<(String, String)>>,
    usage: &UsageSink,
    options: AgentTurnOptions,
) -> Result<AgentReply, CoreError> {
    match target {
        TurnTarget::Runtime(rt) => {
            // Refused rather than dropped. `AGENT_CHAT`'s params are a wire
            // contract and carry no history, so this path cannot seed -- and a
            // turn that asked for history and silently ran without it would be
            // the agent answering blind, which is worse than a clear error.
            //
            // `Domain`, not `Unavailable`: the latter means the method was
            // compiled or configured out and tells hosts to degrade the
            // surface. `AGENT_CHAT` is fully present here; it is this one
            // request that cannot be served, which is a caller error and an
            // expected user-visible state rather than a missing capability.
            if seed.is_some() {
                return Err(CoreError::Domain {
                    method: AGENT_CHAT,
                    message: "seeded history is not supported on a caller-built runtime's \
                              orchestrator; run the turn on a runtime-owned Agent"
                        .to_owned(),
                    kind: Some("seed_unsupported".to_owned()),
                    data: None,
                    expected_user_state: true,
                });
            }
            // Refused for the same reason: `AGENT_CHAT` carries a string, and
            // a turn that silently ran without its files would answer about
            // something it never saw.
            if !options.attachments.is_empty() {
                return Err(CoreError::Domain {
                    method: AGENT_CHAT,
                    message: "attachments are not supported on a caller-built runtime's \
                              orchestrator; run the turn on a runtime-owned Agent"
                        .to_owned(),
                    kind: Some("attachments_unsupported".to_owned()),
                    data: None,
                    expected_user_state: true,
                });
            }
            // Native, like the `Agent` arm: the progress sink and host
            // environment are non-serializable values that ride the call as
            // explicit arguments, which the JSON-RPC envelope could not carry.
            // Gated and scoped exactly as the RPC dispatch would be.
            if !rt.context().domains().inference {
                return Err(CoreError::Unavailable { method: AGENT_CHAT });
            }
            let ctx = std::sync::Arc::clone(rt.context());
            let chat_env = options.chat_env;
            let dispatch =
                openhuman_core::core::runtime::DispatchCtx::new(std::sync::Arc::clone(&ctx));
            let turn: futures_box::BoxFuture<'_, Result<AgentReply, CoreError>> =
                Box::pin(async move {
                    use openhuman_core::inference::host_runtime::ops::{
                        agent_chat_reply_for_controlled, AgentChatTarget,
                    };
                    let mut config = dispatch
                        .load_config()
                        .await
                        .map_err(|raw| CoreError::from_rpc_string(AGENT_CHAT, raw))?;
                    let target = match request.agent_id.as_deref().map(str::trim) {
                        Some(id) if !id.is_empty() => AgentChatTarget::AgentId(id),
                        _ => AgentChatTarget::Orchestrator,
                    };
                    let route = openhuman_core::config::schema::EphemeralRoute::from_params(
                        request.inference_url.clone(),
                        request.api_key.clone(),
                    )
                    .map(|route| route.with_headers(request.inference_headers.clone()));
                    let route = route
                        .map(|route| {
                            route.with_provider_options(request.inference_provider_options.clone())
                        })
                        .map(|route| {
                            route.with_reasoning_effort(request.inference_reasoning_effort.clone())
                        });
                    agent_chat_reply_for_controlled(
                        &mut config,
                        target,
                        &request.message,
                        request.model_override.clone(),
                        request.temperature,
                        request.thread_id.clone(),
                        request.cwd.clone(),
                        route,
                        chat_env,
                    )
                    .await
                    .map(|reply| (reply.text, None))
                    .map_err(|error| map_agent_chat_error(error, None))
                });
            rt.run_in(ctx, turn).await
        }
        TurnTarget::Agent(agent) => {
            if !agent.ctx.domains().inference {
                return Err(CoreError::Unavailable { method: AGENT_CHAT });
            }
            let ctx = agent.ctx.clone();
            let inner = agent.clone();
            let runtime = agent.runtime.clone();
            // Boxed: the native turn future is the entire tinyagents harness
            // inlined, and nesting it inside `Turn::send`'s own state machine
            // pushes rustc's layout query past its depth limit. One heap
            // allocation per turn is nothing next to the turn itself.
            let turn: futures_box::BoxFuture<'_, Result<AgentReply, CoreError>> =
                Box::pin(async move {
                    use openhuman_core::inference::host_runtime::ops::{
                        agent_chat_reply_for_controlled, AgentChatTarget,
                    };
                    let mut config = inner.config.clone();
                    let route = inference_route(&request);
                    let host = options.tools.or_else(|| inner.composed_host_tools());
                    let target = AgentChatTarget::Definition {
                        definition: &inner.definition,
                        host: host.as_ref(),
                        seed: seed.as_deref(),
                        usage: Some(usage),
                        host_only: inner.host_only,
                        untrusted_input: options.untrusted_input,
                        shape: Some(&options.shape),
                        observer: options.observer.as_ref(),
                        attachments: &options.attachments,
                    };
                    let outcome = agent_chat_reply_for_controlled(
                        &mut config,
                        target,
                        &request.message,
                        request.model_override,
                        request.temperature,
                        request.thread_id,
                        request.cwd,
                        route,
                        options.chat_env,
                    )
                    .await
                    .map(|reply| reply.into_outcome());
                    // The shape preserves provider charges and root-call totals
                    // absent from normalized session usage. Overlay before both
                    // meter and outcome reads, retaining child/session metadata.
                    let report = options.shape.report();
                    {
                        let mut captured = usage
                            .lock()
                            .unwrap_or_else(std::sync::PoisonError::into_inner);
                        if let Some(spent) = &report.usage {
                            types::overlay_response_usage(&mut captured, spent);
                        }
                        if let Some(spent) = captured.as_mut() {
                            spent.reasoning_tokens = report.reasoning_tokens;
                        }
                    }
                    if let Err(error) = &outcome {
                        if let Some(refusal) =
                            error.downcast_ref::<crate::budget::DispatchRefusal>()
                        {
                            return Err(CoreError::DispatchAdmission {
                                method: AGENT_CHAT,
                                source: *refusal,
                                usage: report.usage.map(|spent| crate::complete::CompletionUsage {
                                    input_tokens: spent.input_tokens,
                                    output_tokens: spent.output_tokens,
                                    cached_tokens: spent.cached_tokens,
                                    reasoning_tokens: spent.reasoning_tokens,
                                    cost_usd: spent.cost_usd,
                                }),
                            });
                        }
                    }
                    if outcome.is_err() && report.structured_failed {
                        use crate::structured::{
                            StructuredFailureReason as Reason, StructuredOutputFailure,
                        };
                        let reason = match report.validation_error.as_deref() {
                            Some("RequiredToolCallMissing") => Reason::RequiredToolCallMissing,
                            Some("Truncated") => Reason::Truncated,
                            Some("SchemaMismatch") => Reason::SchemaMismatch,
                            _ => Reason::InvalidJson,
                        };
                        return Err(CoreError::StructuredOutput {
                            method: AGENT_CHAT,
                            failure: StructuredOutputFailure {
                                attempts: report.structured_attempts,
                                reason,
                                finish_reason: report.finish_reason,
                                answered_model: report.answered_model,
                                usage: report.usage.map(|spent| crate::complete::CompletionUsage {
                                    input_tokens: spent.input_tokens,
                                    output_tokens: spent.output_tokens,
                                    cached_tokens: spent.cached_tokens,
                                    reasoning_tokens: spent.reasoning_tokens,
                                    cost_usd: spent.cost_usd,
                                }),
                            },
                        });
                    }
                    match outcome {
                        Ok(outcome) => Ok((outcome.value, Some(report))),
                        Err(error) => Err(map_agent_chat_error(error, report.usage)),
                    }
                });
            agent
                .lifecycle
                .admit(&agent.id, AGENT_CHAT, runtime.run_in(ctx, turn))
                .await
        }
    }
}

/// The per-call inference route `request` names (endpoint, bearer, headers,
/// provider options, reasoning effort), applied to the agent's config in
/// memory for that call alone.
pub(crate) fn inference_route(
    request: &TurnRequest,
) -> Option<openhuman_core::config::schema::EphemeralRoute> {
    openhuman_core::config::schema::EphemeralRoute::from_params(
        request.inference_url.clone(),
        request.api_key.clone(),
    )
    .map(|route| route.with_headers(request.inference_headers.clone()))
    .map(|route| route.with_provider_options(request.inference_provider_options.clone()))
    .map(|route| route.with_reasoning_effort(request.inference_reasoning_effort.clone()))
}

fn map_agent_chat_error(
    error: anyhow::Error,
    usage: Option<tinyagents_harness::middleware::ResponseUsage>,
) -> CoreError {
    if let Some(refusal) = error.downcast_ref::<crate::budget::DispatchRefusal>() {
        return CoreError::DispatchAdmission {
            method: AGENT_CHAT,
            source: *refusal,
            usage: usage.map(|spent| crate::complete::CompletionUsage {
                input_tokens: spent.input_tokens,
                output_tokens: spent.output_tokens,
                cached_tokens: spent.cached_tokens,
                reasoning_tokens: spent.reasoning_tokens,
                cost_usd: spent.cost_usd,
            }),
        };
    }
    CoreError::from_rpc_string(AGENT_CHAT, error.to_string())
}

fn validate_route(request: &TurnRequest) -> Result<(), CoreError> {
    let route_requested = request.inference_url.is_some() || request.api_key.is_some();
    if route_requested
        && (request
            .inference_url
            .as_deref()
            .is_none_or(|value| value.trim().is_empty())
            || request
                .api_key
                .as_deref()
                .is_none_or(|value| value.trim().is_empty()))
    {
        return Err(CoreError::InvalidRoute { method: AGENT_CHAT });
    }
    Ok(())
}

/// Absolute form of `dir`, for callers assembling a [`Turn::cwd`] from a
/// relative path. The core resolves a relative `cwd` against its own
/// `action_dir`, which is rarely what a library caller means.
pub fn absolute(dir: impl AsRef<Path>) -> std::io::Result<PathBuf> {
    let dir = dir.as_ref();
    if dir.is_absolute() {
        return Ok(dir.to_path_buf());
    }
    Ok(std::env::current_dir()?.join(dir))
}

#[cfg(test)]
#[path = "turn_tests.rs"]
mod tests;

fn event_thread_id(origin: Option<&AgentTurnOrigin>, session_id: &str) -> String {
    match origin {
        Some(AgentTurnOrigin::WebChat { thread_id, .. }) => thread_id.clone(),
        _ => session_id.to_owned(),
    }
}

struct ObservedTurn {
    hub: Arc<crate::events::EventHub>,
    agent_id: Option<String>,
    thread_id: String,
    turn_id: String,
    success: bool,
}
impl Drop for ObservedTurn {
    fn drop(&mut self) {
        self.hub.end_turn(
            self.agent_id.clone(),
            &self.thread_id,
            &self.turn_id,
            self.success,
        );
    }
}
fn observe_progress(
    hub: &crate::events::EventHub,
    agent_id: &Option<String>,
    turn_id: &str,
    item: &AgentProgress,
) {
    let kind = match item {
        AgentProgress::ToolCallStarted { tool_name, .. } => {
            Some(crate::RuntimeEventKind::ToolStarted {
                tool_name: tool_name.clone(),
            })
        }
        AgentProgress::ToolCallCompleted {
            tool_name, success, ..
        } => Some(crate::RuntimeEventKind::ToolEnded {
            tool_name: tool_name.clone(),
            success: *success,
        }),
        _ => None,
    };
    if let Some(kind) = kind {
        hub.emit(agent_id.clone(), Some(turn_id.to_owned()), kind);
    }
}