ultron-session-core 1.0.0

One session's runtime, shared by every mode through the session worker: the rlm lane (model, provider, system prompt, the single rlm tool), the composition root of its host stack, the format-4 run journal, session naming, Pi read views, and the session actor
Documentation
//! One session's runtime, shared by every mode. TypeScript runs every session in a session worker process and so
//! does the Rust build (crates/daemon `worker`); this crate is what that worker runs:
//!
//! - [`lane`]: the model, its key, the native worker's system prompt, the provider call, the clock lines and the
//!   single `rlm` tool (the model's tool list is exactly `[rlm]`);
//! - [`compose`]: the composition root of the host stack behind a lane's kernels;
//! - [`journal`]: the format-4 harness operation journal of a run; [`compaction_op`] that of a compaction;
//! - [`naming`]: automatic and model-made session names;
//! - [`pi_view`] / [`view`]: the session as Pi entries and Pi's read views (tree, messages, stats);
//! - [`core`]: the session actor that owns all of it and reports lane-watch events.

mod agent_hub;
mod agents;
pub mod async_events;
pub mod auto_compaction;
pub mod auto_memory;
pub mod auto_refine;
mod budget_note;
mod budget_pricing;
pub mod cell_file_changes;
pub mod commands;
pub mod compaction_op;
pub mod compose;
pub mod context_reminder;
pub mod continuation;
mod contract_checks;
pub mod core;
pub mod durable_store;
mod format_version;
pub mod frame_models;
pub mod frames;
pub mod guard_log;
pub mod inspect;
pub mod journal;
pub mod kept_contracts;
pub mod lane;
mod lane_reuse;
pub mod local_resources;
pub mod loki_notice;
pub mod memory_children;
pub mod memory_guidance;
pub mod migration;
pub mod model_refresh;
pub mod naming;
pub mod nudge;
mod pi_view;
mod playbook_route;
mod prompt_budget;
pub mod recovery;
pub mod request_keys;
pub mod request_layer;
pub mod request_settings;
pub mod request_trace;
pub mod review_command;
pub mod session_diagrams;
pub mod session_flags;
mod session_images;
mod session_judge;
mod session_knowledge;
mod session_modules;
pub mod session_resources;
pub mod session_stats;
mod session_tools;
pub mod situational_skills;
pub mod startup_trace;
pub mod stored_auth;
pub mod subagents;
pub mod swarm_ops;
pub mod turn_checkpoints;
pub mod turns;
pub mod view;
pub mod view_images;
pub mod wake;

use std::path::PathBuf;
use std::sync::Arc;

/// A session switch's "off": `off`, `0` or `false`, in any case and with surrounding space (the TypeScript
/// `["off", "0", "false"].includes(value.trim().toLowerCase())`).
pub fn flag_off(value: Option<&str>) -> bool {
    value.is_some_and(|v| matches!(v.trim().to_lowercase().as_str(), "off" | "0" | "false"))
}

pub type VarLookup = config::auth::Vars;

/// The process environment and locations a session sees.
#[derive(Clone)]
pub struct RunEnv {
    pub cwd: PathBuf,
    pub home: PathBuf,
    pub var: VarLookup,
    /// The package files (`cli::assets`): the embedded files installed under `<agent dir>/runtime/<version>-<hash>/`,
    /// or a live checkout in dev builds (`ULTRON_DEV_ASSETS`); the CLI makes them ready before a session reads them.
    pub package: PathBuf,
}

impl RunEnv {
    pub fn agent_dir(&self) -> PathBuf {
        config::paths::agent_dir(|k| (self.var)(k), &self.home)
    }

    /// A file of the package (`getPackageDir()`-relative).
    pub fn package_file(&self, relative: &str) -> PathBuf {
        config::paths::normalize(&self.package.join(relative))
    }

    /// `getDocsPath()`.
    pub fn docs(&self) -> PathBuf {
        self.package_file("docs")
    }

    pub fn skills(&self) -> PathBuf {
        self.package_file("skills")
    }

    pub fn runtime(&self) -> PathBuf {
        self.package_file(RUNTIME_PY)
    }

    pub fn flag_off(&self, name: &str) -> bool {
        flag_off((self.var)(name).as_deref())
    }

    pub fn process(cwd: PathBuf, package: PathBuf) -> RunEnv {
        RunEnv {
            cwd,
            home: std::env::var_os("HOME").map(PathBuf::from).unwrap_or_default(),
            var: Arc::new(|k| std::env::var(k).ok()),
            package,
        }
    }
}

/// The REPL's runtime script, relative to the package directory.
pub const RUNTIME_PY: &str = "src/ultron/rlm/runtime.py";

/// The model flags a session starts with (`--provider`, `--model`, `--api-key`, `--thinking`, `--models`).
#[derive(Clone, Debug, Default, PartialEq)]
pub struct ModelFlags {
    pub provider: Option<String>,
    pub model: Option<String>,
    pub api_key: Option<String>,
    pub thinking: Option<String>,
    /// `--models`: the scoped model patterns (None: the settings' `enabledModels`).
    pub models: Option<Vec<String>>,
}