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
//! Typed embedding facade over [`CoreRuntime`].
//!
//! Two ways in:
//!
//! * **[`Runtime`] → [`Agent`]** — the library API. Initialise one runtime
//! (features, services, backend, the TinyHumans API key), then instantiate
//! any number of independently configured agents on it, each with its own
//! MCP servers, skills, working directory, access tier, provider and
//! prompt. [`Harness`] is the one-agent shorthand over the same two types.
//! * **[`Core`]** — the typed facade over a [`CoreRuntime`] the host built
//! itself with [`CoreBuilder`].
//! [`CoreRuntime::invoke`] gives it JSON; this facade gives it real Rust
//! types, so a host never writes `serde_json::json!` or matches on an
//! error string.
//!
//! ```no_run
//! # async fn demo() -> Result<(), Box<dyn std::error::Error>> {
//! use std::sync::Arc;
//! use openhuman_embed::Core;
//! use openhuman_embed::{CoreBuilder, DomainSet, HostKind, ServiceSet};
//!
//! let runtime = CoreBuilder::new(HostKind::detect_standalone())
//! .domains(DomainSet::full())
//! .services(ServiceSet::none())
//! .build()
//! .await?;
//!
//! let core = Core::from_runtime(Arc::new(runtime));
//! let flags = core.config().runtime_flags().await?;
//! println!("log_prompts={}", flags.log_prompts);
//! # Ok(())
//! # }
//! ```
//!
//! # Shape: a struct with borrowed sub-facades, not a trait
//!
//! A single trait spanning every domain would run to well over a hundred
//! methods and force each test double to stub all of them. Instead [`Core`] is
//! a concrete struct whose accessors return zero-cost newtypes over a borrow.
//!
//! Traits appear in exactly one place in this architecture — the **ports**,
//! where a host injects behaviour *downward* into the core (a workflow's
//! harness dispatcher, for instance). Facade and port are opposite directions
//! and deliberately use opposite mechanisms:
//!
//! | Direction | Mechanism |
//! |---|---|
//! | host calls core | this facade — concrete struct, typed methods |
//! | core calls host | a port — trait object installed by the host |
//!
//! # Gated domains
//!
//! Sub-facade accessors for gated domains are `#[cfg]`-compiled, so
//! `core.workflows()` simply does not exist in a build without that feature —
//! a compile error at the call site rather than a runtime surprise. For domains
//! present at compile time but switched off at runtime via
//! [`DomainSet`], calls return
//! [`CoreError::Unavailable`] so a host can hide the surface instead of
//! reporting a failure.
// The owned streaming task proves Send for the core’s deeply nested turn future.
#![recursion_limit = "256"]
#![warn(missing_docs)]
#![cfg_attr(docsrs, feature(doc_cfg))]
/// Complete definition accepted by [`AgentDefinitionSpec::from_base`].
pub use openhuman_core::agent_registry::host_definition::AgentDefinition;
pub use openhuman_core::security::turn_origin::{AgentTurnOrigin, TrustedAutomationSource};
/// The origin of the executing turn, with its original chat or channel route.
///
/// Read this inside a host tool or permission callback. The value belongs to
/// this task's turn, so overlapping messages never replace its sender or
/// reply target. `None` means the caller installed no origin; it grants no
/// authority. Scheduled turns retain their existing automation origin.
pub fn current_turn_origin() -> Option<AgentTurnOrigin> {
openhuman_core::core::runtime::CoreContext::current_turn_origin()
}
pub use openhuman_core::config::ComposioHostCredential;
pub use openhuman_core::config::Config as RuntimeConfig;
pub use openhuman_core::config::{SearchHostCredential, UnknownKeyedSearchProvider};
/// The exact ambient tenant, inherited across profile turns and their scoped tasks.
pub use openhuman_core::core::runtime::{current_tenant, NoTenant, Tenant};
pub use openhuman_core::security::TrustedAccess;
pub use openhuman_core::tools::toolpacks::{GroupMode, ToolGroups};
/// Reasoning effort values accepted by routed inference providers.
pub use tinyinference_llm::model::ReasoningEffort;
// The seam `AgentSpec::tools` needs: the belt types, and `Tool` itself from the
// vendored tinytools. An embedder that took `tinytools` as its own dependency
// would build tools of a different, incompatible type.
pub use openhuman_core::agent::tinyagents::host::LastTurnUsage;
pub use openhuman_core::agent::{HostAttachment, HostTools, HostTurnTools, TurnContext};
pub use openhuman_core::{
CoreBootMode, CoreBuilder, CoreRuntime, DaemonConfig, DomainSet, HostKind, ServiceSet,
TokenSource,
};
/// Declarative execution requirements for host-owned tools, from the core's vendored contract.
pub use tinytools::ToolPolicy;
pub use tinytools::{PermissionLevel, Tool, ToolExposure, ToolResult};
/// Live agent-turn progress for in-process embedders.
pub mod agent_progress {
pub use openhuman_core::progress::AgentProgress;
/// The bounded in-process channel an embedder supplies for one agent turn.
pub type ProgressSink = tokio::sync::mpsc::Sender<AgentProgress>;
}
/// The skill registry: the host transport an embedder passes to
/// `tinyskills::SkillRegistry::builder`, and the process registry the core
/// itself serves catalog RPC and tools from.
#[cfg(feature = "skills")]
pub mod skill_registry {
pub use openhuman_core::skills::catalog::{
skill_registry, ReqwestTransport, HERMES_REGISTRY_ID,
};
}
mod agent;
pub mod artifacts;
mod auth;
pub mod budget;
mod call;
#[cfg(feature = "channels")]
pub mod channels;
pub mod chat_surface;
pub mod complete;
pub mod config;
/// Pure command-line argument parsers shared by host-owned command facades.
pub mod cli {
pub use openhuman_core::core::cli::{
parse_cli_args_after_launch_options, parse_function_params,
};
}
mod core_agent;
pub mod cron;
pub mod embeddings;
mod error;
pub mod fanout;
mod harness;
pub mod identity;
pub mod inbound;
pub mod memory;
pub mod modules;
mod permission;
pub use permission::PermissionFuture;
pub mod observe;
pub mod process;
#[cfg(feature = "profiles")]
pub mod profiles;
/// Explicit ordered fallback and truncation policies.
pub mod routing;
mod runtime;
pub mod secret_storage;
mod turn;
mod turn_cancellation;
mod turn_meter;
mod turn_steering;
/// Core internals for `openhuman-tinyhumans` and `openhuman-rpc` only; see
/// the module docs. Not part of the host-facing API.
#[doc(hidden)]
#[path = "host_internals.rs"]
pub mod __host;
/// Look up the schema of a registered RPC method (`openhuman.<ns>_<fn>`).
pub use openhuman_core::core::all::schema_for_rpc_method;
/// Whether this build carries the HTTP server surface the router mounts.
pub use openhuman_core::core::http_server_status::HTTP_SERVER_COMPILED_IN;
pub use openhuman_core::core::ControllerSchema;
/// Why a listen-port pick failed (another live core holds the port, ...).
pub use openhuman_core::platform::connectivity::rpc::PickListenPortError;
/// Whether this build carries the voice domain.
pub use openhuman_core::voice::VOICE_COMPILED_IN;
pub use agent::ToolAttachmentError;
pub use agent::{
Agent, AgentDefinitionSpec, AgentError, AgentLayout, AgentSpec, ApprovalDecision, Approvals,
ApprovalsError, CompactOptions, CompactOutcome, DefinitionBase, MemoryBinding, MemoryBlockSpec,
PendingApproval, SandboxModeSpec, ToolScopeSpec,
};
pub use auth::{Auth, AuthState, Session};
#[cfg(feature = "channels")]
pub use channels::{ChannelError, ChannelListener, Channels, StreamMode, TelegramChannelSpec};
pub use config::{Config, RuntimeFlags};
pub use core_agent::CoreAgent;
pub use cron::{
Cron, CronError, JobKind, JobKindHandler, JobOutcome, JobRun, JobRunContext, JobRunRecord,
JobSchedule, JobSpec, JobTarget, ScheduledJob, SystemJobContext,
};
pub use error::CoreError;
pub use harness::{
Access, Harness, HarnessBuilder, HarnessCore, HarnessError, Provider, Workspace,
};
#[cfg(feature = "mcp")]
pub use harness::{HttpHeader, McpAuthConfig, McpServer};
/// Host-routed delivery of scheduled replies, for [`RuntimeBuilder::cron_delivery`]
/// and the profile runtime alike.
pub use openhuman_core::cron::host_delivery::{CronDelivery, CronReply};
pub use openhuman_core::cron::JobOrigin;
#[cfg(feature = "profiles")]
pub use profiles::{
ChatReply, CronSweepReport, DirectProfileProvider, OpenError, ProfileError, ProfileEvents,
ProfileHandle, ProfileId, ProfileIdMode, ProfileRuntime, ProfileRuntimeBuilder, ProfileSummary,
Provisioned, SaasConfig,
};
#[cfg(all(feature = "profiles", feature = "channels"))]
pub use profiles::{RelayAccepted, RelayMessage};
pub use runtime::builder::DEFAULT_MAX_AGENTS;
/// Read-only view of a [`RuntimeBuilder`], for the layered crates' tests.
#[doc(hidden)]
pub use runtime::BuilderSummary;
pub use runtime::{
run_from_args, AgentDefaults, ApiKey, ConfigSource, ConfigurationInfo, DefaultsInfo,
LearningSettings, ModelDefaults, RemoveAgent, Runtime, RuntimeBuilder, RuntimeDefaults,
RuntimeError, RuntimeInfo, RuntimeModule, SkillsPolicy, StorageInfo, WeightClass,
};
/// The types the [`RuntimeBuilder`] seam options take: controller
/// extensions, embedder hooks, the CLI server launcher and the live security
/// policy. A `tool_search` ranker implements `tinytools::ToolRanker`; take
/// `tinytools` from the vendored path (`vendor/tinyagents/vendor/tinytools`)
/// so the trait unifies — re-exporting it here would break the
/// agent-runtime ownership boundary.
pub mod seams {
pub use openhuman_core::agent::tinyagents::host::OpenHumanRunContext;
pub use tinyagents_harness::cost::TurnCost;
pub use tinyagents_harness::host::{LearningSink, TurnSummary};
pub use tinyagents_harness::middleware::{PolicyDecision, ToolCallPolicy};
pub use tinyagents_hooks::stop::BudgetStopHook;
pub use tinyagents_hooks::stop::{StopDecision, StopHook};
pub use tinyagents_hooks::tool::{
HookIdentity, ToolHook, ToolHookContext, ToolHookDecision, ToolHookEvent,
};
/// Product cost snapshot passed to TinyAgents stop policies.
pub type TurnState<'a> = tinyagents_hooks::stop::TurnState<'a, TurnCost>;
pub use openhuman_core::core::all::{ControllerExtension, DomainGroup};
pub use openhuman_core::core::server_launcher::{HostBoot, ServeRequest, ServerLauncher};
pub use openhuman_core::security::SecurityPolicy;
pub use openhuman_core::storage::{CollectionSpec, Precondition, Scope, StorageBackend};
pub use crate::runtime::StorageSource;
}
/// The session store port: what a host implements to keep every agent's
/// conversations in its own database ([`RuntimeBuilder::session_store`]),
/// with the in-memory provider and the conformance suites a host's provider
/// is held to. The persisted record types are the harness's own serde codecs,
/// so hosts can encode and decode stored state without duplicating wire shapes.
pub mod session_store {
pub use tinyagents_harness::events::{AgentEvent, HarnessRunStatus};
pub use tinyagents_harness::ids::ExecutionStatus;
pub use tinyagents_harness::observability::AgentObservation;
pub use tinyagents_harness_tools::todos::TodoList;
pub use tinyagents_session::port::{AgentStores, SessionStoreProvider};
pub use tinyagents_session::port::{AppendStore, Store, TurnStates};
/// In-memory provider and contract suites for providers implemented by embedders.
#[cfg(feature = "testkit")]
pub use tinyagents_session::port::{
InMemorySessionStores, InMemoryTranscriptLocator, InMemoryTurnStates,
};
/// What a provider's `lease_for_agent` returns: stores the provider promises
/// stay bound to one backend for the life of the lease.
pub use tinyagents_session::port::{SessionStoreLease, SessionStoreLeaseError};
#[cfg(feature = "testkit")]
pub use tinyagents_session::testkit::conformance::{
session_store_conformance, session_store_isolation_conformance,
};
/// The transcript seam a provider's [`AgentStores::transcripts`] implements.
pub use tinyagents_session::transcript::{
SessionRef, SessionTranscript, TranscriptHistory, TranscriptLocator, TranscriptMessage,
TranscriptMeta, TranscriptPartial, TranscriptRead, TranscriptTurn,
};
/// The turn snapshots a provider's [`AgentStores::turn_states`] keeps.
pub use tinyagents_session::turn_state::{TurnLifecycle, TurnState};
/// The error and result the key-value and journal seams return.
pub use tinyagents_session::{Result as StoreResult, TinyAgentsError as StoreError};
}
pub use complete::{
ChatMessage, Completer, CompletionObserver, CompletionRequest, CompletionResponse,
CompletionTrace, CompletionUsage, PhysicalDispatchMetadata, PhysicalDispatchObserver,
PhysicalDispatchOutcome, PhysicalDispatchStatus, PhysicalDispatchTerminal,
PhysicalDispatchUsage,
};
#[cfg(feature = "testkit")]
pub use session_store::InMemorySessionStores;
pub use session_store::SessionStoreProvider;
pub use turn::{absolute, Route, Turn, TurnOutcome, TurnRequest};
pub use turn_cancellation::TurnCancellation;
pub use turn_steering::{SteerRefused, TurnSteering};
use std::sync::Arc;
/// Typed handle to an embedded OpenHuman core.
///
/// Cheap to clone: it is an `Arc` over the runtime the embedder already owns.
#[derive(Clone)]
pub struct Core {
rt: Arc<CoreRuntime>,
}
impl Core {
/// Wrap an already-built [`CoreRuntime`].
///
/// The runtime must come from
/// [`CoreBuilder::build`](openhuman_core::core::runtime::CoreBuilder::build). The
/// facade neither starts nor stops background services; lifecycle stays
/// with the embedder.
pub fn from_runtime(rt: Arc<CoreRuntime>) -> Self {
log::debug!("[embed] core_facade_attached services={:?}", rt.services());
Self { rt }
}
/// Typed configuration access.
pub fn config(&self) -> Config<'_> {
Config(&self.rt)
}
/// Typed access to the session store.
///
/// Use this when the embedded workload calls authenticated TinyHumans
/// backend services. A [`HostKind::Library`]
/// runtime does not need an app session for caller-supplied inference.
pub fn auth(&self) -> Auth<'_> {
Auth(&self.rt)
}
/// Typed access to the agent harness — run a turn on the runtime's
/// orchestrator, get a reply.
///
/// Requires the `inference` domain family at runtime; with it off the turn
/// returns [`CoreError::Unavailable`], because the routed chat entry point
/// is registered under that group. Note
/// [`DomainSet::harness`](openhuman_core::core::runtime::DomainSet::harness) leaves
/// `inference` **off** despite its name — use
/// [`DomainSet::embedded`](openhuman_core::core::runtime::DomainSet::embedded), or
/// set the field.
///
/// For agents of your own — several, each with its own MCP servers,
/// skills, working directory and access tier — see [`Runtime::agent`].
pub fn agent(&self) -> CoreAgent<'_> {
CoreAgent(&self.rt)
}
/// The underlying runtime, for anything this facade does not yet model.
///
/// An escape hatch, not the intended path — every use is a candidate for a
/// real typed method. Callers own the JSON and the error strings.
pub fn raw(&self) -> &Arc<CoreRuntime> {
&self.rt
}
}
impl std::fmt::Debug for Core {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
// CoreRuntime holds resolved workspace paths and host identity; keep
// them out of logs and panic messages.
f.debug_struct("Core").finish_non_exhaustive()
}
}
/// Strict structured output failure metadata.
pub mod structured;
/// Acknowledged cancellation for stateless completion operations.
pub mod cancellation;
/// Runtime event subscriptions without content or credentials.
pub mod events;
/// Owned streaming turns and cooperative cancellation.
pub mod stream;
pub use agent::{ApprovalHandler, ApprovalSubscription};
pub use events::{EventStreamError, RuntimeEvent, RuntimeEventKind, RuntimeEvents};
pub use stream::{CancellationToken, StreamEvent, TurnStream};
/// Native custom-provider contract and request/response types.
pub mod providers {
pub use tinyinference_llm::message::MessageDelta;
pub use tinyinference_llm::model::{
ChatModel, DeferredHandle, DeferredStatus, ModelProfile, ModelRequest, ModelResponse,
ModelStream, ModelStreamItem, ModelStreamMetadata,
};
pub use tinyinference_llm::{Error, Result};
}
pub use agent_progress::AgentProgress;