Skip to content

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

16.2 KB
Raw Blame
//! 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;