Skip to content

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

22.9 KB
Raw Blame
//! Core initialization context.
//!
//! [`CoreContext`] owns the core's initialization *order* (Phase 2, Stage A):
//! register controllers, load the master key, seed the RPC bearer, initialize
//! the workspace-bound stores, and run pure `bootstrap_core_runtime` registration. Today it is a
//! facade — the store init still targets the process globals — but centralizing
//! the sequence here is the seam the later stages build on (handler-threaded
//! context, per-context stores). See the pluggable-core work (`core::runtime`)
//! for how this fits with [`builder`](crate::core::runtime::builder).
//!
//! [`init_stores`] initializes the process-global stores bound to a single
//! resolved workspace directory (memory, image attachments, WhatsApp data,
//! people) plus the boot-time Sentry user binding. It preserves the exact
//! behavior and ordering of the original inline `run_server_inner` block,
//! including the deliberate wrong-workspace guard (never seed against a
//! `Config::default` fallback — Sentry OPENHUMAN-CORE-48 / TAURI-RUST-8NM).

use std::future::Future;
use std::sync::{Arc, OnceLock, RwLock};

use crate::core::types::HostKind;

#[path = "context_accessors.rs"]
mod accessors;

/// The process-wide default context — the first one built. Callers that dispatch
/// RPC without an explicit per-call context (the desktop shell, the CLI, tests)
/// resolve to this. Multi-tenant hosts override it per dispatch via
/// [`CoreContext::scope`].
static DEFAULT_CONTEXT: OnceLock<Arc<CoreContext>> = OnceLock::new();

tokio::task_local! {
    /// The context active for the current dispatch, set by [`CoreContext::scope`]
    /// at the `try_invoke_registered_rpc` chokepoint. Absent outside a scope —
    /// [`CoreContext::current`] then falls back to [`DEFAULT_CONTEXT`].
    static CURRENT_CONTEXT: Arc<CoreContext>;
}

/// A built, initialized core context. Holds the identity of the host and the
/// resolved workspace directory; created by [`CoreContext::init`].
///
/// Handlers reach the context for the current dispatch through
/// [`CoreContext::current`] rather than a threaded parameter — the ambient
/// context is established once per RPC at the dispatch chokepoint. This keeps
/// controller handlers as bare `fn` pointers (no per-handler signature churn)
/// while giving every handler a path to per-context state.
///
/// Stage A/B: state that today still lives in process globals is reached through
/// the globals as before; a domain migrates by reading its store handle off the
/// context ([`CoreContext::current`]) instead of the global. Once a domain's
/// state lives on the context, two contexts dispatched under distinct
/// [`CoreContext::scope`]s read isolated state — the Phase 3 exit criterion.
pub struct CoreContext {
    host_kind: HostKind,
    /// The workspace this context is bound to. Shared (`Arc`) so a context
    /// derived over the same workspace follows the parent when the active
    /// user's workspace is rebound.
    workspace_binding: RwLock<Arc<RwLock<WorkspaceBinding>>>,
    /// Which domain families are live for this context (#4796). The registry
    /// filters its controller/schema/dispatch surface by this set via
    /// [`CoreContext::current`] → [`CoreContext::domains`]. `full()` for the
    /// desktop shell / standalone CLI (byte-identical to pre-#4796).
    domains: crate::core::runtime::DomainSet,
    /// The configuration an embedder supplied to
    /// [`CoreBuilder::config`](crate::core::runtime::CoreBuilder::config),
    /// if any.
    ///
    /// `None` for every host that lets the core discover its own config, which
    /// is all of them today except a library embedder — so the default path is
    /// untouched.
    ///
    /// This exists because setting the config at boot is **not** sufficient on
    /// its own: RPC handlers do not receive it, they call
    /// `config::ops::load_config_with_timeout()` per dispatch, which re-runs
    /// `Config::load_or_init()` and re-resolves the process-global workspace.
    /// An embedder that supplied a config would therefore watch its turns run
    /// against `~/.openhuman` anyway. Publishing it on the context — the seam
    /// phase 2 of the pluggable-core work (`core::runtime`) introduced for exactly this
    /// migration — lets that loader prefer it without any handler changing.
    embedder_config: Option<crate::config::Config>,
    latest_embedder_config: Option<Arc<std::sync::Mutex<crate::config::Config>>>,
    /// Per-tool-group disclosure for this context (see
    /// [`ToolGroups`](crate::tools::toolpacks::ToolGroups)).
    ///
    /// The third narrowing axis, independent of `domains` the same way
    /// `DomainSet` is independent of `ServiceSet`: `DomainSet` decides which
    /// families *exist*, `ToolGroups` decides how the ones that exist reach
    /// the model. Defaults to every group withheld, which is what the
    /// compiled-in pack table meant before the type existed.
    tool_groups: crate::tools::toolpacks::ToolGroups,
    /// Whether autonomy-tier checks reload config or retain this context's
    /// effective in-memory tier.
    autonomy_tier_source: super::AutonomyTierSource,
    /// A fixed maximum autonomy level inherited by derived contexts.
    autonomy_tier_ceiling: Option<crate::security::AutonomyLevel>,
    /// Which tiny dependencies the config switched off (`[components]`). Only
    /// narrows: `domains` and `tool_groups` are already clamped by it, and this
    /// is kept so dispatch can answer `COMPONENT_DISABLED:<name>` for a method
    /// that a disabled component removed.
    components: crate::core::runtime::ComponentSet,
    /// Whether skill discovery under this context scans the operator's
    /// user-scope roots (`~/.openhuman/skills`, `~/.agents/skills`).
    ///
    /// `true` for every booted context — the desktop, CLI and a plain library
    /// embedder all run as the operator. A per-agent context derived through
    /// [`CoreContext::derive_with`] can turn it off so an embedded agent sees
    /// only the skills its host installed for it, never the operator's.
    user_skill_roots: bool,
    /// Hook registrations bound to this context (see [`crate::core::slots`]).
    /// Empty unless the host supplied some through
    /// [`CoreBuilder::extensions`](crate::core::runtime::CoreBuilder::extensions);
    /// inherited by every context derived through [`CoreContext::derive_with`].
    extensions: crate::core::slots::Extensions,
    /// Explicit authority on this derived turn context.
    turn_origin: Option<crate::security::turn_origin::AgentTurnOrigin>,
    /// Durable relay conversation carried by the immutable turn context.
    channel_thread: Option<String>,
    /// The agent whose stores a host-installed session store
    /// ([`crate::storage::sessions`]) hands out to work under this
    /// context. `None` for booted contexts, which use the shared default.
    session_agent: Option<String>,
    /// The tenant (SaaS profile) this context serves. `None` for booted
    /// contexts and every single-user agent. See [`crate::core::runtime::tenant`].
    profile: Option<String>,
    /// Private admission generation shared only by contexts derived within
    /// this profile generation. Profile reopen creates a fresh context from
    /// the host root and therefore a fresh token.
    profile_admission: Arc<()>,
    /// What the agent this context was derived for owns.
    agent: agent_parts::AgentParts,
    /// A context that exists only to carry a turn origin where no core was
    /// booted ([`CoreContext::bare`]). Every reader other than the turn-origin
    /// ones treats it as if nothing were scoped: [`CoreContext::current`] and
    /// [`CoreContext::scoped`] skip it.
    bare: bool,
}

/// The workspace a context is bound to.
struct WorkspaceBinding {
    workspace_dir: Option<std::path::PathBuf>,
    config_path: Option<std::path::PathBuf>,
}

impl CoreContext {
    /// The host that constructed this context (Tauri shell / CLI / Docker).
    pub fn host_kind(&self) -> HostKind {
        self.host_kind
    }

    /// Which domain families are live for this context (#4796). The controller
    /// registry consults this (via [`CoreContext::current`]) to filter its
    /// schema/dispatch/tool surface. `full()` for desktop/CLI.
    /// The `[components]` switches this context booted with.
    pub fn components(&self) -> crate::core::runtime::ComponentSet {
        self.components
    }

    /// Per-group tool disclosure for this context.
    pub fn tool_groups(&self) -> crate::tools::toolpacks::ToolGroups {
        self.tool_groups.clone()
    }

    pub fn domains(&self) -> crate::core::runtime::DomainSet {
        self.domains
    }

    /// Whether skill discovery under this context scans the operator's
    /// user-scope roots. See [`ContextOverlay::user_skill_roots`].
    pub fn user_skill_roots(&self) -> bool {
        self.user_skill_roots
    }

    /// [`user_skill_roots`](Self::user_skill_roots) of the ambient context, or
    /// `true` when nothing is scoped and no default context exists — the
    /// pre-existing behaviour for every non-embedded caller.
    pub fn current_user_skill_roots() -> bool {
        Self::current().is_none_or(|ctx| ctx.user_skill_roots())
    }

    /// Derive a child with its own config and narrowed tool/runtime surfaces.
    /// The child shares host identity but does not boot stores or alter the
    /// process default; scoped readers observe its config and policy.
    pub fn derive_with(&self, overlay: ContextOverlay) -> Arc<CoreContext> {
        let parent_config = self.latest_embedder_config();
        self.derive_with_parent_config_inner(parent_config.as_ref(), overlay, false)
    }

    /// Derive a child using the exact parent configuration it was built from.
    ///
    /// This is used by embedders that load their config after core boot: the
    /// context may intentionally have no published embedder snapshot, while
    /// the child still needs the correct baseline for conflict-refresh
    /// overrides.
    pub fn derive_with_parent_config(
        &self,
        parent_config: &crate::config::Config,
        overlay: ContextOverlay,
    ) -> Arc<CoreContext> {
        self.derive_with_parent_config_inner(Some(parent_config), overlay, false)
    }

    /// Whether `other` descends from the same admitted profile context
    /// generation. This differs from context pointer identity: turn contexts
    /// may be derived while the profile remains admitted.
    pub(crate) fn shares_profile_admission(&self, other: &Self) -> bool {
        Arc::ptr_eq(&self.profile_admission, &other.profile_admission)
    }

    fn derive_with_parent_config_inner(
        &self,
        parent_config: Option<&crate::config::Config>,
        mut overlay: ContextOverlay,
        fresh_state: bool,
    ) -> Arc<CoreContext> {
        // Clamped to what this context can already dispatch. A derived
        // overlay may only narrow: callers outside this crate (embed's
        // `Runtime::agent`, for one) already refuse a spec that names a
        // family the runtime never registered, but that check lives at the
        // call site. Enforcing it here too means a future or third-party
        // caller of `derive_with` cannot widen a restricted parent's domains
        // just by omitting that check.
        let domains = self.domains.intersect(&overlay.domains);
        let components = if fresh_state {
            crate::core::runtime::ComponentSet::from_config(&overlay.config.components)
        } else {
            self.components
        };
        if domains != overlay.domains {
            log::warn!(
                "[core-context] derive: overlay requested domains={:?} wider than \
                 parent domains={:?}; clamped to {:?}",
                overlay.domains,
                self.domains,
                domains
            );
        }
        log::debug!(
            "[core-context] derive: workspace_dir={} domains={:?} tool_groups={:?} \
             user_skill_roots={}",
            overlay.config.workspace_dir.display(),
            domains,
            overlay.tool_groups,
            overlay.user_skill_roots
        );
        // A derived context over the parent's workspace and config root shares
        // its current binding snapshot. A later parent rebind replaces the
        // parent's handle, leaving already-derived work on the prior binding.
        // Another workspace or config root gets its own binding from the start.
        let shared_binding = {
            let parent_handle = self.workspace_binding.read();
            let parent_handle = parent_handle
                .as_ref()
                .ok()
                .map(|handle| Arc::clone(&**handle));
            let can_share = parent_handle.as_ref().is_some_and(|handle| {
                handle.read().ok().is_some_and(|parent| {
                    parent.workspace_dir.as_deref() == Some(overlay.config.workspace_dir.as_path())
                        && parent.config_path.as_deref()
                            == Some(overlay.config.config_path.as_path())
                })
            });
            match (can_share, parent_handle.as_ref()) {
                (true, Some(handle)) => Arc::clone(handle),
                _ => Arc::new(RwLock::new(WorkspaceBinding {
                    workspace_dir: Some(overlay.config.workspace_dir.clone()),
                    config_path: Some(overlay.config.config_path.clone()),
                })),
            }
        };
        let agent = self.agent.derive(&mut overlay, fresh_state);
        config_access::record_context_config_overlay(self.profile(), parent_config, &mut overlay);
        overlay.config.runtime_state.context_snapshot = None;
        let latest_embedder_config = Some(Arc::new(std::sync::Mutex::new(overlay.config.clone())));
        if let Some(snapshot) = &latest_embedder_config {
            crate::config::Config::bind_context_snapshot(snapshot);
        }
        let profile_admission = if overlay
            .profile
            .as_deref()
            .is_none_or(|profile| Some(profile) == self.profile())
        {
            Arc::clone(&self.profile_admission)
        } else {
            Arc::new(())
        };
        Arc::new(CoreContext {
            host_kind: self.host_kind,
            workspace_binding: RwLock::new(shared_binding),
            domains,
            tool_groups: overlay.tool_groups,
            components,
            autonomy_tier_source: overlay
                .autonomy_tier_source
                .unwrap_or(self.autonomy_tier_source),
            autonomy_tier_ceiling: overlay::stricter_autonomy_ceiling(
                self.autonomy_tier_ceiling,
                overlay.autonomy_tier_ceiling,
            ),
            embedder_config: Some(overlay.config),
            latest_embedder_config,
            user_skill_roots: overlay.user_skill_roots,
            extensions: self.extensions.clone(),
            turn_origin: self.turn_origin.clone(),
            channel_thread: self.channel_thread.clone(),
            session_agent: overlay.session_agent.or_else(|| self.session_agent.clone()),
            profile: overlay.profile.or_else(|| self.profile.clone()),
            profile_admission,
            agent,
            bare: self.bare,
        })
    }

    /// The agent a host session store scopes work under this context to, if
    /// this context was derived for one.
    pub fn session_agent(&self) -> Option<&str> {
        self.session_agent.as_deref()
    }

    /// The resolved per-user workspace directory this context is bound to.
    pub fn workspace_dir(&self) -> Result<std::path::PathBuf, String> {
        self.workspace_binding
            .read()
            .map_err(|e| format!("workspace unavailable: context lock poisoned: {e}"))?
            .read()
            .map_err(|e| format!("workspace unavailable: binding lock poisoned: {e}"))?
            .workspace_dir
            .clone()
            .ok_or_else(|| {
                "workspace unavailable: Config::load_or_init failed during core boot; \
                 fix config.toml or OPENHUMAN_WORKSPACE and restart"
                    .to_string()
            })
    }

    /// The workspace and config path hint from one binding snapshot. The hint
    /// is captured during normal boot even when no embedder config was supplied.
    pub(crate) fn workspace_config_binding(
        &self,
    ) -> Result<(std::path::PathBuf, Option<std::path::PathBuf>), String> {
        let handle = self
            .workspace_binding
            .read()
            .map_err(|e| format!("workspace unavailable: context lock poisoned: {e}"))?;
        let binding = handle
            .read()
            .map_err(|e| format!("workspace unavailable: binding lock poisoned: {e}"))?;
        let workspace = binding.workspace_dir.clone().ok_or_else(|| {
            "workspace unavailable: Config::load_or_init failed during core boot; \
             fix config.toml or OPENHUMAN_WORKSPACE and restart"
                .to_string()
        })?;
        Ok((workspace, binding.config_path.clone()))
    }

    /// The context for the current dispatch: the one scoped by
    /// [`CoreContext::scope`] if inside a scope, else the process
    /// [`DEFAULT_CONTEXT`]. Returns `None` only before any context is built
    /// (e.g. a unit test that dispatches without initializing the core).
    ///
    /// Handlers migrating off process globals read their state through this.
    /// The configuration this context was built with, when an embedder
    /// supplied one.
    ///
    /// `None` means "discover it the usual way" — see the field docs.
    pub fn embedder_config(&self) -> Option<&crate::config::Config> {
        self.embedder_config.as_ref()
    }

    /// Rebind the process default context to the current active user's
    /// workspace. Desktop login, logout, and pending-session revalidation can
    /// switch the active workspace after boot without rebuilding the core.
    /// Scoped multi-tenant dispatch is unaffected because tenant contexts are
    /// passed to [`CoreContext::scope`] explicitly and are not the process
    /// default.
    pub fn rebind_default_workspace(workspace_dir: &std::path::Path) -> Result<(), String> {
        Self::rebind_default_workspace_with_config(workspace_dir, None)
    }

    pub(crate) fn rebind_default_workspace_with_config(
        workspace_dir: &std::path::Path,
        config_path: Option<&std::path::Path>,
    ) -> Result<(), String> {
        let Some(ctx) = DEFAULT_CONTEXT.get() else {
            log::debug!(
                "[core-context] default context not initialized; skipped workspace rebind to {}",
                workspace_dir.display()
            );
            return Ok(());
        };
        ctx.rebind_workspace(workspace_dir, config_path)
    }

    pub(crate) fn rebind_workspace(
        &self,
        workspace_dir: &std::path::Path,
        config_path: Option<&std::path::Path>,
    ) -> Result<(), String> {
        let mut binding_handle = self
            .workspace_binding
            .write()
            .map_err(|e| format!("workspace rebind failed: binding handle lock poisoned: {e}"))?;
        let already = {
            let binding = binding_handle
                .read()
                .map_err(|e| format!("workspace rebind failed: binding lock poisoned: {e}"))?;
            binding.workspace_dir.as_deref() == Some(workspace_dir)
                && binding.config_path.as_deref() == config_path
        };
        if already {
            log::debug!(
                "[core-context] workspace {} already bound",
                workspace_dir.display()
            );
            return Ok(());
        }
        log::info!(
            "[core-context] rebound default workspace to {}",
            workspace_dir.display()
        );
        *binding_handle = Arc::new(RwLock::new(WorkspaceBinding {
            workspace_dir: Some(workspace_dir.to_path_buf()),
            config_path: config_path.map(std::path::Path::to_path_buf),
        }));
        Ok(())
    }

    /// Run `fut` with `ctx` as the ambient [`CoreContext::current`]: dispatch wraps
    /// each handler in this, and multi-tenant hosts pass the tenant's context.
    ///
    /// A turn's origin survives a change of context: `ctx` without an origin of
    /// its own, scoped inside a turn that has one (an embedded agent's derived
    /// context replacing the caller's, say), keeps that turn's origin. Dropping
    /// it would turn a labelled turn into an unlabelled one the approval gate
    /// refuses.
    pub async fn scope<F: Future>(ctx: Arc<CoreContext>, fut: F) -> F::Output {
        CURRENT_CONTEXT
            .scope(Self::keeping_turn_origin(ctx), fut)
            .await
    }

    /// [`scope`](Self::scope) for a synchronous closure.
    pub fn sync_scope<R>(ctx: Arc<CoreContext>, f: impl FnOnce() -> R) -> R {
        CURRENT_CONTEXT.sync_scope(Self::keeping_turn_origin(ctx), f)
    }

    /// `ctx`, carrying the origin of the turn it is being scoped inside when it
    /// has none of its own.
    fn keeping_turn_origin(ctx: Arc<CoreContext>) -> Arc<CoreContext> {
        if ctx.turn_origin.is_some() {
            return ctx;
        }
        match Self::scoped_for_turn().and_then(|outer| outer.turn_origin.clone()) {
            Some(origin) => ctx.derive_channel_turn(None, Some(origin)),
            None => ctx,
        }
    }

    /// Capture the current context now and carry it across a subsequently
    /// spawned task. Calling this before `tokio::spawn` is essential: reading
    /// `current()` inside the child would already have fallen back to the
    /// process default.
    ///
    /// In SaaS only the caller's own task scope is carried (never the
    /// operator's default context), together with its memory identity — the
    /// same rule as [`DispatchCtx::spawn`](crate::core::runtime::DispatchCtx::spawn).
    pub fn propagate<F: Future>(fut: F) -> impl Future<Output = F::Output> {
        super::spawn::carry(fut)
    }
}

/// Initialize the workspace-bound stores and report the memory engine.
///
/// A `Config::load_or_init` failure here is operator-visible and serious
/// (corrupt toml, bad permissions, missing/unwritable `OPENHUMAN_WORKSPACE` —
/// common on headless/containerised deploys with no writable `$HOME`).
/// Instead of falling back to `Config::default()` against the *wrong*
/// workspace (Sentry OPENHUMAN-CORE-48), the workspace-bound init is skipped
/// entirely; the server still comes up and the operator sees the loud error.
/// Per-`DomainGroup` gating decision for each workspace-bound store that
#[path = "context_store_init.rs"]
mod store_init;
pub use store_init::{init_stores, StoreInitPlan};

#[path = "context_boot.rs"]
mod boot;

#[path = "context_turn_origin.rs"]
mod turn_origin_scope;

#[path = "context_for_agent.rs"]
mod for_agent_scope;

#[path = "context_agent.rs"]
mod agent_parts;

#[path = "context_inspection.rs"]
mod inspection;

#[path = "context_overlay.rs"]
mod overlay;
pub use overlay::{AutonomyTierSource, ContextOverlay};

#[path = "context_config.rs"]
mod config_access;

#[cfg(test)]
#[path = "context_test_support.rs"]
mod test_support;

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