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
//! Long-lived runtime infrastructure brought up once per core boot.
//!
//! [`bootstrap_core_runtime`] runs from
//! [`CoreContext::init`](super::context::CoreContext::init) whether or not the
//! runtime ever binds a listener; [`start_core_runtime_services`] runs from
//! [`CoreRuntime::start_services`](super::CoreRuntime::start_services)
//! once a transport has bound, or directly when there is none.
use crate::core::runtime::DispatchCtx;
/// Initializes long-lived socket/event-bus infrastructure.
///
/// `host_kind` identifies the embedding process (Tauri desktop shell vs
/// standalone CLI / Docker). It drives the approval-gate's host-aware
/// decision tree: under the Tauri shell, the `OPENHUMAN_APPROVAL_GATE=0`
/// env override is ignored and a domain event is published so the UI can
/// surface a banner; under CLI / Docker the override is honored (with a
/// noisy log + a domain event so any connected dashboard can flag it).
pub(crate) async fn bootstrap_core_runtime(
host_kind: crate::core::types::HostKind,
config: Option<crate::config::Config>,
domains: crate::core::runtime::DomainSet,
ctx: &DispatchCtx,
) {
use crate::platform::socket::{set_global_socket_manager, SocketManager};
use std::sync::Arc;
// `embedded_core` derived from host_kind so the rest of the function (which
// already keys behavior off the boolean) stays unchanged.
let embedded_core = host_kind.is_desktop_shell();
let Some(mut cfg) = config else {
log::error!(
"[runtime] Config unavailable for runtime bootstrap; workspace-bound startup skipped"
);
return;
};
let workspace_dir = cfg.workspace_dir.clone();
// The workflow metadata loader is synchronous. Start module-owned resource
// acquisition before any subscriber or session snapshots it, but keep the
// optional download outside the critical bootstrap path.
#[cfg(all(feature = "flows", feature = "skills"))]
crate::skills::schedule_flow_authoring_prewarm(ctx, &cfg, Some(domains));
// --- Legacy store import ---------------------------------------------
// With a storage backend installed, bring the workspace's per-domain
// SQLite files (approvals, devices, notifications, task sources) into it
// once, read-only, before anything below opens those stores. A no-op
// without a backend; failures are logged and retried at the next boot.
for report in crate::storage::import::run(ctx, &cfg).await {
if let Err(error) = report.outcome {
log::warn!(
"[runtime] legacy {} store import failed: {error:#}",
report.domain
);
}
}
// --- Event bus bootstrap ---
// Ensure the global event bus is initialized (no-op if already done by start_channels).
crate::core::bus::init().await.expect("bus init");
let agent_enabled = domains.allows(crate::core::all::DomainGroup::Agent);
if agent_enabled {
// Host decision: `OPENHUMAN_FILE_STATE_GUARD=0|false|off|no` turns the
// cross-agent file-staleness guard off.
let guard_disabled = std::env::var("OPENHUMAN_FILE_STATE_GUARD")
.map(|v| matches!(v.as_str(), "0" | "false" | "off" | "no"))
.unwrap_or(false);
if guard_disabled {
log::debug!("[file_state] guard disabled via OPENHUMAN_FILE_STATE_GUARD");
}
tinyagents_harness_tools::fs::file_state::init_global(!guard_disabled);
} else {
log::debug!("[boot] agent file-state coordinator SKIPPED — Agent domain disabled");
}
// Register domain subscribers for cross-module event handling. Ungated infra
// runs once (INFRA: Once) and each DomainGroup installs at most once via the
// per-group `group_first_time` set, so repeated calls to
// bootstrap_core_runtime() cannot double-subscribe (and a later, wider
// DomainSet still installs its newly-enabled groups).
super::subscribers::register_domain_subscribers(
workspace_dir.clone(),
cfg.clone(),
embedded_core,
domains,
ctx,
);
// Latch the config-corruption recovery signal (#5167) so `app_state_snapshot`
// keeps reporting it after the loader heals the file on this same boot; the
// frontend raises a one-shot "settings were reset" notice off it.
crate::desktop::app_state::latch_from_config(&cfg);
// --- Configurable hooks -------------------------------------------
// Read every `hooks.json` layer and, only if something is configured,
// install the harness bridge. Boot is the right moment: a hook that is
// meant to gate the first tool call of the first turn has to be loaded
// before any session exists, and the alternative — loading lazily on the
// first event — would let that first call through while the file is read.
crate::hooks::init(ctx, &cfg).await;
// --- Turn-state recovery -------------------------------------------
// Any per-thread turn snapshots left on disk from a previous process
// are stale by definition — there is no live driver to resume them.
// Stamp them as `Interrupted` so the UI can offer a retry without
// confusing a stale `Streaming` lifecycle for an in-flight turn.
//
// An installed host session store repairs itself, once; with none, the
// workspace default store is swept.
let host_store = crate::storage::sessions::installed_in(ctx);
if let Some(provider) = &host_store {
match provider.recover() {
Ok(()) => log::info!("[runtime] host session store recovered"),
Err(err) => log::warn!("[runtime] host session store recovery failed: {err:#}"),
}
}
if host_store.is_none() {
let now = chrono::Utc::now().to_rfc3339();
match crate::storage::sessions::default_turn_states_for(&workspace_dir)
.mark_all_interrupted(&now)
{
Ok(0) => {}
Ok(count) => {
log::info!("[runtime] marked {count} stale turn snapshot(s) as interrupted")
}
Err(err) => {
log::warn!("[runtime] failed to mark stale turn snapshots interrupted: {err}")
}
}
}
// --- Run-ledger recovery -------------------------------------------
// Detached sub-agent runs (`spawn_subagent`) from a previous process
// are gone with that process. Any `agent_runs` row still marked `running`
// at boot is orphaned — its driver died without firing a terminal event, so
// the finalizer never settled it. Stamp such rows `interrupted` so they stop
// rendering as perpetual "running" timeline entries on thread reopen.
if agent_enabled {
if !crate::storage::installed_is_shared() {
match crate::storage::sessions::with_ledger(&cfg.workspace_dir, |ledger| async move {
ledger.interrupt_orphaned_agent_runs().await
}) {
Ok(0) => {}
Ok(count) => {
log::info!("[runtime] settled {count} orphaned agent run(s) on startup")
}
Err(err) => log::warn!("[runtime] failed to settle orphaned agent runs: {err}"),
}
}
// --- Detached sub-agent TaskStore reconciliation -------------------
// The durable orchestration TaskStore can hold non-terminal sub-agent
// records left by a previous process — their detached executor (abort handle +
// cooperative CancellationToken) died with that process, so they cannot be
// re-attached. Reconcile each orphan to a terminal state and emit the typed
// terminal lifecycle event so the run ledger finalizes. Best-effort and
// non-fatal (issue #4249 / 07.2 steps 2 & 4).
let reconciled =
crate::agent::orchestration::running_subagents::reconcile_orphaned_tasks_on_boot(
&workspace_dir,
);
if reconciled > 0 {
log::info!(
"[runtime] reconciled {reconciled} orphaned detached sub-agent task(s) on startup"
);
}
// --- Undelivered background completions ----------------------------
// A detached sub-agent that finished in a previous process but whose
// result never reached its chat thread is still pending in the durable
// completion store.
// Schedule its delivery turn through the normal idle-gated path.
let redelivering =
crate::agent::orchestration::background_delivery::recover_on_boot(ctx, &workspace_dir);
if redelivering > 0 {
log::info!(
"[runtime] scheduled redelivery of undelivered background completions for \
{redelivering} thread(s) on startup"
);
}
} else {
log::debug!(
"[boot] agent run-ledger + orchestration task reconciliation SKIPPED — Agent domain disabled"
);
}
// --- Cost dashboard tracker ---
// Activates the previously-dormant CostTracker so the dashboard RPC
// surface (`openhuman.cost_get_dashboard`) and `record_provider_usage`
// share one JSONL-backed store. Idempotent.
crate::platform::cost::init_global(cfg.cost.clone(), &workspace_dir);
// --- Sub-agent definition registry bootstrap ---
// Loads built-in archetype definitions plus any custom TOML files
// under `<workspace>/agents/*.toml`. Idempotent — safe to call
// multiple times. Uses the per-user scoped workspace_dir.
if agent_enabled {
if let Err(err) =
crate::agent_registry::host_definition::AgentDefinitionRegistry::init_global(
&workspace_dir,
)
{
log::warn!(
"[runtime] AgentDefinitionRegistry::init_global failed: {err} — \
spawn_subagent will be unavailable until restart"
);
}
} else {
log::debug!("[boot] agent definition registry SKIPPED — Agent domain disabled");
}
// --- Agent sandbox + projects dirs ---
// Create the action sandbox + default projects home and register the
// projects dir as a ReadWrite trusted root BEFORE building the live policy
// below (so the trusted root is reflected in `from_config`). This is the
// always-run boot for web-chat-only desktop cores; without it a fresh
// install with no messaging integrations leaves `~/OpenHuman/projects`
// uncreated and every shell-tool `current_dir` fails with ERROR_DIRECTORY
// (os error 267) on Windows / ENOENT on Unix (#3353, RC-A). Idempotent — a
// later `start_channels` calls the same helper.
crate::config::ensure_agent_dirs(&mut cfg).await;
// --- Live SecurityPolicy ---
// Install the process-global live policy on the always-run serve boot, not
// only inside `start_channels` (which is skipped for web-chat-only cores
// with no messaging integrations). Without this, `live_policy::current()`
// would be empty on those cores, so the ApprovalGate's `auto_approve`
// allowlist and `config.update_autonomy_settings` reloads (`reload_from`)
// would be inert until a session with integrations starts. `from_config`
// injects the default projects root, so this matches what `start_channels`
// installs; idempotent — a later `start_channels` re-installs an equivalent
// policy.
let action_dir = cfg.action_dir.clone();
crate::security::live_policy::install(
std::sync::Arc::new(
crate::security::SecurityPolicy::from_config(
&cfg.autonomy,
&workspace_dir,
&action_dir,
)
.with_privacy_mode(cfg.privacy.mode),
),
workspace_dir.clone(),
action_dir,
);
// --- Triggered-workflow subscriber ---
// Install on the always-run serve boot, not only inside `start_channels`
// (skipped for web-chat-only cores with no messaging integrations, and when
// `OPENHUMAN_DISABLE_CHANNEL_LISTENERS=1`). Without this, any workflow
// declaring `triggers:` was silently ignored on web-chat-only desktop
// installs. Idempotent — shares a process-global OnceLock with the
// `start_channels` site so it registers exactly once regardless of which
// path runs first. (Matching only for now; activation handoff still pending.)
// Gated on the Skills domain (#4808 review): under `harness()`/`none()` the
// skills controllers are absent, so their trigger subscriber must not install.
if domains.allows(crate::core::all::DomainGroup::Skills) {
crate::skills::bus::ensure_triggered_workflow_subscriber_for(ctx, &cfg, Some(domains));
} else {
log::debug!("[boot] triggered-workflow subscriber SKIPPED — Skills domain disabled");
}
// --- Approval gate (#1339) ---
// ON by default; opt out with `OPENHUMAN_APPROVAL_GATE=0` (or `false`).
// Prompt-class `external_effect()` tool calls route through
// `ApprovalGate::intercept` and park until the UI dispatches
// `approval_decide` (or the 10-minute TTL elapses → deny). Safe to default
// on now that the release surface exists (ApprovalRequestCard + the Agent
// OS access panel) AND only *interactive chat* turns park — background /
// triage / cron turns carry no chat context and pass straight through, so
// autonomous automation is never blocked.
//
// Host-aware override evaluation: under the Tauri desktop shell the env
// override is treated as advisory only — the gate ALWAYS installs and a
// `DomainEvent::ApprovalGateOverrideIgnored` is published so the UI can
// surface a one-shot banner explaining the override was rejected. Under
// standalone CLI / Docker (env-as-config is the operator's chosen
// surface) the override is honored, but a `DomainEvent::ApprovalGateDisabled`
// is still published so any connected dashboard / log shipper can
// surface the elevated-privilege state.
let env_override_requested = std::env::var("OPENHUMAN_APPROVAL_GATE")
.map(|v| {
let t = v.trim();
t == "0" || t.eq_ignore_ascii_case("false")
})
.unwrap_or(false);
let decision =
crate::core::types::approval_gate_boot_decision(host_kind, env_override_requested);
// Record the boot decision before publishing the warning event so the
// first poll of `approval_get_gate_state` after boot reflects the same
// host-aware verdict the event itself describes — no race.
crate::security::approval::gate::record_boot_state(
crate::security::approval::gate::ApprovalGateBootState {
installed: decision.install_gate,
disabled_by_env: decision.gate_disabled_by_override,
override_ignored: decision.override_ignored,
host: match host_kind {
crate::core::types::HostKind::TauriShell => "tauri-shell",
crate::core::types::HostKind::Cli => "cli",
crate::core::types::HostKind::Docker => "docker",
crate::core::types::HostKind::Library => "library",
crate::core::types::HostKind::Saas => "saas",
},
},
);
if decision.override_ignored {
log::warn!(
"[runtime] OPENHUMAN_APPROVAL_GATE=0 IGNORED under desktop shell — \
gate is always on for the Tauri host (host={})",
host_kind.tag()
);
crate::core::bus::BUS.publish(
crate::core::events::DomainEvent::ApprovalGateOverrideIgnored {
host: host_kind.tag().to_string(),
},
);
}
// Bridge interactive web-surface events to the frontend: ApprovalRequested →
// `approval_request` AND PlanReviewRequested → `plan_review_request` (both
// handled by the same subscriber). Registered UNCONDITIONALLY here on the
// always-run serve boot — the plan-review gate is independent of the approval
// gate and parks turns even when `OPENHUMAN_APPROVAL_GATE=0`, while
// `start_channels` is skipped for web-chat-only cores. Without this an
// unguarded standalone/CLI/Docker core would park a plan review that never
// reaches the UI and dies at the gate TTL. Idempotent (Once-guarded).
crate::web_chat::register_approval_surface_subscriber();
// Egress-surface bridge (privacy epic S2, #4436) — registered
// unconditionally alongside the approval surface so external-transfer
// disclosures reach the UI even on cores that skip `start_channels` or run
// with the approval gate disabled. Idempotent (OnceLock-guarded).
crate::web_chat::register_egress_surface_subscriber();
// Agent-surface bridge (goals/todos/queue, C3) — registered unconditionally
// for the same reason as the two bridges above: this JSON-RPC serve boot
// path can run without `start_channels`. Idempotent (OnceLock-guarded).
crate::web_chat::register_agent_surface_subscriber();
if decision.install_gate {
// Per-launch correlation token for the approval gate. This is
// a fresh UUID every boot — it is NOT derived from the
// JSON-RPC bearer (`OPENHUMAN_CORE_TOKEN` / the in-memory
// auth subsystem) and carries no credential material, so it
// is safe to log, persist, and surface in audit events.
// `approval_list_pending` is session-agnostic so pending rows
// from prior launches remain visible after restart; only the
// per-session audit grouping changes across launches.
let session_id = format!("session-{}", uuid::Uuid::new_v4());
let _ =
crate::security::approval::ApprovalGate::init_global(cfg.clone(), session_id.clone());
log::info!(
"[runtime] approval gate installed (on by default; set OPENHUMAN_APPROVAL_GATE=0 to disable, session_id={session_id}) — \
Prompt-class external-effect tool calls park for approval in interactive chat turns"
);
// (The approval/plan-review surface bridge is registered unconditionally
// above — it must run even when this gate-install branch is skipped.)
crate::web_chat::register_artifact_surface_subscriber();
crate::threads::artifact_rows::register_artifact_row_subscriber();
} else {
log::info!(
"[runtime] approval gate DISABLED (OPENHUMAN_APPROVAL_GATE=0 honored on host={}) — \
Prompt-class external-effect tool calls run unprompted",
host_kind.tag()
);
crate::core::bus::BUS.publish(crate::core::events::DomainEvent::ApprovalGateDisabled {
host: host_kind.tag().to_string(),
reason: "env-override".to_string(),
});
}
// Artifact surface bridges DomainEvent::ArtifactReady/Failed onto the web
// channel ("Files in this chat" panel + ArtifactCard updates). This is
// independent of the approval-gate config — keep it outside the
// `if approval_gate` block so artifact events still publish when the user
// sets OPENHUMAN_APPROVAL_GATE=0 (CR #3328947323 on PR #3026). Idempotent
// (OnceLock-guarded inside register_artifact_surface_subscriber).
crate::web_chat::register_artifact_surface_subscriber();
crate::threads::artifact_rows::register_artifact_row_subscriber();
// Memory-activity surface bridges DomainEvent::MemoryStored/Recalled onto
// the web channel's `memory_activity` event (C5) — same unconditional
// placement rationale as the bridges above. Idempotent (OnceLock-guarded).
crate::web_chat::register_memory_activity_surface_subscriber();
// --- Socket manager bootstrap ---
let socket_mgr = Arc::new(SocketManager::new());
set_global_socket_manager(socket_mgr.clone());
log::info!("[socket] SocketManager initialized and registered globally");
}
/// Starts selected background jobs after the runtime has entered `serve()`.
///
/// This deliberately sits outside [`bootstrap_core_runtime`]: embedders may call
/// `CoreBuilder::build()` only to use in-process RPC, and a failed listener bind
/// must not leave pollers, one-shot jobs, MCP processes, or socket reconnect work
/// running without a live runtime.
pub(crate) async fn start_core_runtime_services(
services: crate::core::runtime::ServiceSet,
config: Option<&crate::config::Config>,
) {
let Some(cfg) = config else {
log::error!(
"[runtime] Config unavailable for runtime service startup; selected services skipped"
);
return;
};
// Long-lived bootstrap loops selected by ServiceSet.
crate::core::runtime::services::start_boot_once_jobs(services, cfg).await;
// Long-lived bootstrap loops selected by ServiceSet. These start only
// after the boot-once jobs above have completed.
crate::core::runtime::services::start_bootstrap_jobs(services, cfg);
match crate::platform::socket::global_socket_manager() {
Some(socket_mgr) => {
crate::core::runtime::services::spawn_socket_auto_connect(services, socket_mgr.clone());
}
None => {
log::warn!(
"[socket] SocketManager unavailable during runtime service startup; auto-connect skipped"
);
}
}
}