Skip to content

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

6.1 KB
Raw Blame
//! Explicit host environment for one agent turn.
//!
//! An entry point that drives a turn on behalf of a host (the embed facade, the
//! web channel, a scheduler) owns a handful of per-turn values the harness has
//! to honour: the shared model-spend budget, a narrower delegation depth, the
//! caller's cancellation, the wall-clock backstop, hook callbacks, and whether
//! the host's tool belt is authoritative over a restored transcript. They used
//! to ride ambient task-locals that every layer below re-read, which silently
//! stopped working across a `tokio::spawn` and could not be seen from a
//! signature. This value is handed to the session instead
//! ([`OpenHumanSessionHost::set_host_env`](crate::agent::OpenHumanSessionHost::set_host_env));
//! the session copies it onto the turn's explicit
//! [`OpenHumanRunContext`](crate::agent::tinyagents::host::OpenHumanRunContext),
//! whose `child()` hands it down the sub-agent tree.

use std::sync::Arc;

use tinyagents_harness::cancel::CancellationToken;
use tinyagents_harness::turn_deadline::TurnDeadline;

use crate::agent::tinyagents::host::OpenHumanRunContext;
use tinyagents_harness::cost::ModelBudget;

/// Per-turn values an entry point hands to the session it runs.
///
/// Every field defaults to "nothing narrowed", so `HostTurnEnv::default()` is a
/// turn exactly as it ran before any host policy existed.
#[derive(Clone, Default)]
pub struct HostTurnEnv {
    /// Host-issued media refs belonging only to this external turn.
    pub(crate) native_staged_parts: Vec<tinychannels_bus::ContentPart>,
    /// Provider message identity used when binding staged media after commit.
    pub(crate) native_message_id: Option<String>,
    /// Root-only cleanup/commit state for the staged native refs above.
    pub(crate) native_staged_lease: Option<crate::threads::attachments::NativeStagedLease>,
    /// Exact child-process environment values supplied by the embedding host.
    ///
    /// The map is carried through the run context so module-backed shell
    /// execution receives the same explicit environment as native tools.
    pub command_environment: Option<Arc<std::collections::BTreeMap<String, String>>>,
    /// Shared model-spend ledger and per-call bounds every model call of the
    /// turn tree is charged against.
    pub model_budget: Option<ModelBudget>,
    /// Shared physical-dispatch policy for this turn and its synchronous or
    /// detached children.
    pub dispatch_admission: Option<Arc<dyn super::tinyagents::budget::PhysicalDispatchAdmission>>,
    /// A narrower model-directed delegation depth than the product ceiling.
    pub spawn_depth_limit: Option<usize>,
    /// The caller's cancellation, shared with every child run. `None` runs the
    /// turn under a fresh token only the session itself can fire.
    pub cancellation: Option<CancellationToken>,
    /// The wall-clock backstop the harness winds down before.
    pub turn_deadline: Option<TurnDeadline>,
    /// A cap on real tool invocations, never wider than the product default.
    pub tool_call_limit: Option<usize>,
    /// Agent/turn hook callbacks added after the runtime's global ones.
    pub hooks:
        tinyagents_hooks::scope::HookScope<OpenHumanRunContext, tinyagents_harness::cost::TurnCost>,
    /// The host's tool belt for this turn is authoritative: tool declarations
    /// recorded in a restored transcript must not bring a revoked tool back.
    pub fresh_tool_snapshot: bool,
    /// The approval context of the turn an entry point starts here (chat
    /// surface, copilot flag, flow run), for the entry points that hand the
    /// turn its environment as one value (the embed facade, `agent_chat`). The
    /// session reads it once, for the root turn; it is never copied to
    /// children ([`OpenHumanRunContext::with_host_env`] leaves it out), which
    /// take theirs from their parent's run context.
    ///
    /// [`OpenHumanRunContext::with_host_env`]: crate::agent::tinyagents::host::OpenHumanRunContext
    pub approval: crate::security::approval::ApprovalTurnContext,
    /// Who the runs this environment starts act as on memory, when the entry
    /// point knows more than "the host itself": a team member's identity, which
    /// a turn or sub-agent narrows with `child(<definition id>)`. `None` is the
    /// root identity. Unlike `approval` it follows delegation, so runs started
    /// from a parent snapshot keep the parent's team.
    pub memory_identity: Option<tinymemory_tools::layout::identity::Identity>,
    /// The [`CoreContext`](crate::core::runtime::CoreContext) the turn runs
    /// under (the tenant's, an embedded agent's, or the host's own), held
    /// weakly: the env outlives a turn, and a strong handle would keep the
    /// tenant in use. The session copies it onto the turn's run context, from
    /// which tools, middleware and the provider factory read it; `None` leaves
    /// the session to bind the calling task's context when the turn starts.
    pub core: Option<std::sync::Weak<crate::core::runtime::CoreContext>>,
}

impl std::fmt::Debug for HostTurnEnv {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("HostTurnEnv")
            .field("native_staged_parts", &self.native_staged_parts.len())
            .field("has_native_message_id", &self.native_message_id.is_some())
            .field("command_environment", &self.command_environment.is_some())
            .field("model_budget", &self.model_budget.is_some())
            .field("dispatch_admission", &self.dispatch_admission.is_some())
            .field("spawn_depth_limit", &self.spawn_depth_limit)
            .field("cancellation", &self.cancellation.is_some())
            .field("turn_deadline", &self.turn_deadline.is_some())
            .field("tool_call_limit", &self.tool_call_limit)
            .field("hooks_empty", &self.hooks.is_empty())
            .field("fresh_tool_snapshot", &self.fresh_tool_snapshot)
            .field("approval", &self.approval)
            .field("memory_identity", &self.memory_identity)
            .field("core", &self.core.is_some())
            .finish()
    }
}

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