Skip to main content

session_core/
compose.rs

1//! The composition root of a session's host stack. A cell's host request passes, outermost first:
2//!
3//! 1. [`kernel_apis::KernelApis`]: the kernel-API modules (`skills.*` with code skills, `memory.*`,
4//!    `hints.*`, `images.*`, `diagram.*`, and the local services of [`services`]: `refinements.*`, `experiments.*`, `gates.*`),
5//!    matched by prefix;
6//! 2. [`inference::Inference`]: `rlm.infer`, `rlm.load`, `rlm.frames`;
7//! 3. [`Router`]: subagents (`rlm.spawn`, `rlm.collect`, ... served by [`delegation::host::Delegation`] for the
8//!    calling lane, in host collect mode: a cell never waits); the lane API (`rlm.lanes`, `rlm.lane.*`, `rlm.cells`, `rlm.cell.cancel`, `rlm.recovery`) is answered by the
9//!    session's REPL lanes ([`lanes::Lanes`]) first;
10//! 4. [`host::Host`], sandboxed ([`host::Host::sandboxed`] with the `sandbox.*` settings) over the
11//!    session's file hooks (Loki): shell, jobs and the before-write check.
12//!
13//! Each lane's kernel runs inside the session's shell sandbox (`KernelOptions::sandbox`), with `ULTRON_FILE_HOOKS=1`
14//! (its writes ask the host first), a per-session spill dir, a signed snapshot under the profile's `rlm-snapshots/<session>/` with the profile
15//! snapshot key, and the continuity policy (checkpoint after each cell, restore on restart). Subagent and detached
16//! cell completions continue the run between turns ([`RuntimeEvents`]). The model sees one tool, `rlm`.
17
18use crate::RunEnv as Env;
19use crate::async_events::RuntimeEvent;
20use crate::lane::{Provider, Rlm, rlm_over};
21use crate::session_stats::{GuardOutcome, SessionStats};
22use agent::{AgentOptions, AgentTool, StreamFn};
23use ai::{Message, Model, UserMessage, UserMessageContent};
24use delegation::agents::{Agents, AgentsOptions, Completion, PredictCall, predict_adapter};
25use delegation::child::agent_runner;
26use delegation::host::{ChildRun, ChildRunner, Delegation, DelegationOptions, DetachedEnd};
27use delegation::usage::UsageLedger;
28use host::Host;
29use host::file_hooks::{FileHooks, GuardRecord, OnRecord};
30use host::loki_guard::{LokiGuard, LokiMode, git_root, loki_mode};
31use inference::Inference;
32use jsrt::sync;
33use kernel::store::{FileDocumentStore, MemoryDocumentStore};
34use kernel::{ContinuityPolicy, HostHandler, Kernel, KernelOptions, Signal};
35use kernel_apis::{
36    CodeSkills, CodeSkillsOptions, DurableWork, DurableWorkOptions, GoalDriver, HintsModule, KernelApis, MemoryApi,
37    MemoryBackend, MemoryService, SchedulesModule, SkillSource, SkillsModule, TaskGoalJobs,
38};
39use lanes::Park;
40use lanes::{CellEnd, Lanes, LanesOptions};
41use serde_json::{Map, Value, json};
42use std::collections::HashMap;
43use std::path::{Path, PathBuf};
44use std::sync::mpsc::Receiver;
45use std::sync::{Arc, Condvar, Mutex, Weak};
46use std::time::Duration;
47
48pub const CONTEXT_REMINDER_ENV: &str = "ULTRON_CONTEXT_REMINDER";
49pub const CONTEXT_REMINDER_TOKENS_ENV: &str = "ULTRON_CONTEXT_REMINDER_TOKENS";
50pub const GUIDE_ENV: &str = "ULTRON_GUIDE";
51pub const LOKI_ENV: &str = "ULTRON_LOKI";
52pub const LOKI_TIMEOUT_MS_ENV: &str = "ULTRON_LOKI_TIMEOUT_MS";
53pub const MASK_SECRETS_ENV: &str = "ULTRON_MASK_SECRETS";
54pub const READ_HANDLE_BYTES_ENV: &str = "ULTRON_READ_HANDLE_BYTES";
55
56/// What a cell's `ext.call` / `ext.list` (runtime.py's Pi extension functions) is answered.
57pub const EXTENSIONS_UNSUPPORTED: &str = "Pi extensions are not supported by ultron-rs";
58
59/// Told the session's MCP gateway when its stack opens.
60pub type McpListener = Arc<dyn Fn(&Arc<mcp::gateway::Gateway>) + Send + Sync>;
61
62/// Collaborators a caller may supply in place of the defaults (tests, embedders).
63#[derive(Clone, Default)]
64pub struct Services {
65    /// The memory backend behind `memory.*`; none: the memorantado server this process chose
66    /// ([`memorantado::Endpoint::choose`]), else the Hindsight server and bank it resolves ([`hindsight::Endpoint`]),
67    /// or memory off ("Hindsight is not configured") when that resolves to off.
68    pub memory: Option<Arc<dyn MemoryBackend>>,
69    /// Told the session's MCP gateway once its stack opens (the session worker serves `/mcp` with it).
70    pub on_mcp: Option<McpListener>,
71    /// Where the gateway's notices go when the session starts (configuration errors, an eager server that needs
72    /// sign-in): the attached client's UI (`ctx.ui.notify`). None: nowhere, as without a UI in TypeScript.
73    pub mcp_notices: Option<mcp::gateway::NoticeSink>,
74    /// `--system-prompt`, `--no-skills`, `--no-context-files` (crate::session_flags).
75    pub session: crate::session_flags::SessionFlags,
76    /// The local skills and prompts (crate::session_resources), resolved by [`Runtime::new`].
77    pub resources: Arc<crate::session_resources::SessionResources>,
78    /// The session whose values the module stores are (`ultron.module/<name>`, `ultron.local/<key>`, the memory
79    /// journal), set by the session actor: resuming restores them and a tree fork copies them (A07). None: files
80    /// under `rlm-modules/<session id>/` (no session).
81    pub values: Option<services::SessionValues>,
82    /// Told the session's active schedules (`schedule.*`, kernel_apis::prompt_schedule) after every change: the
83    /// session worker reports them to its server, which fires them.
84    pub on_schedules: Option<kernel_apis::prompt_schedule::Listener>,
85    /// Runs typed agents' `rlm` lanes for a stack without a [`SubagentHost`] (its typed agents' records stay in
86    /// memory); none: such a stack has no `rlm` strategy. A host's own [`AgentStores::lanes`] wins.
87    pub agent_lanes: Option<AgentLanes>,
88}
89
90/// Builds a typed-agent lane runner from the stack being built (it may hold the stack weakly).
91pub type AgentLanes = Arc<dyn Fn(Weak<Stack>) -> delegation::agents::LaneRunner + Send + Sync>;
92
93/// What every lane of this process shares: settings, locations, guards and the snapshot key. Owned
94/// values only, so subagent lanes can be built on their own threads.
95pub struct Config {
96    pub cwd: PathBuf,
97    pub home: PathBuf,
98    pub agent_dir: PathBuf,
99    /// The merged settings (`sandbox.*`, `loki`, ...).
100    pub settings: Value,
101    pub loki: LokiMode,
102    /// Which hygiene advisories Loki adds after a write (`ULTRON_LOKI_HYGIENE`, else `loki.hygiene`, else on).
103    pub loki_hygiene: loki::hygiene::Level,
104    /// Where Loki's policy is read: the Git work tree containing the cwd, else the cwd (None when Loki is off).
105    pub loki_root: Option<PathBuf>,
106    pub runtime_path: PathBuf,
107    pub skills_dir: PathBuf,
108    pub mask_secrets: Option<String>,
109    pub output_bytes: Option<String>,
110    /// `ULTRON_CELL_YIELD_AFTER`: how long a woken root's cell may hold its tool call before it continues in the
111    /// background (crate::lane `cell_yield_after`).
112    pub cell_yield_after: Option<String>,
113    pub snapshot_key: Option<Vec<u8>>,
114    pub spawn_depth: u32,
115    /// `ULTRON_ASYNC_EVENTS` is not off: completions of detached work continue the run.
116    pub async_events: bool,
117    /// `ULTRON_GUIDE=ts` ([`ts_guide`]).
118    pub ts_guide: bool,
119    /// `ULTRON_HINTS=on` ([`hints`]).
120    pub hints: bool,
121    /// Not `ULTRON_TURN_GUARDS=off`, outside the TypeScript guide ([`turn_guards`]).
122    pub turn_guards: bool,
123    /// The global `rlm.resultFooter` setting, outside the TypeScript guide: REPL results end with
124    /// [`crate::lane::result_footer`]s, and the runtime guide says so.
125    pub result_footer: bool,
126    /// Rounds without a user message before the root is nudged (`ULTRON_TOOL_ROUNDS_NUDGE`).
127    pub tool_rounds_nudge: u64,
128    /// Turns before a skill-extraction nudge (`ULTRON_SKILL_NUDGE`).
129    pub skill_nudge: u64,
130    /// Tool-result images a request keeps (`ULTRON_CONTEXT_IMAGES`; 0: all).
131    pub context_images: usize,
132    /// The frame settings `rlm.map` / `rlm.infer` read from the environment (`ULTRON_RLM_FRAME_MODEL`,
133    /// `ULTRON_REVIEW_MODEL`, `ULTRON_RLM_MAP_TOKENS`).
134    pub frame_env: HashMap<String, String>,
135    /// The process environment, for models.json keys and headers (`$VAR` values).
136    pub var: crate::VarLookup,
137    /// Cell output masking for every lane: the values MCP servers resolve (env, headers) are registered here, as
138    /// TypeScript's process-wide `registerSecretValues`.
139    pub masker: Arc<host::secrets::OutputMasker>,
140    /// Whether the project's own configuration (`.pi/mcp.json`) may be read.
141    pub project_trusted: bool,
142    /// The current key of a `/login` provider, for MCP servers with `auth.provider`.
143    pub provider_token: mcp::connection::ProviderToken,
144    /// Files Loki's own setup commit changed (crate::loki_notice): not the changes of the cell it ran beside.
145    pub outside_changes: host::file_hooks::OutsideChanges,
146    /// The session's language servers, shared by every lane; None when they are off (`lsp::enabled`).
147    pub lsp: Option<lsp::LspGuard>,
148    /// The terminal appearance the attached TUI reported ([`crate::core::Op::SetTerminalTheme`]): `diagram.mermaid`'s
149    /// `auto` theme follows it before the session's `COLORFGBG`.
150    pub terminal_theme: Arc<std::sync::Mutex<Option<String>>>,
151}
152
153/// After-cell checks picture the directory between cells (workspace-snapshot.ts).
154pub fn workspace_snapshotter() -> host::file_hooks::Snapshotter {
155    std::sync::Arc::new(|dir: &Path| {
156        let picture = delegation::workspace::snapshot_workspace(dir);
157        Ok(host::file_hooks::Snapshot {
158            root: picture.root,
159            entries: picture.entries,
160            complete: picture.complete,
161        })
162    })
163}
164
165/// Variables a session's commands and kernels receive from the session's environment even when this process has
166/// none of that name (the session's lookup cannot be listed): the shell's essentials and the kernel's own settings.
167const SESSION_ENV_NAMES: &[&str] = &[
168    "PATH",
169    "HOME",
170    "USER",
171    "LOGNAME",
172    "SHELL",
173    "TERM",
174    "LANG",
175    "LANGUAGE",
176    "LC_ALL",
177    "LC_CTYPE",
178    "TZ",
179    "TMPDIR",
180    "XDG_CONFIG_HOME",
181    "XDG_DATA_HOME",
182    "XDG_CACHE_HOME",
183    "XDG_STATE_HOME",
184    "XDG_RUNTIME_DIR",
185    "PYTHONPATH",
186    "PYTHONHOME",
187    "VIRTUAL_ENV",
188    config::env::OFFLINE_ENV,
189    config::env::SKIP_VERSION_CHECK_ENV,
190    kernel::env::PYTHON_ENV,
191    kernel::env::RLM_ENV_ALLOW_ENV,
192    kernel::env::BASH_YIELD_AFTER_ENV,
193    kernel::env::RLM_MAX_MEMORY_MB_ENV,
194    kernel::env::RLM_MAX_CPU_SECONDS_ENV,
195    kernel::env::RLM_OUTPUT_BYTES_ENV,
196    kernel::env::RLM_MAX_TREE_MEMORY_MB_ENV,
197    kernel::env::RLM_TREE_MEMORY_BACKEND_ENV,
198];
199
200/// The environment a session's kernels and commands start from (TS: the worker's `process.env`, which kernel.ts
201/// `kernelEnvironment` filters and `getShellEnv` extends): every name this process has plus [`SESSION_ENV_NAMES`],
202/// each with the value the session's `var` gives it (dropped when it gives none). Values come only from the session's
203/// environment, never from this process's: a session whose PATH differs runs its tools from its own PATH.
204pub fn session_environment(var: &dyn Fn(&str) -> Option<String>) -> Vec<(String, String)> {
205    let mut names: Vec<String> = std::env::vars_os()
206        .filter_map(|(name, _)| name.into_string().ok())
207        .collect();
208    for name in SESSION_ENV_NAMES {
209        if !names.iter().any(|known| known == name) {
210            names.push((*name).to_string());
211        }
212    }
213    names
214        .into_iter()
215        .filter_map(|name| var(&name).map(|value| (name, value)))
216        .collect()
217}
218
219/// Whether `ULTRON_GUIDE=ts` asks for the TypeScript guide and output (the TS-recorded replays use it): no Rust-only
220/// APIs, wording or cell-result additions.
221pub fn ts_guide(var: &dyn Fn(&str) -> Option<String>) -> bool {
222    var(GUIDE_ENV).as_deref() == Some("ts")
223}
224
225/// Whether `ULTRON_HINTS=on` ends cell results with situational `[hint:<tag>]` lines (kernel_apis::cell_hints), which
226/// the runtime guide then explains.
227pub fn hints(var: &dyn Fn(&str) -> Option<String>) -> bool {
228    kernel_apis::cell_hints::hints_enabled(var(kernel_apis::cell_hints::HINTS_ENV).as_deref())
229}
230
231/// `ULTRON_TURN_GUARDS`: `off` turns the turn guards off.
232pub const TURN_GUARDS_ENV: &str = "ULTRON_TURN_GUARDS";
233
234/// Whether the turn guards are on: a lane going in circles is told so and its seventh identical cell in a row is
235/// refused (kernel_apis::cell_hints), and the root's turn is continued after an empty reply or with what its
236/// subagents left undone (crate::core `turn_guard`). Off under `ULTRON_TURN_GUARDS=off` and the TypeScript guide.
237pub fn turn_guards(var: &dyn Fn(&str) -> Option<String>) -> bool {
238    !ts_guide(var) && !crate::flag_off(var(TURN_GUARDS_ENV).as_deref())
239}
240
241impl Config {
242    pub fn child_env(&self) -> Vec<(String, String)> {
243        session_environment(&*self.var)
244    }
245
246    /// The kernel environment and output budget a lane reads.
247    pub fn from_env(env: &Env) -> Config {
248        let agent_dir = env.agent_dir();
249        // The worker's settings (`workerProjectTrusted`): a trusted project's `.pi/settings.json` applies too.
250        let manager = config::settings::SettingsManager::for_worker(&env.cwd, &agent_dir, &env.home);
251        let settings = Value::Object(manager.settings().clone());
252        let loki_settings = loki::settings::saved(manager.global_settings());
253        let loki = loki_mode((env.var)(LOKI_ENV).as_deref(), &loki_settings);
254        let loki_hygiene = loki::hygiene::level((env.var)(loki::hygiene::HYGIENE_ENV).as_deref(), &loki_settings);
255        let loki_root = (loki != LokiMode::Off).then(|| git_root(&env.cwd).unwrap_or_else(|| env.cwd.clone()));
256        let skills_dir = (env.var)(kernel::env::CODE_SKILLS_DIR_ENV)
257            .map(|dir| dir.trim().to_string())
258            .filter(|dir| !dir.is_empty())
259            .map_or_else(|| agent_dir.join("skills"), PathBuf::from);
260        let lsp = lsp::enabled((env.var)(lsp::LSP_ENV).as_deref(), &settings)
261            .then(|| lsp::LspGuard::new(session_environment(&*env.var)));
262        Config {
263            cwd: env.cwd.clone(),
264            home: env.home.clone(),
265            snapshot_key: kernel::snapshot_store::session_snapshot_key(&agent_dir, &*env.var),
266            agent_dir,
267            settings,
268            loki,
269            loki_hygiene,
270            loki_root,
271            runtime_path: env.runtime(),
272            skills_dir,
273            mask_secrets: (env.var)(MASK_SECRETS_ENV),
274            output_bytes: (env.var)(kernel::env::RLM_OUTPUT_BYTES_ENV),
275            cell_yield_after: (env.var)(kernel::env::CELL_YIELD_AFTER_ENV),
276            spawn_depth: delegation::host::spawn_depth_limit((env.var)(delegation::host::SPAWN_DEPTH_ENV).as_deref()),
277            async_events: crate::async_events::async_events_enabled(
278                (env.var)(crate::async_events::ASYNC_EVENTS_ENV).as_deref(),
279            ),
280            ts_guide: ts_guide(&*env.var),
281            hints: hints(&*env.var),
282            turn_guards: turn_guards(&*env.var),
283            result_footer: !ts_guide(&*env.var) && config::keys::result_footer(manager.global_settings()),
284            tool_rounds_nudge: crate::nudge::tool_rounds_nudge_from_env(
285                (env.var)(crate::nudge::TOOL_ROUNDS_NUDGE_ENV).as_deref(),
286            ),
287            skill_nudge: crate::nudge::skill_nudge_from_env((env.var)(crate::nudge::SKILL_NUDGE_ENV).as_deref()),
288            context_images: crate::view_images::context_image_budget(
289                (env.var)(crate::view_images::CONTEXT_IMAGES_ENV).as_deref(),
290            ),
291            frame_env: inference::frame_env(&*env.var),
292            var: env.var.clone(),
293            masker: Arc::default(),
294            project_trusted: manager.is_project_trusted(),
295            outside_changes: host::file_hooks::OutsideChanges::default(),
296            lsp,
297            terminal_theme: Arc::default(),
298            provider_token: {
299                let env = env.clone();
300                Arc::new(move |provider: &str| crate::lane::api_key(&crate::ModelFlags::default(), &env, provider))
301            },
302        }
303    }
304
305    /// Reads the settings as they are now, with the worker's project trust (fixed when the session opened): what the
306    /// TypeScript worker reads from its live `SettingsManager` per frame, spawn or request.
307    pub fn settings_reader(&self) -> Arc<dyn Fn() -> config::settings::SettingsManager + Send + Sync> {
308        let (cwd, agent_dir, trusted) = (self.cwd.clone(), self.agent_dir.clone(), self.project_trusted);
309        Arc::new(move || config::settings::SettingsManager::create(&cwd, &agent_dir, trusted))
310    }
311
312    /// The bundled skills directory (packages/coding-agent/skills, beside the runtime), unless
313    /// `ULTRON_BUNDLED_SKILLS` turns it off.
314    pub fn bundled_skills(&self) -> Option<String> {
315        let root = self.runtime_path.ancestors().nth(4)?;
316        crate::session_resources::bundled_skills(&root.join("skills"), &*self.var)
317    }
318
319    /// The session's MCP gateway (TypeScript's extensions/mcp, built in): the servers of `mcp.json`, and of `.pi/mcp.json` in a trusted
320    /// project, reached from the REPL through the `mcp` tool. Server log messages go to `<agentDir>/mcp.log`.
321    pub fn mcp_gateway(&self) -> Arc<mcp::gateway::Gateway> {
322        let masker = self.masker.clone();
323        mcp::gateway::Gateway::new(mcp::gateway::GatewayOptions {
324            agent_dir: self.agent_dir.clone(),
325            project_trusted: self.project_trusted,
326            servers: None,
327            env: mcp::connection::ConnectionEnv {
328                cwd: self.cwd.clone(),
329                home: self.home.clone(),
330                env_overlay: HashMap::new(),
331                client_version: config::version().to_string(),
332                log: Some(Arc::new(mcp::log::ServerLog::new(self.agent_dir.join("mcp.log")))),
333                secrets: Some(Arc::new(move |values: &[String]| {
334                    let values: Vec<Value> = values.iter().map(|v| Value::String(v.clone())).collect();
335                    masker.register_secret_values(&values);
336                })),
337                provider_token: Some(self.provider_token.clone()),
338                // The worker's proxies, with undici's semantics (TS: the worker's `configureHttpDispatcher`).
339                proxy: Some(ai::net::ProxyEnv::from_lookup(&*self.var)),
340                var: Some(self.var.clone()),
341                ..mcp::connection::ConnectionEnv::default()
342            },
343            // The session's PATH finds the launcher (never the process's).
344            open_url: Some(config::browser::browser_opener(
345                (self.var)("PATH"),
346                (self.var)("HOME"),
347                config::browser::opener_vars(&*self.var),
348            )),
349        })
350    }
351
352    /// The model `provider`/`id` of the built-in catalog or models.json, ready for requests.
353    pub fn model(&self, provider: &str, id: &str) -> Option<Model> {
354        let env = Env {
355            cwd: self.cwd.clone(),
356            home: self.home.clone(),
357            var: self.var.clone(),
358            package: PathBuf::new(),
359        };
360        crate::lane::catalog_model(provider, id, &env).ok()
361    }
362
363    /// `rlm.find_models` (session-worker.ts): the available models (`registry.getAvailable()`) as
364    /// `{provider, id, name}`, whatever the query.
365    pub fn find_models(&self) -> Value {
366        let env = Env {
367            cwd: self.cwd.clone(),
368            home: self.home.clone(),
369            var: self.var.clone(),
370            package: PathBuf::new(),
371        };
372        Value::Array(
373            crate::lane::available_models(&env)
374                .iter()
375                .map(|m| json!({"provider": m.provider, "id": m.id, "name": m.name}))
376                .collect(),
377        )
378    }
379
380    /// `rlm.race_models`: `rlm.raceModels` (/settings -> Models) read now, keeping the refs that name a known model.
381    pub fn race_models(&self) -> Value {
382        let picked = config::keys::rlm_model_settings((self.settings_reader())().global_settings()).race_models;
383        picked
384            .into_iter()
385            .filter(|spec| spec.split_once('/').is_some_and(|(p, id)| self.model(p, id).is_some()))
386            .map(Value::String)
387            .collect()
388    }
389
390    /// Refuses a spawn's `model=` unless it names a model of the built-in catalog or models.json.
391    fn model_check(self: &Arc<Self>) -> delegation::host::ModelCheck {
392        let config = self.clone();
393        Arc::new(move |spec: &str| {
394            match spec
395                .split_once('/')
396                .and_then(|(provider, id)| config.model(provider, id))
397            {
398                Some(_) => Ok(()),
399                None => Err(format!("model must be provider/model naming a known model, not {spec}")),
400            }
401        })
402    }
403
404    /// The session's file hooks (session-worker.ts): Loki's guard unless `ULTRON_LOKI` or the global `loki.mode`
405    /// setting turns it off.
406    /// In `cwd` (a worktree subagent's own), Loki checks that tree. Every guard outcome goes to `ULTRON_LOKI_LOG`, then
407    /// to `record` (the session's counters).
408    fn file_hooks_in(&self, cwd: &Path, record: Option<OnRecord>) -> FileHooks {
409        let mut hooks = FileHooks::with_snapshots(cwd, workspace_snapshotter());
410        hooks.ignore_outside(self.outside_changes.clone());
411        hooks.protect(config::paths::AgentPaths::new(&self.agent_dir).protected(), &self.home);
412        match (
413            crate::guard_log::loki_log((self.var)(crate::guard_log::LOKI_LOG_ENV).as_deref()),
414            record,
415        ) {
416            (Some(log), Some(record)) => hooks.on_record(Arc::new(move |outcome: &GuardRecord| {
417                log(outcome);
418                record(outcome);
419            })),
420            (Some(only), None) | (None, Some(only)) => hooks.on_record(only),
421            (None, None) => {}
422        }
423        if let Some(root) = &self.loki_root {
424            let root = if cwd == self.cwd {
425                root.clone()
426            } else {
427                git_root(cwd).unwrap_or_else(|| cwd.to_path_buf())
428            };
429            // Post-write checks compare against the committed policy and a base revision: only in a repository
430            // with a `.loki/` policy (TS: after its auto-install there).
431            let post_write = git_root(cwd).is_some() && root.join(".loki").is_dir();
432            hooks.add(Box::new(
433                LokiGuard::new(&root, self.loki)
434                    .with_post_write(post_write)
435                    .with_hygiene(self.loki_hygiene)
436                    .with_project_python(crate::guard_log::project_python(&*self.var, &self.cwd))
437                    .with_timeout(host::loki_guard::loki_timeout(
438                        (self.var)(LOKI_TIMEOUT_MS_ENV).as_deref(),
439                    )),
440            ));
441        }
442        if let Some(lsp) = &self.lsp {
443            hooks.add(Box::new(lsp.clone()));
444        }
445        hooks
446    }
447
448    /// Per-session directories under the profile, private like snapshots.
449    fn session_dir(&self, kind: &str, session_id: &str) -> PathBuf {
450        self.agent_dir.join(kind).join(session_id)
451    }
452}
453
454/// Lane names as file names (`laneDir` of session-worker.ts).
455fn lane_dir(lane: &str) -> String {
456    lane.chars()
457        .map(|c| {
458            if c.is_ascii_alphanumeric() || "._-".contains(c) {
459                c
460            } else {
461                '_'
462            }
463        })
464        .collect()
465}
466
467/// Live kernels a session keeps (`maxLive` of the TS rlm tool, 16); `rlm.maxLiveKernels` overrides it.
468fn max_live_kernels(settings: &Value) -> usize {
469    settings["rlm"]["maxLiveKernels"]
470        .as_u64()
471        .filter(|n| *n >= 1)
472        .map_or(16, |n| n.min(1024) as usize)
473}
474
475/// Where each lane's kernel snapshot lives (the path its kernel restores at startup): the pool snapshots an idle
476/// kernel there before evicting it.
477fn lane_snapshot_path(config: &Arc<Config>, session_id: &str) -> lanes::SnapshotPathFn {
478    let snapshots = config.session_dir("rlm-snapshots", session_id);
479    Arc::new(move |lane: &str| {
480        Some(
481            snapshots
482                .join(format!("{}.snapshot", lane_dir(lane)))
483                .display()
484                .to_string(),
485        )
486    })
487}
488
489/// The runtime guide's view of the `mcp` gateway: the tool and its servers when `mcp.json` names any.
490pub fn mcp_runtime_guide(config: &Config) -> resources::runtime_guide::RuntimeGuideOptions {
491    let tool = config.mcp_gateway().tool();
492    resources::runtime_guide::RuntimeGuideOptions {
493        mcp_servers: tool
494            .as_ref()
495            .map(|t| mcp::gateway::server_names_of(&t.description))
496            .unwrap_or_default(),
497        // The REPL's only `tools.*` tool is the gateway (TypeScript lists it among its extension tools): without
498        // `mcp.json` servers there is none, and the guide has no tools section.
499        extension_tools: tool
500            .into_iter()
501            .map(|t| resources::runtime_guide::ExtensionToolSummary {
502                name: t.name,
503                description: t.description,
504            })
505            .collect(),
506        // The session runtime serves `rlm.ask`, `swarm`, `board`, `notes` (swarm_ops.rs) and typed memory: the model
507        // is told, unless `ULTRON_GUIDE=ts` asks for the TypeScript guide (the TS-recorded request replays use it).
508        durable_apis: !config.ts_guide,
509        // The root is woken by its work's ends only with completion events on (crate::wake); with them off it is
510        // told to wait (`ULTRON_ASYNC_EVENTS=off`).
511        delivery: if config.async_events {
512            resources::runtime_guide::EventDelivery::Wake
513        } else {
514            resources::runtime_guide::EventDelivery::Off
515        },
516        // The woken root's rlm.collect never waits (crate::wake); TypeScript's guide (`ULTRON_GUIDE=ts`, its
517        // recorded replays) keeps its wording.
518        host_waits: !config.ts_guide,
519        // Cell results end with `[hint:<tag>]` lines under `ULTRON_HINTS=on`: the guide says what to do with them.
520        hints: config.hints,
521        result_footer: config.result_footer,
522        ..Default::default()
523    }
524}
525
526/// The root system prompt, rendered again only when the settings' [`crate::lane::PromptMode`] changes (engineering
527/// mode, `alwaysSkills`), so the prompt-cache prefix stays stable (session-worker.ts `currentSystemPrompt`). A
528/// change applies from the next request.
529#[derive(Clone)]
530pub struct SystemPrompt(Arc<PromptState>);
531
532type RenderPrompt = dyn Fn(&crate::lane::PromptMode) -> Result<(String, Vec<String>), String> + Send + Sync;
533type RenderChildPrompt = dyn Fn(&crate::lane::PromptMode, ChildReader) -> Result<String, String> + Send + Sync;
534
535/// Who a subagent's prompt is for: an in-memory child (without the durable runtime's APIs) or not, and how much its
536/// guide says about memory (crate::memory_guidance, by its model's tier).
537#[derive(Clone, Copy, Debug, PartialEq, Eq)]
538pub struct ChildReader {
539    pub in_memory: bool,
540    pub memory: crate::memory_guidance::MemoryGuidance,
541}
542
543struct PromptState {
544    /// `None`: a fixed prompt.
545    render: Option<Box<RenderPrompt>>,
546    /// A subagent's prompt, by [`ChildReader`]; `None`: as the root's.
547    render_child: Option<Box<RenderChildPrompt>>,
548    /// The subagent prompt last rendered, by mode and reader.
549    child: Mutex<Option<(crate::lane::PromptMode, ChildReader, String)>>,
550    mode: Box<dyn Fn() -> crate::lane::PromptMode + Send + Sync>,
551    current: Mutex<(crate::lane::PromptMode, String, Vec<String>)>,
552    /// The session's own persona toggle over the settings' (resources::keep_going): `None` follows the settings.
553    persona: Mutex<Option<bool>>,
554    /// The root lane's model id ([`crate::lane::PromptMode::model`]).
555    model: Mutex<String>,
556}
557
558impl SystemPrompt {
559    pub fn fixed(text: impl Into<String>) -> SystemPrompt {
560        SystemPrompt(Arc::new(PromptState {
561            render: None,
562            render_child: None,
563            child: Mutex::new(None),
564            mode: Box::new(crate::lane::PromptMode::default),
565            current: Mutex::new((Default::default(), text.into(), Vec::new())),
566            persona: Mutex::new(None),
567            model: Mutex::new(String::new()),
568        }))
569    }
570
571    /// The native worker's prompt for `env`'s working directory, in the mode its settings name now (read with the
572    /// worker's project trust).
573    fn rendered(
574        env: &Env,
575        config: &Config,
576        trusted: bool,
577        guide: resources::runtime_guide::RuntimeGuideOptions,
578        flags: &crate::session_flags::SessionFlags,
579        extra: Arc<crate::session_resources::SessionResources>,
580    ) -> Result<SystemPrompt, String> {
581        let (cwd, agent_dir) = (env.cwd.clone(), config.agent_dir.clone());
582        let (no_skills, no_context_files) = (flags.no_skills, flags.no_context_files);
583        let mode = move || {
584            let settings = config::settings::SettingsManager::create(&cwd, &agent_dir, trusted);
585            crate::lane::PromptMode {
586                no_skills,
587                no_context_files,
588                ..crate::lane::PromptMode::from_settings(&settings)
589            }
590        };
591        let (env, loki_root) = (env.clone(), config.loki_root.clone());
592        let (child_env, child_loki, child_extra) = (env.clone(), loki_root.clone(), extra.clone());
593        let child_guide = guide.clone();
594        let render = move |mode: &crate::lane::PromptMode| {
595            crate::lane::system_prompt_with_resources(
596                &env,
597                &env.cwd.display().to_string(),
598                loki_root.as_deref(),
599                &guide,
600                mode,
601                &extra,
602            )
603        };
604        // A subagent's guide (crate::wake): it awaits what its answer needs, has no `schedule`, and an in-memory
605        // child has no persistent children, `swarm`, `board` or `notes`.
606        let render_child = move |mode: &crate::lane::PromptMode, reader: ChildReader| {
607            let guide = resources::runtime_guide::RuntimeGuideOptions {
608                reader: resources::runtime_guide::GuideReader::Subagent {
609                    swarm: !reader.in_memory,
610                },
611                memory: reader.memory,
612                ..child_guide.clone()
613            };
614            crate::lane::system_prompt_with_resources(
615                &child_env,
616                &child_env.cwd.display().to_string(),
617                child_loki.as_deref(),
618                &guide,
619                mode,
620                &child_extra,
621            )
622            .map(|(text, _)| text)
623        };
624        let initial = mode();
625        let (text, warnings) = render(&initial)?;
626        Ok(SystemPrompt(Arc::new(PromptState {
627            render: Some(Box::new(render)),
628            render_child: Some(Box::new(render_child)),
629            child: Mutex::new(None),
630            mode: Box::new(mode),
631            current: Mutex::new((initial, text, warnings)),
632            persona: Mutex::new(None),
633            model: Mutex::new(String::new()),
634        })))
635    }
636
637    /// The prompt in the settings' current mode. A mode whose prompt does not render keeps the last one.
638    pub fn current(&self) -> String {
639        let state = &self.0;
640        let Some(render) = &state.render else {
641            return sync::lock(&state.current).1.clone();
642        };
643        let mut mode = (state.mode)();
644        if let Some(persona) = *sync::lock(&state.persona) {
645            mode.persona = persona;
646        }
647        mode.model = sync::lock(&state.model).clone();
648        let mut current = sync::lock(&state.current);
649        if current.0 != mode
650            && let Ok((text, warnings)) = render(&mode)
651        {
652            *current = (mode, text, warnings);
653        }
654        current.1.clone()
655    }
656
657    /// A subagent's prompt in the settings' current mode, for `reader`: the root's, with the subagent's runtime
658    /// guide and the notes of `model` (the subagent's own). A fixed prompt is the same for every lane.
659    pub fn child_current(&self, reader: ChildReader, model: &str) -> String {
660        let state = &self.0;
661        let Some(render) = &state.render_child else {
662            return self.current();
663        };
664        let mut mode = (state.mode)();
665        if let Some(persona) = *sync::lock(&state.persona) {
666            mode.persona = persona;
667        }
668        mode.model = model.to_string();
669        let mut child = sync::lock(&state.child);
670        if let Some((cached, cached_reader, text)) = &*child
671            && *cached == mode
672            && *cached_reader == reader
673        {
674            return text.clone();
675        }
676        match render(&mode, reader) {
677            Ok(text) => {
678                *child = Some((mode, reader, text.clone()));
679                text
680            }
681            Err(_) => {
682                drop(child);
683                self.current()
684            }
685        }
686    }
687
688    /// The session's persona toggle (`None`: follow the settings), applied from the next request.
689    pub fn set_persona(&self, persona: Option<bool>) {
690        *sync::lock(&self.0.persona) = persona;
691    }
692
693    /// The root lane's model, applied from the next request.
694    pub fn set_model(&self, id: &str) {
695        *sync::lock(&self.0.model) = id.to_string();
696    }
697
698    /// The `alwaysSkills` problems of the prompt as last rendered.
699    pub fn warnings(&self) -> Vec<String> {
700        sync::lock(&self.0.current).2.clone()
701    }
702}
703
704/// The process-wide composition: configuration and injected services.
705pub struct Runtime {
706    pub config: Arc<Config>,
707    pub services: Services,
708    /// Problems found building the session (the `alwaysSkills` warnings of the system prompt), reported once.
709    pub diagnostics: Vec<String>,
710    /// The root lane's system prompt (subagents use it too).
711    pub system: SystemPrompt,
712    /// Where session-scoped host files (job logs, inference context) live: the cwd's session directory.
713    pub sessions_dir: PathBuf,
714    /// `print`, `json`, `rpc` or `interactive`.
715    pub mode: String,
716    /// The Hindsight server and bank every instance shares (`ULTRON_HINDSIGHT_URL`, the global `hindsightUrl`
717    /// setting, else localhost:8888; `ULTRON_HINDSIGHT_BANK`, else "ultron"); `None`: memory is off.
718    pub hindsight: Option<hindsight::Endpoint>,
719    /// The memorantado server memory uses instead, when `memory.backend` says so or (unset) it answered once
720    /// (memorantado::resolve).
721    pub memorantado: Option<memorantado::Endpoint>,
722    /// Set when memorantado is the backend but did not answer at start: memory is paused (never written to
723    /// Hindsight instead); the session shows it once.
724    pub memory_notice: Option<String>,
725    /// Whether the memory server was set explicitly (`ULTRON_HINDSIGHT_URL` or the `hindsightUrl` setting;
726    /// `memory.backend: memorantado`, `ULTRON_MEMORANTADO_URL` or `memorantadoUrl`), not a default: automatic
727    /// memory defaults to it (crate::auto_memory).
728    pub memory_explicit: bool,
729}
730
731/// The memory backend a process uses ([`memory_backend`]).
732pub struct MemoryChoice {
733    pub backend: memorantado::Backend,
734    /// The Hindsight server resolved from `ULTRON_HINDSIGHT_URL` and `hindsightUrl` (`None`: off), whichever backend
735    /// was chosen.
736    pub hindsight: Option<hindsight::Endpoint>,
737    /// Memory was configured on purpose (a server set, or `memory.backend`), not only the defaults.
738    pub explicit: bool,
739}
740
741/// The memory backend of a process with `var` and the settings of `manager` (profile `agent_dir`):
742/// [`memorantado::Endpoint::choose`] over the Hindsight server resolved the same way, probing memorantado over HTTP.
743/// Sessions and `ultron memory` both choose through it.
744pub fn memory_backend(
745    var: &dyn Fn(&str) -> Option<String>,
746    manager: &config::settings::SettingsManager,
747    agent_dir: &Path,
748) -> MemoryChoice {
749    let (url, source) = hindsight::resolve::resolve_in(var, manager);
750    let hindsight_set = source != hindsight::resolve::Source::Default;
751    let hindsight = hindsight::Endpoint::at(url, var);
752    let resolved = match (&hindsight, hindsight_set) {
753        (None, _) => memorantado::Hindsight::Off,
754        (Some(_), false) => memorantado::Hindsight::Default,
755        (Some(_), true) => memorantado::Hindsight::Set,
756    };
757    let backend = memorantado::Endpoint::choose(var, manager, agent_dir, resolved, &memorantado::resolve::probe);
758    let explicit = hindsight_set
759        || (backend.memorantado().is_some()
760            && (memorantado::resolve::choice(manager) == Some(memorantado::Choice::Memorantado)
761                || var(memorantado::resolve::MEMORANTADO_URL_ENV).is_some()
762                || memorantado::resolve::setting_url(manager).is_some()));
763    MemoryChoice {
764        backend,
765        hindsight,
766        explicit,
767    }
768}
769
770impl Runtime {
771    /// Read the settings and the local resources for `cwd` (`mode`: "print", "json" or "rpc") and build the root
772    /// system prompt.
773    pub fn new(env: &Env, mode: &str, sessions_dir: PathBuf, services: Services) -> Result<Runtime, String> {
774        let mut services = services;
775        let config = Config::from_env(env);
776        let trusted = config.project_trusted;
777        let manager = config::settings::SettingsManager::create(&env.cwd, &config.agent_dir, trusted);
778        // resource-loader.ts `reload`: the local skills and prompts.
779        let mut resolved = crate::session_resources::resolve(
780            env,
781            config::settings::SettingsManager::create(&env.cwd, &config.agent_dir, trusted),
782            services.session.append_system_prompt.as_deref(),
783        );
784        // `--skill <path>`: after the discovered skills (resource-loader.ts `additionalSkillPaths`).
785        resolved
786            .skill_paths
787            .extend(services.session.skill_paths.iter().cloned());
788        services.resources = Arc::new(resolved);
789        let mut diagnostics: Vec<String> = Vec::new();
790        let MemoryChoice {
791            backend,
792            hindsight,
793            explicit: memory_explicit,
794        } = memory_backend(&*env.var, &manager, &config.agent_dir);
795        // Once memorantado is the backend, Hindsight is never written: an outage pauses memory, with a notice.
796        let memory_notice = match &backend {
797            memorantado::Backend::Memorantado { endpoint, up: false } => Some(endpoint.paused_notice()),
798            _ => None,
799        };
800        diagnostics.extend(memory_notice.clone());
801        let hindsight = hindsight.filter(|_| backend == memorantado::Backend::Hindsight);
802        let memorantado = backend.memorantado().cloned();
803        // The `mcp` gateway lives in the REPL: the runtime guide lists it with its servers (`mcpServerNames`).
804        let runtime_guide = resources::runtime_guide::RuntimeGuideOptions {
805            // Topic pages are memorantado's (its dreaming writes them); an injected backend is neither.
806            memory_topics: memorantado.is_some() && services.memory.is_none(),
807            ..mcp_runtime_guide(&config)
808        };
809        let system = match &services.session.system_prompt {
810            // `--system-prompt`: exactly the given text (`currentSystemPrompt`).
811            Some(text) => SystemPrompt::fixed(text.clone()),
812            None => SystemPrompt::rendered(
813                env,
814                &config,
815                trusted,
816                runtime_guide,
817                &services.session,
818                services.resources.clone(),
819            )?,
820        };
821        diagnostics.extend(system.warnings());
822        if let Err(error) =
823            crate::core::turn_guard::parse_checks(config.settings.as_object().unwrap_or(&Default::default()))
824        {
825            diagnostics.push(format!("{error}; no turn-end check runs"));
826        }
827        Ok(Runtime {
828            config: Arc::new(config),
829            services,
830            diagnostics,
831            system,
832            sessions_dir,
833            mode: mode.to_string(),
834            hindsight,
835            memorantado,
836            memory_notice,
837            memory_explicit,
838        })
839    }
840
841    /// The host stack of one session, whose lanes call `model`; `api_key` (`--api-key`) is the key of `model`'s
842    /// provider, every other provider's requests resolve their own credentials per request.
843    pub fn stack(&self, model: &Model, api_key: Option<String>, session_id: &str) -> Result<Arc<Stack>, String> {
844        self.stack_with(model, api_key, session_id, None)
845    }
846
847    /// [`Runtime::stack`] whose subagents run as `subagents` says (default: each on its agent loop, with an
848    /// in-memory task journal).
849    pub fn stack_with(
850        &self,
851        model: &Model,
852        api_key: Option<String>,
853        session_id: &str,
854        subagents: Option<SubagentHost>,
855    ) -> Result<Arc<Stack>, String> {
856        let mut subagents = subagents;
857        // Without a subagent host, children run as in-memory agent loops, steerable by the agent hub and measured
858        // for their context reminder (crate::memory_children).
859        let memory_children = subagents
860            .is_none()
861            .then(|| Arc::new(crate::memory_children::MemoryChildren::default()));
862        let config = self.config.clone();
863        // Shell jobs are durable: their journal is in the session's module directory, and opening the host recovers
864        // the jobs a dead worker left (from their processes).
865        let values = self.services.values.clone();
866        let jobs: Arc<dyn kernel::store::DocumentStore> = match &values {
867            Some(values) => Arc::new(crate::session_modules::ModuleJobJournal(
868                crate::session_modules::ModuleDocument(values.document(session_journal::ns::MODULE, "jobs")),
869            )),
870            None => Arc::new(kernel::store::FileDocumentStore::new(
871                config.session_dir("rlm-modules", session_id).join("jobs.json"),
872            )),
873        };
874        // The session's runtime counters (`ultron.module/stats`): saved once the session actor attaches its journal.
875        let stats = Arc::new(SessionStats::system("lane"));
876        // Typed memory records (kernel_apis::memory_records) are shared by every session of the agent directory;
877        // a cell's file changes that match one point at it with the next result (kernel_apis::memory_pointers).
878        let memory_records = Arc::new(kernel_apis::memory_records::RecordIndex::for_agent_dir(
879            &config.agent_dir,
880        ));
881        // In engineering mode, the skill that fits a cell's file changes comes with its result
882        // (crate::situational_skills).
883        // Skill procedures in progress (`skills.run`, delegation::skill_runs) watch each cell for changes outside the
884        // current segment's files.
885        let skill_runs = Arc::new(delegation::skill_runs::RunBook::default());
886        let observers = self
887            .memory_pointers(session_id, &memory_records)
888            .into_iter()
889            .chain(self.situational_skills())
890            .chain(Some(skill_runs.clone() as Arc<dyn host::file_hooks::CellObserver>))
891            .collect();
892        let host = Arc::new(
893            self.host_in(&config.cwd, session_id, "bash", Some(&stats), observers)?
894                .with_journal(jobs)?,
895        );
896        crate::guard_log::loki_setup(&config);
897        // `createSessionModuleStore(session, name)`: the session value `ultron.module/<name>`.
898        let modules = |name: &str| -> Arc<dyn kernel::store::DocumentStore> {
899            match &values {
900                Some(values) => Arc::new(crate::session_modules::ModuleDocument(
901                    values.document(session_journal::ns::MODULE, name),
902                )),
903                None => Arc::new(FileDocumentStore::new(
904                    config
905                        .session_dir("rlm-modules", session_id)
906                        .join(format!("{name}.json")),
907                )),
908            }
909        };
910        // TS createWorkerServices: a configured server gives every session a backend tagged with the session, its
911        // project directory and the home directory; an invalid URL fails the session as it does there.
912        let (cwd, home) = (config.cwd.display().to_string(), config.home.display().to_string());
913        let backend = match (&self.services.memory, &self.memorantado, &self.hindsight) {
914            (Some(backend), _, _) => Some(backend.clone()),
915            (None, Some(endpoint), _) => Some(Arc::new(
916                endpoint
917                    .session_backend(session_id, &cwd, &home)
918                    .map_err(|e| e.to_string())?,
919            ) as Arc<dyn MemoryBackend>),
920            (None, None, Some(endpoint)) => Some(Arc::new(
921                endpoint
922                    .session_backend(session_id, &cwd, &home)
923                    .map_err(|e| e.to_string())?,
924            ) as Arc<dyn MemoryBackend>),
925            (None, None, None) => None,
926        };
927        let memory = match &backend {
928            Some(backend) => Some(
929                MemoryService::new(
930                    match &values {
931                        Some(values) => Arc::new(crate::session_modules::ModuleDocument(values.document(
932                            session_journal::ns::MEMORY_ROOT.namespace,
933                            session_journal::ns::MEMORY_ROOT.key,
934                        ))),
935                        None => modules("memory"),
936                    },
937                    backend.clone(),
938                    kernel_apis::worker_gate(),
939                )
940                .map_err(|e| format!("memory: {e:?}"))?
941                .with_records(memory_records.clone())
942                .with_root(config.cwd.clone()),
943            ),
944            None => None,
945        };
946        let skills_config = config.clone();
947        let no_skills = self.services.session.no_skills;
948        let extra = self.services.resources.clone();
949        let loader: kernel_apis::SkillLoader = Arc::new(move || Ok(skill_sources(&skills_config, &extra, no_skills)));
950        // Skill test kernels start from the session's environment, as the lanes' kernels do.
951        let code = CodeSkills::new(CodeSkillsOptions::for_session(
952            &config.skills_dir,
953            &config.runtime_path,
954            config.child_env(),
955        ));
956        let clock = kernel_apis::util::system_clock();
957        // The local services: refinements (lessons, checked by the worker's activation rules) and experiment history in
958        // one keyed document file, release gates in their module document. Active instruction refinements reach
959        // later typed-agent prompts through the host's refinement hook.
960        let local = Arc::new(services::LocalServices::worker(match &values {
961            Some(values) => Box::new(values.keyed(session_journal::ns::LOCAL)),
962            None => Box::new(kernel_apis::artifacts::FileKeyedDocuments::new(
963                config.session_dir("rlm-modules", session_id).join("local.json"),
964            )),
965        }));
966        // Refinements follow the conversation branch (`mainBranch`): anchored at the main lane's tip, read back only
967        // while the anchor is on the branch in use (A07).
968        let branch = values.as_ref().map(crate::session_modules::main_branch);
969        let refinements = services::instruction_hook(local.clone(), branch.clone());
970        let ledger = crate::auto_refine::Ledger {
971            services: local.clone(),
972            branch: branch.clone(),
973        };
974        // `session_start` of the MCP extension: eager servers connect in the background; configuration errors were
975        // reported with the runtime's diagnostics.
976        let gateway = config.mcp_gateway();
977        let notices = gateway.start(self.services.mcp_notices.clone());
978        if let Some(notify) = &self.services.mcp_notices {
979            for (message, level) in notices {
980                notify(&message, &level);
981            }
982        }
983        if let Some(on_mcp) = &self.services.on_mcp {
984            on_mcp(&gateway);
985        }
986        let images = Arc::new(crate::view_images::ViewImages::new(
987            model.clone(),
988            config.cwd.clone(),
989            config.agent_dir.clone(),
990            config.project_trusted,
991        ));
992        // `--api-key` is a runtime key of the starting model's provider only (`setRuntimeApiKey`); every request
993        // resolves its provider's key when it is sent (crate::request_keys).
994        let keys = crate::request_keys::Keys::new(
995            api_key.map(|key| (model.provider.clone(), key)),
996            config.provider_token.clone(),
997        );
998        let root_model = Arc::new(Mutex::new(model.clone()));
999        self.system.set_model(&model.id);
1000        // `judge.decide` settles in the session's usage ledger, built with the stack below.
1001        let judge_ledger: Arc<std::sync::OnceLock<UsageLedger>> = Arc::default();
1002        // Its usage rows go to the session's values (set later by a composer that keeps them elsewhere).
1003        let judge_rows: Arc<std::sync::OnceLock<services::SessionValues>> = Arc::default();
1004        if let Some(values) = &values {
1005            let _ = judge_rows.set(values.clone());
1006        }
1007        let judge = Arc::new(crate::session_judge::module(
1008            &config,
1009            root_model.clone(),
1010            keys.clone(),
1011            judge_rows.clone(),
1012            judge_ledger.clone(),
1013        ));
1014        let skills = Arc::new(SkillsModule::new(modules("skills"), loader, clock.clone(), Some(code)));
1015        // A skill procedure's `check` commands run as spawn contract checks do, with the stack's check runner.
1016        let skill_checks: Arc<std::sync::OnceLock<delegation::spawn_contract::CheckRunner>> = Arc::default();
1017        // Runs a dead worker left `running` end `interrupted` now: their book died with it. A store that cannot be
1018        // read leaves them for the next start.
1019        let procedures = Arc::new(delegation::skill_runs::SkillRuns {
1020            book: skill_runs,
1021            skills: skills.clone(),
1022            judge: judge.clone(),
1023            cwd: config.cwd.clone(),
1024            env: config.child_env(),
1025            runner: skill_checks.clone(),
1026            proposals: config::paths::AgentPaths::new(&config.agent_dir).skill_proposals(),
1027            session_id: Some(session_id.to_string()),
1028            now: clock.clone(),
1029        });
1030        let _ = procedures.interrupt_orphans();
1031        let apis = ApiModules {
1032            local: Arc::new(services::LocalServicesModule {
1033                services: local,
1034                branch,
1035            }),
1036            gates: Arc::new(services::ReleaseGateModule::new(modules("release-gates"), None)),
1037            procedures,
1038            skills,
1039            memory: Arc::new(MemoryApi {
1040                service: memory.map(|memory| memory.with_judge(crate::session_judge::decider(judge.clone()))),
1041            }),
1042            hints: Arc::new(HintsModule::new(modules("hints"))),
1043            images: Arc::new(crate::session_images::module(&config, session_id)),
1044            diagram: Arc::new(crate::session_diagrams::module(&config, session_id, images.clone())),
1045            knowledge: Arc::new(crate::session_knowledge::module(
1046                &config,
1047                self.memorantado.clone(),
1048                judge.clone(),
1049            )),
1050            judge,
1051            schedule: Arc::new(
1052                kernel_apis::prompt_schedule::ScheduleModule::new(
1053                    match &values {
1054                        Some(values) => Box::new(values.keyed(kernel_apis::prompt_schedule::NAMESPACE)),
1055                        None => Box::new(kernel_apis::artifacts::MemoryKeyedDocuments::default()),
1056                    },
1057                    session_id,
1058                    kernel_apis::prompt_schedule::clock_for(&*config.var),
1059                    self.services.on_schedules.clone(),
1060                )
1061                .with_github(kernel_apis::prompt_schedule::GitHub::for_env(&*config.var)),
1062            ),
1063            // `tools.*`: the `mcp` gateway called from the REPL, detached after `yield_after`.
1064            tools: Arc::new(kernel_apis::ToolCalls::new(
1065                gateway.tool().is_some().then(|| {
1066                    Arc::new(crate::session_tools::SessionTools { mcp: gateway.clone() })
1067                        as Arc<dyn kernel_apis::ToolRunner>
1068                }),
1069                modules("tool-calls"),
1070            )),
1071            // The task modules of session-worker.ts over the typed-agent host: retained instances (their lanes
1072            // pinned in the kernel pool), progress with verifier runs, and family messages.
1073            instances: Arc::new(kernel_apis::InstancesModule::new(modules("instances"), None)),
1074            progress: Arc::new(kernel_apis::ProgressModule::new(modules("progress"))),
1075            family: Arc::new(kernel_apis::FamilyModule::new(
1076                modules("family"),
1077                kernel_apis::FamilyOptions::default(),
1078            )),
1079            sessions: Arc::new(session_search(&config, &self.sessions_dir, session_id)),
1080        };
1081        // Situational hints (`ULTRON_HINTS=on`): what a cell did, observed per lane, ends its result with one line.
1082        let var = |key: &str| (config.var)(key);
1083        let context_reminders = Arc::new(crate::context_reminder::ContextReminders::new(
1084            crate::context_reminder::ReminderSettings::from_vars(
1085                var(CONTEXT_REMINDER_ENV).as_deref(),
1086                var(CONTEXT_REMINDER_TOKENS_ENV).as_deref(),
1087            ),
1088        ));
1089        let cell_hints = Arc::new(kernel_apis::cell_hints::CellHints::new(
1090            apis.hints.clone(),
1091            kernel_apis::cell_hints::CellHintsOptions {
1092                enabled: config.hints,
1093                guards: config.turn_guards,
1094                max_per_tag: kernel_apis::cell_hints::hint_max_per_tag(
1095                    var(kernel_apis::cell_hints::HINTS_MAX_ENV).as_deref(),
1096                ),
1097                async_events: config.async_events,
1098                read_handle_bytes: kernel_apis::cell_hints::read_handle_bytes(var(READ_HANDLE_BYTES_ENV).as_deref()),
1099                ..Default::default()
1100            },
1101        ));
1102        let session_id = session_id.to_string();
1103        let system = self.system.clone();
1104        let sessions_dir = self.sessions_dir.clone();
1105        let services = self.services.clone();
1106        let model = model.clone();
1107        // One request stack for every lane's frames (built once: an HTTP client is not free, and a handler is made
1108        // per cell); it reads the settings per request.
1109        let frame_stream = crate::request_keys::lane_stream(config.settings_reader(), keys.clone());
1110        let child = ChildDefaults {
1111            model: model.clone(),
1112            keys: keys.clone(),
1113        };
1114        let mut built: Result<(), String> = Ok(());
1115        let (schedules_store, goal_store) = (modules("schedules"), modules("goal"));
1116        let wake = crate::wake::RootWake::default();
1117        let hints_wake = wake.clone();
1118        cell_hints.set_lane_woken(Arc::new(move |lane: &str| hints_wake.woken(lane)));
1119        let memory_children_on = memory_children.is_some();
1120        let agent_lanes = self.services.agent_lanes.clone();
1121        let stack = Arc::new_cyclic(|me: &Weak<Stack>| {
1122            let runner_stack = me.clone();
1123            let (store, inner, agent_stores) = match subagents.take() {
1124                Some(host) => (Some(host.store), (host.runner)(me.clone()), host.agents),
1125                None => {
1126                    let factory: delegation::child::ChildAgentFactory =
1127                        Arc::new(move |run: &ChildRun| child_agent(&runner_stack, &child, run));
1128                    let runner = match &memory_children {
1129                        Some(children) => children.runner(factory),
1130                        None => agent_runner(factory),
1131                    };
1132                    // Typed agents keep in-memory records, their `rlm` lanes run where `agent_lanes` says.
1133                    let agent_stores = agent_lanes.as_ref().map(|lanes| {
1134                        let lanes = lanes.clone();
1135                        AgentStores {
1136                            tasks: Box::new(MemoryDocumentStore::default()),
1137                            definitions: Box::new(MemoryDocumentStore::default()),
1138                            usage: Box::new(MemoryDocumentStore::default()),
1139                            lanes: Box::new(move |stack| lanes(stack)),
1140                            frames: Arc::new(inference::MemoryTraceStore::default()),
1141                        }
1142                    });
1143                    (None, runner, agent_stores)
1144                }
1145            };
1146            let goal_slot: Arc<std::sync::OnceLock<Arc<GoalDriver>>> = Arc::new(std::sync::OnceLock::new());
1147            // Bounded-inference frames: traces as session values (in memory without a session), run as
1148            // `rlm-frame@1` tasks of the typed-agent host.
1149            let frames = inference::FrameSession::new(match &agent_stores {
1150                Some(stores) => stores.frames.clone(),
1151                None => Arc::new(inference::MemoryTraceStore::default()),
1152            });
1153            let (agents, usage, task_ends) = typed_agents(
1154                &config,
1155                agent_stores,
1156                me.clone(),
1157                root_model.clone(),
1158                keys.clone(),
1159                goal_slot.clone(),
1160                Some(refinements),
1161                crate::frames::frame_runner(frames.clone()),
1162                &stats,
1163            );
1164            let _ = judge_ledger.set(usage.clone());
1165            frames.set_tasks(Arc::new(crate::frames::StackFrameTasks {
1166                agents: agents.clone(),
1167                usage: usage.clone(),
1168                stack: me.clone(),
1169            }));
1170            // Schedules and the session goal are durable tasks of the typed-agent host.
1171            let schedules = Arc::new(SchedulesModule::new(schedules_store, None));
1172            let goal = Arc::new(GoalDriver::new(
1173                goal_store,
1174                Arc::new(TaskGoalJobs::new(Arc::new(agents.clone()), host.clone())),
1175                kernel_apis::util::system_clock(),
1176            ));
1177            let _ = goal_slot.set(goal.clone());
1178            let closer = me.clone();
1179            // A subagent's lane closes when its run ends; its stuck-loop hints start over with its next run
1180            // (`cellHints.runEnded(lane)` on every lane's `run_end`).
1181            let runner: ChildRunner = Arc::new(move |run: ChildRun| {
1182                let lane = run.lane_name.clone();
1183                let result = inner(run);
1184                if let Some(stack) = closer.upgrade() {
1185                    stack.cell_hints.run_ended(&lane);
1186                    let _ = stack.lanes.close_lane(&lane);
1187                    stack.retire_workspace(&lane);
1188                }
1189                result
1190            });
1191            let mut options = DelegationOptions::new(runner);
1192            if let Some(store) = store {
1193                options.store = store;
1194            }
1195            // Per lane (crate::wake): a woken root's cell never waits for subagents (rlm.collect returns what has
1196            // ended, and the host waits between turns, delivering each end as a child_done event); every other
1197            // lane waits in its cell.
1198            let lane_wake = wake.clone();
1199            options.collect = Arc::new(move |lane: &str| lane_wake.collect_mode(lane));
1200            options.spawn_depth = config.spawn_depth;
1201            options.session_id = session_id.clone();
1202            options.workspace = Some(config.cwd.clone());
1203            options.now = Box::new(|| jsrt::date::now_ms() as f64);
1204            // `ULTRON_KEEP_WORKTREES`: worktrees and branches stay after merges, on close and at startup.
1205            options.keep_worktrees = delegation::worktrees::keep_worktrees(
1206                (config.var)(delegation::worktrees::KEEP_WORKTREES_ENV).as_deref(),
1207            );
1208            // Read per worktree spawn, as session-worker.ts passes it: the `worktrees` setting, so a changed setting
1209            // applies to the next subagent.
1210            let settings = config.settings_reader();
1211            options.worktree_setup = Arc::new(move || {
1212                let configured = config::keys::worktree_settings(settings().settings());
1213                Some(delegation::worktrees::WorktreeSetup {
1214                    link: configured.link,
1215                    copy: configured.copy,
1216                    command: configured.command,
1217                    timeout_ms: None,
1218                })
1219            });
1220            // How each worktree child's merge ended is counted (`onMerge`).
1221            let merges = stats.clone();
1222            options.on_merge = Some(Arc::new(move |task: &str, status: &str| merges.merge(task, status)));
1223            // A spawn naming a model the session cannot run is refused, never run on the root's model (A04).
1224            options.model_check = Some(config.model_check());
1225            // Spawn contract `run` checks run under the session's shell sandbox, in the child's working directory.
1226            options.check_runner = crate::contract_checks::check_runner(me.clone());
1227            let _ = skill_checks.set(options.check_runner.clone());
1228            // Contract baselines run git with the session's environment (its PATH finds git).
1229            options.command_env = config.child_env();
1230            let (delegation, child_ends) = Delegation::new(options);
1231            // Read per spawn, as session-worker.ts passes it: `rlm.childModel` (/settings -> Models), so a changed
1232            // setting applies to the next subagent.
1233            let settings = config.settings_reader();
1234            delegation.set_child_model(Arc::new(move || {
1235                config::keys::rlm_model_settings(settings().global_settings()).child_model
1236            }));
1237            // Worktrees of sessions that ended without cleaning up (a crash): pruned in the background, their work
1238            // kept on its branch (native-host.ts `loadTasks`).
1239            let pruning = delegation.clone();
1240            std::thread::spawn(move || pruning.prune_orphan_worktrees());
1241            // Workflow nodes with worktree=True run as subagents of the workflow's caller (worktrees live there).
1242            agents.set_worktree_children(delegation.clone());
1243            let factory_stack = me.clone();
1244            let handler_stack = me.clone();
1245            let lanes = Lanes::new(LanesOptions {
1246                create: Arc::new(move |lane| {
1247                    let stack = factory_stack.upgrade().ok_or("the session is closed")?;
1248                    stack.kernel(lane)
1249                }),
1250                handlers: Arc::new(move |lane, signal, park| match handler_stack.upgrade() {
1251                    Some(stack) => stack.cell_handler(lane, Some((signal, park))),
1252                    None => Arc::new(Closed) as Arc<dyn HostHandler>,
1253                }),
1254                max_lanes: 64,
1255                cancel_grace: Duration::from_secs(5),
1256                // Live kernels are bounded as the TS session's rlm tool bounds them (A43): an idle lane is
1257                // snapshotted to its own snapshot path and evicted, and its next cell restores it.
1258                pool: Some(lanes::PoolLimits::new(
1259                    max_live_kernels(&config.settings),
1260                    Some(lane_snapshot_path(&config, &session_id)),
1261                )),
1262            });
1263            let (lanes, cell_ends) = match lanes {
1264                Ok(pair) => {
1265                    // Every host request a kernel makes is counted; `rlm.pool`, inspected or asked by a cell, carries
1266                    // the session's guard statistics.
1267                    let calls = stats.clone();
1268                    pair.0
1269                        .observe_requests(Arc::new(move |kind: &str| calls.host_call(kind)));
1270                    let guards_of = me.clone();
1271                    pair.0.extend_pool_stats(Arc::new(move |pool: &mut Value| {
1272                        if let Some(stack) = guards_of.upgrade() {
1273                            let guards = stack.guard_stats();
1274                            if !guards.is_empty() {
1275                                pool["guards"] = Value::Array(guards);
1276                            }
1277                        }
1278                    }));
1279                    pair
1280                }
1281                Err(error) => {
1282                    built = Err(error);
1283                    let (lanes, ends) = Lanes::new(LanesOptions {
1284                        create: Arc::new(|_| Err("no lanes".into())),
1285                        handlers: Arc::new(|_, _, _| Arc::new(Closed) as Arc<dyn HostHandler>),
1286                        max_lanes: 1,
1287                        cancel_grace: Duration::ZERO,
1288                        pool: None,
1289                    })
1290                    .expect("one lane is a valid limit");
1291                    (lanes, ends)
1292                }
1293            };
1294            let events = Arc::new(RuntimeEvents::new(
1295                (task_ends, child_ends, cell_ends),
1296                config.async_events,
1297                session_mask(&config),
1298            ));
1299            Stack {
1300                config,
1301                mcp: gateway,
1302                host,
1303                delegation,
1304                apis,
1305                model,
1306                root_model,
1307                keys,
1308                frame_stream,
1309                session_id,
1310                sessions_dir,
1311                system,
1312                services,
1313                lanes,
1314                workspaces: Mutex::new(HashMap::new()),
1315                kernel_sandbox: std::sync::OnceLock::new(),
1316                events,
1317                cell_progress: Arc::new(Mutex::new(None)),
1318                agents,
1319                usage,
1320                frames,
1321                schedules,
1322                goal,
1323                work: std::sync::OnceLock::new(),
1324                cell_hints,
1325                context: std::sync::OnceLock::new(),
1326                images,
1327                swarm: std::sync::OnceLock::new(),
1328                budget_note: Arc::new(std::sync::OnceLock::new()),
1329                request_layer: Arc::new(std::sync::OnceLock::new()),
1330                context_reminders,
1331                lane_steer: Arc::new(std::sync::OnceLock::new()),
1332                stats,
1333                judge_rows,
1334                retired_guards: Mutex::new(Vec::new()),
1335                wake,
1336                memory_children: memory_children_on,
1337                ledger,
1338            }
1339        });
1340        built?;
1341        if let Some(children) = memory_children {
1342            children.attach_reminders(stack.context_reminders.clone());
1343            let _ = stack
1344                .lane_steer
1345                .set(Arc::new(move |lane: &str, message: &str| children.steer(lane, message)));
1346        }
1347        stack.lanes.open(session_journal::run::MAIN_LANE)?;
1348        let work = DurableWork::open(
1349            DurableWorkOptions::new(Arc::new(stack.agents.clone()))
1350                .schedules(stack.schedules.clone())
1351                .goal(stack.goal.clone())
1352                .jobs(stack.host.clone()),
1353        )?;
1354        let _ = stack.work.set(work);
1355        Ok(stack)
1356    }
1357
1358    /// The file hooks of a host in `cwd`: Loki's (see [`Config::file_hooks_in`]), with `observers` told each cell's
1359    /// changes.
1360    fn file_hooks_in(
1361        &self,
1362        cwd: &Path,
1363        stats: Option<&Arc<SessionStats>>,
1364        observers: Vec<Arc<dyn host::file_hooks::CellObserver>>,
1365    ) -> FileHooks {
1366        let record = stats.map(|stats| {
1367            let stats = stats.clone();
1368            Arc::new(move |record: &GuardRecord| {
1369                stats.guard(&GuardOutcome {
1370                    guard: &record.guard,
1371                    phase: record.phase,
1372                    outcome: record.outcome,
1373                    ms: record.ms as f64,
1374                });
1375            }) as OnRecord
1376        });
1377        let hooks = self.config.file_hooks_in(cwd, record);
1378        for observer in observers {
1379            hooks.observe(observer);
1380        }
1381        hooks
1382    }
1383
1384    /// The session's situational skills (crate::situational_skills): the settings' rules over the session's skills,
1385    /// while engineering mode is on.
1386    fn situational_skills(&self) -> Option<Arc<dyn host::file_hooks::CellObserver>> {
1387        let config = self.config.clone();
1388        let (extra, no_skills) = (self.services.resources.clone(), self.services.session.no_skills);
1389        let resolve = move |name: &str| {
1390            let cwd = config.cwd.display().to_string();
1391            let agent_dir = config.agent_dir.display().to_string();
1392            let bundled = config.bundled_skills();
1393            let skill = crate::session_resources::skills(&cwd, &agent_dir, &extra, no_skills, bundled.as_deref())
1394                .into_iter()
1395                .find(|skill| skill.name == name)?;
1396            let raw = std::fs::read_to_string(&skill.file_path).ok()?;
1397            Some((skill.file_path, resources::frontmatter::strip(&raw).ok()?))
1398        };
1399        let (cwd, agent_dir, home) = (
1400            self.config.cwd.clone(),
1401            self.config.agent_dir.clone(),
1402            self.config.home.clone(),
1403        );
1404        let session_cwd = cwd.clone();
1405        let engineering = move || {
1406            config::settings::SettingsManager::for_worker(&cwd, &agent_dir, &home)
1407                .settings()
1408                .get("engineering")
1409                == Some(&Value::Bool(true))
1410        };
1411        crate::situational_skills::session_observer(
1412            &self.config.settings,
1413            &session_cwd,
1414            Box::new(resolve),
1415            Box::new(engineering),
1416        )
1417    }
1418
1419    /// The session's memory pointers: on while memory is (an injected backend or a Hindsight server) and the
1420    /// `memory.filePointers` setting is not false; scoped by the session's identity tags.
1421    fn memory_pointers(
1422        &self,
1423        session_id: &str,
1424        records: &Arc<kernel_apis::memory_records::RecordIndex>,
1425    ) -> Option<Arc<dyn host::file_hooks::CellObserver>> {
1426        let config = &self.config;
1427        let filters = match &self.services.memory {
1428            Some(backend) => backend.scope_tags(),
1429            None if self.memorantado.is_some() || self.hindsight.is_some() => kernel_apis::memory::worker_scope_tags(
1430                session_id,
1431                &config.cwd.display().to_string(),
1432                &config.home.display().to_string(),
1433            ),
1434            None => return None,
1435        };
1436        kernel_apis::memory_pointers::session_pointers(&config.settings, records.clone(), filters)
1437    }
1438
1439    /// A sandboxed host with its working directory at `cwd` (the session's, or a worktree subagent's); its guard
1440    /// outcomes are counted in `stats`.
1441    fn host_in(
1442        &self,
1443        cwd: &Path,
1444        session_id: &str,
1445        spill: &str,
1446        stats: Option<&Arc<SessionStats>>,
1447        observers: Vec<Arc<dyn host::file_hooks::CellObserver>>,
1448    ) -> Result<Host, String> {
1449        let config = &self.config;
1450        let jobs_dir = self.sessions_dir.join("rlm-jobs").join(session_id);
1451        // Blocking-bash spill files stay with the session (TS: the OS temp dir), so the sandbox keeps only
1452        // session paths writable.
1453        let spill_dir = config.session_dir("rlm-output", session_id).join(spill);
1454        let tmp_dir = config.session_dir("rlm-tmp", session_id);
1455        for dir in [&spill_dir, &tmp_dir] {
1456            std::fs::create_dir_all(dir).map_err(|e| format!("{}: {e}", dir.display()))?;
1457        }
1458        // `createLocalBashOperations({ shellPath: settingsManager.getShellPath() })`: the REPL's bash and its jobs.
1459        let shell_path = config
1460            .settings
1461            .as_object()
1462            .and_then(|settings| config::keys::shell_path(settings, &config.home));
1463        Ok(Host::new(
1464            cwd,
1465            jobs_dir,
1466            spill_dir,
1467            Box::new(self.file_hooks_in(cwd, stats, observers)),
1468        )
1469        .with_shell_path(shell_path)
1470        // The session's environment, never the server's: its PATH finds the shell, the sandbox and the tools.
1471        .with_base_env(config.child_env())
1472        // Cell results carry the diff of what they wrote (crate::cell_file_changes), except in the TS-compatible
1473        // output the TS-recorded replays compare (`ULTRON_GUIDE=ts`).
1474        .recording_cell_writes(!config.ts_guide)
1475        .sandboxed(&config.settings, &config.home, Some(&tmp_dir)))
1476    }
1477}
1478
1479/// The skill catalog `skills.*` serves: the session's skills with their file contents.
1480fn skill_sources(
1481    config: &Config,
1482    extra: &crate::session_resources::SessionResources,
1483    no_skills: bool,
1484) -> Vec<SkillSource> {
1485    let cwd = config.cwd.display().to_string();
1486    let agent_dir = config.agent_dir.display().to_string();
1487    let bundled = config.bundled_skills();
1488    crate::session_resources::skills(&cwd, &agent_dir, extra, no_skills, bundled.as_deref())
1489        .into_iter()
1490        .map(|skill| SkillSource {
1491            content: std::fs::read_to_string(&skill.file_path).unwrap_or_default(),
1492            name: skill.name,
1493            description: skill.description,
1494            file_path: skill.file_path,
1495            disable_model_invocation: skill.disable_model_invocation,
1496        })
1497        .collect()
1498}
1499
1500struct ApiModules {
1501    local: Arc<dyn kernel_apis::ApiModule>,
1502    gates: Arc<services::ReleaseGateModule>,
1503    skills: Arc<SkillsModule>,
1504    procedures: Arc<delegation::skill_runs::SkillRuns>,
1505    memory: Arc<MemoryApi>,
1506    hints: Arc<HintsModule>,
1507    images: Arc<kernel_apis::ImagesModule>,
1508    diagram: Arc<diagram::DiagramModule>,
1509    judge: Arc<judge::JudgeModule>,
1510    knowledge: Arc<graph::KnowledgeModule>,
1511    schedule: Arc<kernel_apis::prompt_schedule::ScheduleModule>,
1512    tools: Arc<kernel_apis::ToolCalls>,
1513    instances: Arc<kernel_apis::InstancesModule>,
1514    progress: Arc<kernel_apis::ProgressModule>,
1515    family: Arc<kernel_apis::FamilyModule>,
1516    sessions: Arc<kernel_apis::SessionsModule>,
1517}
1518
1519/// The session stores `sessions.*`, `/continue` and the dream's quiet check search: the session root itself, then the
1520/// profile's native and Pi-format stores, then every project instance's own store (`<home>/.ultron/projects/*/sessions`,
1521/// where a session started in a project is kept), in name order.
1522// ponytail: one directory listing per call; cache the project stores if `sessions.*` shows up in a profile.
1523pub fn store_roots(agent_dir: &Path, home: &Path, session_root: Option<&Path>) -> Vec<PathBuf> {
1524    let paths = config::paths::AgentPaths::new(agent_dir);
1525    let mut projects: Vec<PathBuf> =
1526        std::fs::read_dir(home.join(config::paths::AGENT_CONFIG_DIR_NAME).join("projects"))
1527            .map(|entries| entries.flatten().map(|entry| entry.path().join("sessions")).collect())
1528            .unwrap_or_default();
1529    projects.sort();
1530    let mut roots: Vec<PathBuf> = Vec::new();
1531    for root in session_root
1532        .map(Path::to_path_buf)
1533        .into_iter()
1534        .chain([paths.experimental_sessions_dir(), paths.sessions_dir()])
1535        .chain(projects)
1536    {
1537        if !roots.contains(&root) {
1538            roots.push(root);
1539        }
1540    }
1541    roots
1542}
1543
1544/// Where a session's `sessions.*` and `/continue` look for sessions: its own session root (the parent of the cwd's
1545/// `sessions_dir`), then the profile's native and Pi-format stores.
1546pub(crate) fn session_roots(config: &Config, sessions_dir: &Path) -> Vec<PathBuf> {
1547    store_roots(&config.agent_dir, &config.home, sessions_dir.parent())
1548}
1549
1550/// `sessions.*` of session `session_id`: its own session root (the parent of the cwd's `sessions_dir`) first, then
1551/// the profile's native and Pi-format stores.
1552fn session_search(config: &Config, sessions_dir: &Path, session_id: &str) -> kernel_apis::SessionsModule {
1553    kernel_apis::SessionsModule::new(
1554        session_roots(config, sessions_dir),
1555        session_id,
1556        &config.cwd.display().to_string(),
1557        kernel_apis::util::system_clock(),
1558    )
1559}
1560
1561/// A worktree subagent's lane: its working directory, extra environment and host.
1562struct Workspace {
1563    cwd: PathBuf,
1564    env: Vec<(String, String)>,
1565    host: Arc<Host>,
1566}
1567
1568/// A handler for a closed session.
1569struct Closed;
1570
1571impl HostHandler for Closed {
1572    fn handle(&self, kind: &str, _: Map<String, Value>, _: &Signal) -> Result<Value, String> {
1573        Err(format!("The session is closed ({kind})"))
1574    }
1575}
1576
1577/// One session's host stack: the sandboxed host, the REPL lanes, the subagent host and the kernel-API modules.
1578pub struct Stack {
1579    config: Arc<Config>,
1580    /// The session's MCP servers (closed with the session).
1581    mcp: Arc<mcp::gateway::Gateway>,
1582    pub host: Arc<Host>,
1583    pub delegation: Delegation,
1584    pub lanes: Lanes,
1585    pub events: Arc<RuntimeEvents>,
1586    apis: ApiModules,
1587    model: Model,
1588    /// The root lane's model now (a model switch changes it): frames and the predict adapter call it.
1589    root_model: Arc<Mutex<Model>>,
1590    /// The key of each request's provider (crate::request_keys).
1591    keys: crate::request_keys::Keys,
1592    /// What frames request through (crate::request_keys::lane_stream).
1593    frame_stream: Arc<dyn StreamFn>,
1594    session_id: String,
1595    sessions_dir: PathBuf,
1596    system: SystemPrompt,
1597    services: Services,
1598    workspaces: Mutex<HashMap<String, Workspace>>,
1599    /// The root lane kernels' sandbox, once built.
1600    kernel_sandbox: std::sync::OnceLock<Option<Arc<sandbox::Launcher>>>,
1601    /// The durable progress of the root lane's running cell: what its shell operations print is its partial
1602    /// output, kept if the worker dies before the cell ends.
1603    pub cell_progress: Arc<Mutex<Option<harness::chat::CellProgress>>>,
1604    /// The typed-agent host (`agents.*`, `background.*`, `workflows.run`) and its usage ledger.
1605    pub agents: Agents,
1606    pub usage: UsageLedger,
1607    /// The session's bounded-inference frames (`rlm.infer`, `rlm.map`, `rlm.frames`): budgets, traces, tasks.
1608    pub frames: Arc<inference::FrameSession>,
1609    /// `schedules.*` and the session goal (`goal.*`, `/goal`), on the root lane.
1610    pub schedules: Arc<SchedulesModule>,
1611    pub goal: Arc<GoalDriver>,
1612    /// Schedules, the goal and shell jobs as durable work: recovered when the stack opens, its tick running.
1613    pub work: std::sync::OnceLock<DurableWork>,
1614    /// Situational hints over every lane's cells (crate::lane::Rlm appends them).
1615    cell_hints: Arc<kernel_apis::cell_hints::CellHints>,
1616    /// Model-owned context of every lane (`ctx.*`; collapse on return on the root), once the session actor opened it.
1617    pub context: std::sync::OnceLock<Arc<kernel_apis::ContextControl>>,
1618    /// The images each lane's running cell attached with `view_image`, and the model each lane's results go to.
1619    pub images: Arc<crate::view_images::ViewImages>,
1620    /// `swarm.*`, `board.*`, `notes.*` and persistent children, once the session actor opened the durable runtime.
1621    pub swarm: std::sync::OnceLock<Arc<crate::swarm_ops::SwarmOps>>,
1622    /// The budget line every lane's cell results end with, once the session actor wired it (crate::budget_note).
1623    pub budget_note: Arc<std::sync::OnceLock<crate::budget_note::BudgetNote>>,
1624    /// A layer over every lane's host requests, set by a composition root whose root is not the session actor's
1625    /// (crate::request_layer); none: requests pass through.
1626    pub request_layer: Arc<std::sync::OnceLock<crate::request_layer::RequestLayer>>,
1627    /// The context-pressure reminder every lane's cell results may end with (crate::context_reminder): each lane's
1628    /// limit and, once the session actor wired it, the meter of its context use.
1629    pub context_reminders: Arc<crate::context_reminder::ContextReminders>,
1630    /// Steering into a child lane's running conversation (crate::agent_hub), once the session actor wired it.
1631    pub lane_steer: Arc<std::sync::OnceLock<crate::agent_hub::LaneSteer>>,
1632    /// The session's runtime counters (crate::session_stats), for `/usage`.
1633    pub stats: Arc<SessionStats>,
1634    /// Where `judge.decide` writes its usage rows: the session's values (see [`Stack::record_judge_rows_in`]).
1635    judge_rows: Arc<std::sync::OnceLock<services::SessionValues>>,
1636    /// The guard statistics of worktree subagent hosts whose runs ended (TypeScript has one set of file hooks for the
1637    /// whole session, so they stay in its totals).
1638    retired_guards: Mutex<Vec<Value>>,
1639    /// Whether the host wakes the root lane when its work ends (crate::wake): set by the composer that drives the
1640    /// root; every other lane waits in its cell.
1641    pub wake: crate::wake::RootWake,
1642    /// Subagents run as in-memory agent loops (crate::memory_children): no durable runtime behind their lanes.
1643    memory_children: bool,
1644    /// The session's refinements ledger (crate::auto_refine proposes into it and delivers from it).
1645    pub ledger: crate::auto_refine::Ledger,
1646}
1647
1648impl Stack {
1649    /// `judge.decide` records its calls as usage rows of `session`: for a composer whose modules keep no session
1650    /// values (an `ultron claude` server); a native session's go to its values already.
1651    pub fn record_judge_rows_in(&self, session: crate::durable_store::SharedSession) {
1652        let _ = self.judge_rows.set(services::SessionValues::shared(session));
1653    }
1654
1655    pub(crate) fn config(&self) -> &Arc<Config> {
1656        &self.config
1657    }
1658
1659    /// `memory.*`'s service, when memory is on (crate::auto_memory recalls and keeps through it).
1660    pub fn memory(&self) -> Option<&kernel_apis::MemoryService> {
1661        self.apis.memory.service.as_ref()
1662    }
1663
1664    /// `schedule.*`: the session's scheduled prompts (fired by the server through the session actor).
1665    pub fn prompt_schedules(&self) -> &Arc<kernel_apis::prompt_schedule::ScheduleModule> {
1666        &self.apis.schedule
1667    }
1668
1669    /// `poolStats()` as the worker answers an inspected `rlm.pool`: the lanes' kernel pool, plus the session's
1670    /// file-hook guard statistics (`guards`) when it has guards.
1671    pub fn pool_stats(&self) -> Value {
1672        self.lanes.pool_stats()
1673    }
1674
1675    /// `fileHooks.stats()` over the whole session: the session host's guards, with the same guards of every worktree
1676    /// subagent's host (live or ended) added in.
1677    pub fn guard_stats(&self) -> Vec<Value> {
1678        let mut totals = self.host.guard_stats();
1679        let others: Vec<Vec<Value>> = sync::lock(&self.workspaces)
1680            .values()
1681            .map(|w| w.host.guard_stats())
1682            .chain(std::iter::once(sync::lock(&self.retired_guards).clone()))
1683            .collect();
1684        for stats in others {
1685            add_guard_stats(&mut totals, &stats);
1686        }
1687        totals
1688    }
1689
1690    /// A new root turn began (`fileHooks.beginTurn()`): every host's per-turn guard times start from zero.
1691    pub fn begin_turn(&self) {
1692        self.host.begin_turn();
1693        for workspace in sync::lock(&self.workspaces).values() {
1694            workspace.host.begin_turn();
1695        }
1696        for retired in sync::lock(&self.retired_guards).iter_mut() {
1697            retired["turnMs"] = json!(0);
1698        }
1699    }
1700
1701    /// A worktree subagent's lane ended: its host goes (its shell jobs are the session's and keep running), its guard
1702    /// statistics stay in the session's.
1703    fn retire_workspace(&self, lane: &str) {
1704        let Some(workspace) = sync::lock(&self.workspaces).remove(lane) else {
1705            return;
1706        };
1707        add_guard_stats(&mut sync::lock(&self.retired_guards), &workspace.host.guard_stats());
1708    }
1709
1710    /// The host `lane` runs its shell in: a worktree subagent's own, else the session's.
1711    fn host_of(&self, lane: &str) -> Arc<Host> {
1712        sync::lock(&self.workspaces)
1713            .get(lane)
1714            .map_or_else(|| self.host.clone(), |w| w.host.clone())
1715    }
1716
1717    /// The handler `lane`'s requests go to (outermost layer first). `cell`: the cell's wait signal and park
1718    /// callback (subagent waits end with the cell); none for requests outside a cell.
1719    pub fn cell_handler(&self, lane: &str, cell: Option<(Signal, Park)>) -> Arc<dyn HostHandler> {
1720        let cell_signal = cell.as_ref().map(|(signal, _)| signal.clone());
1721        let delegation: Arc<dyn HostHandler> = match cell {
1722            Some((signal, park)) => Arc::new(self.delegation.cell_handler(lane, signal, park)),
1723            None => Arc::new(self.delegation.lane_handler(lane)),
1724        };
1725        let router = Router {
1726            delegation,
1727            host: self.host_of(lane),
1728            progress: (lane == session_journal::run::MAIN_LANE).then(|| self.cell_progress.clone()),
1729            lane: lane.to_string(),
1730            config: self.config.clone(),
1731            swarm: self.swarm.get().cloned(),
1732            cell: cell_signal.clone().map(CellShell::new),
1733        };
1734        // Frames are lanes of the session as TypeScript's are: on the root lane's model now, with the live request
1735        // settings, each request's key resolved when it is sent, and the harness retry policy. They run on their
1736        // handler threads' own runtimes, so they get their own HTTP client.
1737        let models = crate::frame_models::resolver(self.config.clone());
1738        let inference = Inference::new(
1739            Arc::new(router),
1740            self.root_model(),
1741            None,
1742            Arc::new(crate::lane::process_transport()),
1743            self.sessions_dir.join("rlm-context").join(&self.session_id),
1744        )
1745        .with_stream(self.frame_stream.clone())
1746        // A frame naming another model calls it as a lane of that model would (crate::frame_models); its key is
1747        // resolved per request like the session model's.
1748        .with_models(Arc::new(move |spec: &str| models(spec).map(|(model, _)| (model, None))))
1749        .with_session(self.frames.clone(), lane);
1750        // `rlm.map` and the frame-model defaults wrap the frames.
1751        // Read per frame (session-worker.ts `modelSettings`): `/settings -> Models` applies to the next frame.
1752        let settings = self.config.settings_reader();
1753        let models = move || {
1754            let settings = settings();
1755            let rlm = config::keys::rlm_model_settings(settings.global_settings());
1756            inference::ModelSettings {
1757                frame_model: rlm.frame_model,
1758                frame_thinking: rlm.frame_thinking,
1759                child_model: rlm.child_model,
1760                review_model: config::keys::review_model(settings.global_settings()),
1761                map_tokens: rlm.map_tokens,
1762            }
1763        };
1764        let frames = inference::Frames::new(inference, self.config.frame_env.clone(), models);
1765        // Frames end with their cell: an aborted root turn cancels every in-flight frame at once.
1766        let frames: Arc<dyn HostHandler> = match cell_signal {
1767            Some(cell) => Arc::new(FramesOfCell {
1768                inner: Arc::new(frames),
1769                cell,
1770            }),
1771            None => Arc::new(frames),
1772        };
1773        // Typed agents answer their requests (and their own lanes' `rlm.finish`) outside the delegation router.
1774        let typed: Arc<dyn HostHandler> = Arc::new(self.agents.handler(lane, frames));
1775        // `schedules.*` and `goal.*` from every lane, as session-worker.ts registers them: the goal module itself
1776        // refuses lanes other than the root and the goal's job.
1777        let mut apis = KernelApis::new(typed)
1778            .with_host(Arc::new(self.agents.clone()), lane)
1779            .with(self.schedules.clone() as Arc<dyn kernel_apis::ApiModule>)
1780            .with(self.goal.clone() as Arc<dyn kernel_apis::ApiModule>);
1781        if let Some(context) = self.context.get() {
1782            apis = apis.with(context.clone() as Arc<dyn kernel_apis::ApiModule>);
1783        }
1784        let apis = apis
1785            .with(self.apis.skills.clone())
1786            .with(self.apis.procedures.clone())
1787            .with(self.apis.memory.clone())
1788            .with(self.apis.hints.clone())
1789            .with(self.apis.images.clone())
1790            .with(self.apis.diagram.clone())
1791            .with(self.apis.judge.clone())
1792            .with(self.apis.knowledge.clone())
1793            .with(self.apis.schedule.clone())
1794            .with(self.apis.tools.clone())
1795            .with(self.apis.local.clone())
1796            .with(self.apis.gates.clone())
1797            .with(self.apis.instances.clone())
1798            .with(self.apis.progress.clone())
1799            .with(self.apis.sessions.clone())
1800            .with(Arc::new(crate::agent_hub::Family::new(
1801                self.apis.family.clone(),
1802                self.delegation.clone(),
1803                self.lane_steer.clone(),
1804            )) as Arc<dyn kernel_apis::ApiModule>);
1805        let observed: Arc<dyn HostHandler> = if self.cell_hints.active() {
1806            Arc::new(ObservedByHints {
1807                inner: Arc::new(apis),
1808                hints: self.cell_hints.clone(),
1809                lane: lane.to_string(),
1810            })
1811        } else {
1812            Arc::new(apis)
1813        };
1814        // `view_image` is the cell's own (`executeCell`), outside what the hints observe.
1815        let viewed: Arc<dyn HostHandler> = Arc::new(crate::view_images::ViewImageLayer {
1816            inner: observed,
1817            images: self.images.clone(),
1818            lane: lane.to_string(),
1819        });
1820        // The composition root's layer, if it set one (crate::request_layer), sees every request first.
1821        Arc::new(crate::request_layer::Layered {
1822            inner: viewed,
1823            layer: self.request_layer.clone(),
1824            lane: lane.to_string(),
1825        })
1826    }
1827
1828    /// `lane`'s kernel (not started): in the lane's working directory, inside the shell sandbox, with its snapshot
1829    /// under the profile and the continuity policy.
1830    fn kernel(&self, lane: &str) -> Result<Kernel, String> {
1831        let config = &self.config;
1832        let (cwd, extra) = match sync::lock(&self.workspaces).get(lane) {
1833            Some(workspace) => (workspace.cwd.clone(), workspace.env.clone()),
1834            None => (config.cwd.clone(), Vec::new()),
1835        };
1836        let spill_dir = config.session_dir("rlm-output", &self.session_id).join(lane_dir(lane));
1837        let mut options = KernelOptions::new(&cwd, &config.runtime_path);
1838        // The kernel starts from the session's environment (its PATH, its ULTRON_* settings), never the server's.
1839        options.base_env = Some(config.child_env());
1840        options.env = vec![
1841            (
1842                kernel::env::CODE_SKILLS_DIR_ENV.into(),
1843                config.skills_dir.display().to_string(),
1844            ),
1845            (kernel::env::RLM_SPILL_DIR_ENV.into(), spill_dir.display().to_string()),
1846            // The kernel's write skills ask the host's file hooks (Loki, the sandbox's containment) first.
1847            (kernel::env::FILE_HOOKS_ENV.into(), "1".into()),
1848            // What a running cell prints reaches the host as it is written (`cell.output`): its partial output.
1849            (kernel::env::RLM_STREAM_OUTPUT_ENV.into(), "1".into()),
1850            ("HOME".into(), config.home.display().to_string()),
1851        ];
1852        options.env.extend(extra);
1853        let snapshots = config.session_dir("rlm-snapshots", &self.session_id);
1854        std::fs::DirBuilder::new()
1855            .recursive(true)
1856            .create(&snapshots)
1857            .map_err(|e| format!("{}: {e}", snapshots.display()))?;
1858        options.snapshot_path = Some(snapshots.join(format!("{}.snapshot", lane_dir(lane))));
1859        options.snapshot_key = config.snapshot_key.clone();
1860        options.continuity = Some(ContinuityPolicy::default());
1861        // The Python process itself runs inside the session's shell sandbox, so direct writes are contained too.
1862        options.sandbox = self.kernel_launcher(lane)?;
1863        // The whole process tree is capped (ULTRON_RLM_MAX_TREE_MEMORY_MB, default twice the per-process limit) by the
1864        // host watchdog; ULTRON_RLM_TREE_MEMORY_BACKEND=auto|cgroup opts into a systemd scope where one is available.
1865        options.tree_memory = Some(kernel::TreeMemoryOptions {
1866            backend: Some(
1867                (config.var)(kernel::env::RLM_TREE_MEMORY_BACKEND_ENV)
1868                    .filter(|value| !value.trim().is_empty())
1869                    .unwrap_or_else(|| "watchdog".into()),
1870            ),
1871            ..kernel::TreeMemoryOptions::default()
1872        });
1873        Kernel::new(options, self.cell_handler(lane, None)).map_err(|e| e.to_string())
1874    }
1875
1876    /// The sandbox a lane's kernel runs in: its host's shell policy plus the inference context directory, which
1877    /// `rlm.load` writes from inside the kernel (the kernel adds its snapshot and spill paths itself). The root
1878    /// lane's is built once.
1879    fn kernel_launcher(&self, lane: &str) -> Result<Option<Arc<sandbox::Launcher>>, String> {
1880        let host = self.host_of(lane);
1881        let workspace = sync::lock(&self.workspaces).contains_key(lane);
1882        if !workspace && let Some(launcher) = self.kernel_sandbox.get() {
1883            return Ok(launcher.clone());
1884        }
1885        let context = self.sessions_dir.join("rlm-context").join(&self.session_id);
1886        std::fs::create_dir_all(&context).map_err(|e| format!("{}: {e}", context.display()))?;
1887        let launcher = host.launcher().map(|launcher| {
1888            let mut policy = launcher.policy.clone();
1889            policy.writable.push(std::fs::canonicalize(&context).unwrap_or(context));
1890            Arc::new(sandbox::Launcher::new(launcher.mode, policy))
1891        });
1892        if !workspace {
1893            let _ = self.kernel_sandbox.set(launcher.clone());
1894        }
1895        Ok(launcher)
1896    }
1897
1898    /// The `rlm` tool over `lane` (opened when needed).
1899    pub fn rlm(&self, lane: &str) -> Result<Rlm, String> {
1900        self.lanes.open(lane)?;
1901        let spill_dir = self
1902            .config
1903            .session_dir("rlm-output", &self.session_id)
1904            .join(lane_dir(lane));
1905        let hints = self.cell_hints.active().then(|| self.cell_hints.clone());
1906        Ok(rlm_over(
1907            &self.config,
1908            self.lanes.clone(),
1909            lane,
1910            spill_dir,
1911            hints,
1912            self.images.clone(),
1913            Some(self.host_of(lane)),
1914        )
1915        .with_budget_note(self.budget_note.clone())
1916        .with_stats(self.stats.clone())
1917        .with_context_reminders(self.context_reminders.clone())
1918        .with_wake(self.wake.clone()))
1919    }
1920
1921    /// `listCommands`: `/mcp`, `/review`, prompt templates and skills (crate::commands).
1922    pub fn commands(&self) -> Vec<Value> {
1923        let bundled = self.config.bundled_skills();
1924        let commands = crate::commands::list_commands_with(
1925            &self.config.cwd.display().to_string(),
1926            &self.config.agent_dir.display().to_string(),
1927            bundled.as_deref(),
1928            &self.services.resources,
1929        );
1930        crate::session_flags::filter_commands(commands, &self.services.session)
1931    }
1932
1933    /// The session's prompt templates, the ones [`Stack::commands`] lists as `/name` commands.
1934    pub fn prompt_templates(&self) -> Vec<resources::prompt_templates::PromptTemplate> {
1935        crate::session_resources::prompts(
1936            &self.config.cwd.display().to_string(),
1937            &self.config.agent_dir.display().to_string(),
1938            &self.services.resources,
1939        )
1940    }
1941
1942    /// The model the session's lanes run on unless told otherwise.
1943    pub fn model(&self) -> &Model {
1944        &self.model
1945    }
1946
1947    pub fn root_model(&self) -> Model {
1948        sync::lock(&self.root_model).clone()
1949    }
1950
1951    /// The root lane switched to `model` (`set_model`, `cycle_model`): frames, the predict adapter and the root's
1952    /// `view_image` follow it.
1953    pub fn set_root_model(&self, model: &Model) {
1954        *sync::lock(&self.root_model) = model.clone();
1955        self.system.set_model(&model.id);
1956        self.images.set_model(None, model.clone());
1957    }
1958
1959    /// The key of each request's provider, resolved when it is sent.
1960    pub fn keys(&self) -> &crate::request_keys::Keys {
1961        &self.keys
1962    }
1963
1964    /// The root lane's system prompt, in the settings' current mode.
1965    pub fn system(&self) -> String {
1966        self.system.current()
1967    }
1968
1969    /// The system prompt of a subagent lane on `model` (crate::wake: its runtime guide says to await before
1970    /// replying; crate::memory_guidance: a model cheaper than the root's is told how to use memory too).
1971    pub fn child_system(&self, model: &Model) -> String {
1972        self.system.child_current(
1973            ChildReader {
1974                in_memory: self.memory_children,
1975                memory: crate::memory_guidance::memory_guidance(model, &self.root_model(), true),
1976            },
1977            &model.id,
1978        )
1979    }
1980
1981    /// As [`Stack::close`], for a worker whose session a successor worker takes over: running shell jobs keep
1982    /// running, journaled as running, for the successor to follow (`DurableWork::hand_over`), and subagents are not
1983    /// cancelled: their tasks stay unfinished in the journal, so the successor reattaches them as after a crash.
1984    pub fn hand_over(&self) {
1985        if let Some(work) = self.work.get() {
1986            work.hand_over();
1987        }
1988        // Tool calls run in this worker's MCP connections: they end with it (a successor reads them as interrupted).
1989        self.apis.tools.close();
1990        self.mcp.close();
1991        self.lanes.close();
1992        self.stats.close();
1993    }
1994
1995    /// Stop the session's lanes and subagents, and its durable work (the tick, goal jobs, shell jobs).
1996    pub fn close(&self) {
1997        if let Some(work) = self.work.get() {
1998            work.close();
1999        }
2000        self.apis.tools.close();
2001        self.mcp.close();
2002        self.agents.close();
2003        self.delegation.close();
2004        self.lanes.close();
2005        // What the closing lanes counted is saved; nothing is counted after.
2006        self.stats.close();
2007    }
2008
2009    /// The session's situational hints (`ULTRON_HINTS`).
2010    pub fn cell_hints(&self) -> &Arc<kernel_apis::cell_hints::CellHints> {
2011        &self.cell_hints
2012    }
2013
2014    /// The session's MCP gateway (`/mcp`, and the REPL's `mcp` namespace through `tools.*`).
2015    pub fn mcp(&self) -> &Arc<mcp::gateway::Gateway> {
2016        &self.mcp
2017    }
2018
2019    /// The session's REPL tool calls (`tools.*`).
2020    pub fn tool_calls(&self) -> &Arc<kernel_apis::ToolCalls> {
2021        &self.apis.tools
2022    }
2023
2024    /// The session's masking of text that reaches the model (see [`session_mask`]).
2025    pub fn mask(&self) -> crate::async_events::MaskText {
2026        session_mask(&self.config)
2027    }
2028}
2029
2030/// How a session's subagents run, and where their task journal lives.
2031pub struct SubagentHost {
2032    pub store: Box<dyn kernel::store::DocumentStore>,
2033    /// Builds the runner from the stack being built (it may hold the stack weakly).
2034    pub runner: Box<dyn FnOnce(Weak<Stack>) -> delegation::host::ChildRunner>,
2035    /// The typed agents' task journal, definition registry and usage ledger stores, and the runner of their `rlm`
2036    /// lanes (none: in memory, and no `rlm` strategy).
2037    pub agents: Option<AgentStores>,
2038}
2039
2040/// Where the typed-agent host keeps its records, and how its `rlm` lanes run.
2041pub struct AgentStores {
2042    pub tasks: Box<dyn kernel::store::DocumentStore>,
2043    pub definitions: Box<dyn kernel::store::DocumentStore>,
2044    pub usage: Box<dyn kernel::store::DocumentStore>,
2045    pub lanes: Box<dyn FnOnce(Weak<Stack>) -> delegation::agents::LaneRunner>,
2046    /// Where frame traces are kept (`ultron.rlm.frames`).
2047    pub frames: Arc<dyn inference::TraceStore>,
2048}
2049
2050/// The typed-agent host of a session: its journal, definitions and usage ledger in `stores` (in memory without),
2051/// the predict adapter over the session's model, `rlm` lanes as `stores` runs them, root turns charged to roots
2052/// of their own. Returns the host, its ledger and its task-end channel.
2053#[allow(clippy::too_many_arguments)]
2054fn typed_agents(
2055    config: &Config,
2056    stores: Option<AgentStores>,
2057    stack: Weak<Stack>,
2058    root_model: Arc<Mutex<Model>>,
2059    keys: crate::request_keys::Keys,
2060    goal: Arc<std::sync::OnceLock<Arc<GoalDriver>>>,
2061    refinements: Option<delegation::agents::RefinementsHook>,
2062    frames: delegation::agents::FrameRunner,
2063    stats: &Arc<SessionStats>,
2064) -> (Agents, UsageLedger, Receiver<delegation::agents::TaskEnd>) {
2065    let (tasks, definitions, usage_store, lanes) = match stores {
2066        Some(stores) => (
2067            stores.tasks,
2068            stores.definitions,
2069            stores.usage,
2070            Some(hinted_lanes((stores.lanes)(stack.clone()), {
2071                let stack = stack.clone();
2072                Arc::new(move |lane: &str| {
2073                    if let Some(stack) = stack.upgrade() {
2074                        stack.cell_hints.run_ended(lane);
2075                    }
2076                })
2077            })),
2078        ),
2079        None => (
2080            Box::new(MemoryDocumentStore::default()) as Box<dyn kernel::store::DocumentStore>,
2081            Box::new(MemoryDocumentStore::default()) as Box<dyn kernel::store::DocumentStore>,
2082            Box::new(MemoryDocumentStore::default()) as Box<dyn kernel::store::DocumentStore>,
2083            None,
2084        ),
2085    };
2086    // `nativeUsageLimitsFromEnv(process.env, settingsManager.getRootBudgetSettings())`: the session's environment
2087    // and the `rootBudget` settings, whose token cap is off unless set.
2088    let var = config.var.clone();
2089    let root_budget = delegation::usage::root_budget_settings(&config.settings["rootBudget"]);
2090    let limits = delegation::usage::limits_from_env(&|key| var(key), &root_budget);
2091    // Work refused at a root's limit is counted (`onRefused: () => sessionStats.usageLimitBlock()`).
2092    let refused = stats.clone();
2093    let usage = UsageLedger::new(
2094        usage_store,
2095        delegation::usage::UsageOptions {
2096            limits,
2097            on_refused: Some(Arc::new(move |_: &str| refused.usage_limit_block())),
2098            // With the token cap off by default, the turn counts are still kept, as TypeScript's capped ledger does.
2099            keep_turns: true,
2100            ..Default::default()
2101        },
2102    )
2103    .unwrap_or_else(|_| {
2104        UsageLedger::new(Box::new(MemoryDocumentStore::default()), Default::default()).expect("an empty ledger opens")
2105    });
2106    let mut options = AgentsOptions::new(tasks);
2107    options.definition_store = Some(definitions);
2108    options.usage = Some(usage.clone());
2109    options.lanes = lanes;
2110    options.frames = Some(frames);
2111    options.root_turns = true;
2112    options.refinements = refinements;
2113    options.pricing = Some(crate::budget_pricing::pricing(config, root_model.clone()));
2114    // The session goal follows its runs' ends; the root's context control attributes each root-level task's
2115    // result to the cell that returns it (collapse on return).
2116    let context_stack = stack.clone();
2117    options.on_task_end = Some(Arc::new(move |task: &Value, cost, _| {
2118        if let (Some(goal), Some(id)) = (goal.get(), task["id"].as_str()) {
2119            let _ = goal.task_ended(id, task.get("result"));
2120        }
2121        if let Some(stack) = context_stack.upgrade()
2122            && let Some(context) = stack.context.get()
2123        {
2124            context.task_ended(task, cost);
2125        }
2126    }));
2127    // `createPredictAdapter({model: () => lane.getModel()})`: the root lane's model as of each call, its key
2128    // resolved then, over the process's HTTP stack at the idle timeout the settings name now.
2129    let settings = config.settings_reader();
2130    options.predict = Some(predict_adapter(Arc::new(move |call: PredictCall<'_>| {
2131        let model = sync::lock(&root_model).clone();
2132        let idle = ai::http::http_idle_timeout(settings().settings().get("httpIdleTimeoutMs"));
2133        let provider = crate::request_keys::Keyed {
2134            inner: Provider::with_idle_timeout(idle),
2135            keys: keys.clone(),
2136        };
2137        complete_once(&model, &provider, &call)
2138    })));
2139    // Retained instances pin their lanes' kernels in the session's pool.
2140    let (pin_stack, unpin_stack) = (stack.clone(), stack.clone());
2141    options.pin_lane = Some(Arc::new(move |lane: &str, holder: &str| {
2142        pin_stack.upgrade().is_some_and(|stack| stack.lanes.pin(lane, holder))
2143    }));
2144    options.unpin_lane = Some(Arc::new(move |lane: &str, holder: &str| {
2145        if let Some(stack) = unpin_stack.upgrade() {
2146            stack.lanes.unpin(lane, holder);
2147        }
2148    }));
2149    // `statusExtras`: the shell jobs and REPL tool calls `lane` may see, for `agents.status` and the TUI graph.
2150    let extras_stack = stack.clone();
2151    options.status_extras = Some(Arc::new(move |lane: &str| match extras_stack.upgrade() {
2152        Some(stack) => crate::agents::status_extras(&stack.host, stack.tool_calls(), lane),
2153        None => Map::new(),
2154    }));
2155    let reuse_stack = stack;
2156    options.before_lane_reuse = Some(Arc::new(move |lane: &str| {
2157        let stack = reuse_stack.upgrade().ok_or("The session is closed")?;
2158        match stack.lanes.kernel(lane) {
2159            Some(kernel) => kernel.reset_scratch().map(drop).map_err(|e| e.to_string()),
2160            None => Ok(()),
2161        }
2162    }));
2163    let (agents, ends) = Agents::new(options);
2164    (agents, usage, ends)
2165}
2166
2167/// A typed agent's `rlm` lane runner whose every run's end is reported to `ended` with its lane: the session's cell
2168/// hints start that lane's stuck-loop detection over (`cellHints.runEnded(lane)` on every lane's `run_end`), so a
2169/// retained instance's next run does not inherit the last one's failure streak.
2170pub fn hinted_lanes(
2171    runner: delegation::agents::LaneRunner,
2172    ended: Arc<dyn Fn(&str) + Send + Sync>,
2173) -> delegation::agents::LaneRunner {
2174    Arc::new(move |run: delegation::agents::LaneRun| {
2175        let lane = run.lane.clone();
2176        let result = runner(run);
2177        ended(&lane);
2178        result
2179    })
2180}
2181
2182/// One model completion without tools (`completeSimple`), for the predict adapter.
2183fn complete_once(model: &Model, provider: &dyn StreamFn, call: &PredictCall<'_>) -> Result<Completion, String> {
2184    let context = ai::TranscriptContext {
2185        messages: vec![
2186            Message::System(ai::SystemMessage {
2187                content: ai::SystemContent::Text(call.system.to_string()),
2188                sections: None,
2189                tools_added: None,
2190                tools_removed: None,
2191                timestamp: jsrt::date::now_ms(),
2192            }),
2193            Message::User(UserMessage {
2194                content: UserMessageContent::Text(call.user.clone()),
2195                timestamp: jsrt::date::now_ms(),
2196            }),
2197        ],
2198    };
2199    let abort = ai::AbortSignal::new();
2200    let mut options = ai::SimpleStreamOptions::default();
2201    options.base.signal = Some(abort.clone());
2202    let (signal, done) = (call.signal.clone(), Signal::new());
2203    let watched = done.clone();
2204    let watcher = std::thread::spawn(move || {
2205        while !watched.is_aborted() {
2206            if signal.wait(Duration::from_millis(200)) {
2207                abort.abort();
2208                return;
2209            }
2210        }
2211    });
2212    let mut sink = |_: &ai::AssistantMessageEvent| {};
2213    let runtime = tokio::runtime::Builder::new_current_thread()
2214        .enable_all()
2215        .build()
2216        .map_err(|e| e.to_string());
2217    let message = runtime.map(|runtime| runtime.block_on(provider.stream(model, &context, &options, &mut sink)));
2218    done.abort("done");
2219    let _ = watcher.join();
2220    let message = message?;
2221    let text = message
2222        .content
2223        .iter()
2224        .filter_map(|c| match c {
2225            ai::AssistantContent::Text(text) => Some(text.text.as_str()),
2226            _ => None,
2227        })
2228        .collect::<Vec<_>>()
2229        .join("");
2230    let stop = serde_json::to_value(message.stop_reason)
2231        .ok()
2232        .and_then(|v| v.as_str().map(str::to_string))
2233        .unwrap_or_default();
2234    Ok(Completion {
2235        text,
2236        stop_reason: stop,
2237        error_message: message.error_message,
2238    })
2239}
2240
2241/// What a subagent runs with: its model, its system prompt (naming its working directory) and thinking level.
2242pub struct ChildSetup {
2243    pub model: Model,
2244    pub system: String,
2245    pub thinking: String,
2246}
2247
2248/// A subagent's lane: in its worktree when it has one (its shell, kernel and prompt name that working directory, as
2249/// `session-worker.ts` rewrites it), on the session's model unless the spawn named one.
2250pub fn child_setup(stack: &Stack, run: &ChildRun) -> ChildSetup {
2251    let model = run
2252        .model
2253        .as_deref()
2254        .and_then(|spec| spec.split_once('/'))
2255        .and_then(|(provider, id)| stack.config.model(provider, id))
2256        .unwrap_or_else(|| stack.model.clone());
2257    let root_cwd = stack.config.cwd.display().to_string();
2258    // The subagent's own guide (crate::wake): nothing wakes it, so it awaits what its answer needs.
2259    let mut system = stack.child_system(&model);
2260    if let Some(cwd) = run.cwd.as_deref() {
2261        // A worktree subagent works in its worktree: its shell, kernel and prompt name it, not the checkout.
2262        let host = Runtime {
2263            config: stack.config.clone(),
2264            services: stack.services.clone(),
2265            diagnostics: Vec::new(),
2266            system: SystemPrompt::fixed(""),
2267            sessions_dir: stack.sessions_dir.clone(),
2268            mode: String::new(),
2269            hindsight: None,
2270            memorantado: None,
2271            memory_notice: None,
2272            memory_explicit: false,
2273        }
2274        .host_in(
2275            Path::new(cwd),
2276            &stack.session_id,
2277            &lane_dir(&run.lane_name),
2278            Some(&stack.stats),
2279            Vec::new(),
2280        );
2281        match host {
2282            Ok(host) => {
2283                // Its commands run with the worktree's environment (`withShellEnv(..., laneWorkspace(lane).env)`),
2284                // and its shell jobs are the session's (one `ShellJobs` for every lane).
2285                let host = host.with_env(run.env.clone()).sharing_jobs(&stack.host);
2286                sync::lock(&stack.workspaces).insert(
2287                    run.lane_name.clone(),
2288                    Workspace {
2289                        cwd: PathBuf::from(cwd),
2290                        env: run.env.clone(),
2291                        host: Arc::new(host),
2292                    },
2293                );
2294                system = system.split(&root_cwd).collect::<Vec<_>>().join(cwd);
2295            }
2296            Err(error) => system.push_str(&format!("\n\nThe worktree could not be prepared: {error}")),
2297        }
2298    }
2299    // A subagent's `view_image` resizes for its own model.
2300    stack.images.set_model(Some(&run.lane_name), model.clone());
2301    // Its context reminder: a child conversation compacts at the harness's default threshold.
2302    stack.context_reminders.set_limit(
2303        &run.lane_name,
2304        crate::context_reminder::lane_limit(&model, true, harness::chat::CompactionPolicy::default().reserve_tokens),
2305    );
2306    // The model each `rlm.spawn` subagent runs on is counted (`childModel`; a subagent run as a process has no lane
2307    // to ask).
2308    stack
2309        .stats
2310        .child_model(&run.task_id, &format!("{}/{}", model.provider, model.id));
2311    ChildSetup {
2312        model,
2313        system,
2314        thinking: run.thinking.clone().unwrap_or_else(|| "off".into()),
2315    }
2316}
2317
2318/// A subagent's agent (its lane per [`child_setup`]), the loop that runs it when it is not run durably.
2319fn child_agent(stack: &Weak<Stack>, defaults: &ChildDefaults, run: &ChildRun) -> (AgentOptions, Box<dyn StreamFn>) {
2320    let Some(stack) = stack.upgrade() else {
2321        // The session is closing: a loop without tools whose provider reports no work.
2322        let mut options = AgentOptions::new(defaults.model.clone());
2323        options.system_prompt = Some("The session ended before this subagent started.".into());
2324        let provider = crate::request_keys::Keyed {
2325            inner: Provider::new(),
2326            keys: defaults.keys.clone(),
2327        };
2328        return (options, Box::new(provider));
2329    };
2330    let setup = child_setup(&stack, run);
2331    let system = setup.system;
2332    let mut options = AgentOptions::new(setup.model);
2333    options.system_prompt = Some(system.clone());
2334    options.thinking_level = setup.thinking;
2335    match stack.rlm(&run.lane_name) {
2336        Ok(tool) => options.tools = vec![Arc::new(tool) as Arc<dyn AgentTool>],
2337        // The child's loop then runs without its REPL and reports the failure in its reply.
2338        Err(error) => options.system_prompt = Some(format!("{system}\n\nThe REPL failed to start: {error}")),
2339    }
2340    // Its requests carry the session's stream options as the root's do (one harness in TypeScript).
2341    // Each request carries its provider's key, resolved when it is sent.
2342    let provider = crate::request_keys::Keyed {
2343        inner: Provider::new().with_live_settings(stack.config.settings_reader()),
2344        keys: stack.keys.clone(),
2345    };
2346    (options, Box::new(provider))
2347}
2348
2349/// The model and keys a subagent falls back to.
2350struct ChildDefaults {
2351    model: Model,
2352    keys: crate::request_keys::Keys,
2353}
2354
2355/// Routes a cell's requests: subagents to the delegation host (as that lane), everything else to the host
2356/// operations. (The lane API — `rlm.lanes`, `rlm.lane.*`, `rlm.cells`,
2357/// `rlm.cell.cancel`, `rlm.recovery` — is answered by the lanes before a request gets here.)
2358struct Router {
2359    delegation: Arc<dyn HostHandler>,
2360    host: Arc<Host>,
2361    /// The root lane's cell progress (crate::turns): shell output is published as the cell's partial output.
2362    progress: Option<Arc<Mutex<Option<harness::chat::CellProgress>>>>,
2363    /// The lane the requests come from: its shell jobs are its own.
2364    lane: String,
2365    config: Arc<Config>,
2366    /// `swarm.*`, `board.*`, `notes.*`, `rlm.ask` and persistent children, once the durable runtime is open.
2367    swarm: Option<Arc<crate::swarm_ops::SwarmOps>>,
2368    /// The cell these requests come from (none outside a cell): cancelling it stops its shell commands.
2369    cell: Option<CellShell>,
2370}
2371
2372/// Why a cancelled cell's shell request failed: Python raises it, so the cell ends at once with its kernel (and the
2373/// lane's variables) intact.
2374pub const CELL_CANCELLED_SHELL: &str = "the cell was cancelled; its shell command was stopped";
2375
2376/// The shell work of one cell. Cancelling the cell (its wait signal aborts while the kernel still runs it) stops
2377/// its blocking `bash` at once and cancels the shell jobs it started; a cell that ends normally leaves its jobs
2378/// running (they outlive cells by design). The kernel aborts a cell's request signal before the lanes abort its
2379/// wait signal at a normal end, so a wait abort with the request signal live is a cancel.
2380#[derive(Clone)]
2381struct CellShell {
2382    waits: Signal,
2383    /// Jobs this cell started, and whether the cancel listener is armed.
2384    jobs: Arc<Mutex<(Vec<String>, bool)>>,
2385}
2386
2387impl CellShell {
2388    fn new(waits: Signal) -> CellShell {
2389        CellShell {
2390            waits,
2391            jobs: Arc::default(),
2392        }
2393    }
2394
2395    /// Whether the cell is being cancelled (as opposed to having ended): `request` is the cell's request signal.
2396    fn cancelled(&self, request: &Signal) -> bool {
2397        self.waits.is_aborted() && !request.is_aborted()
2398    }
2399
2400    /// Runs one shell request under a signal that aborts with the request or with the cell's cancel; a cancelled
2401    /// cell's request fails with [`CELL_CANCELLED_SHELL`]. Jobs it starts are recorded.
2402    fn run(
2403        &self,
2404        host: &Arc<Host>,
2405        lane: &str,
2406        kind: &str,
2407        payload: Map<String, Value>,
2408        request: &Signal,
2409    ) -> Result<Value, String> {
2410        if self.cancelled(request) {
2411            return Err(CELL_CANCELLED_SHELL.into());
2412        }
2413        let combined = Signal::new();
2414        let follow = |source: &Signal| {
2415            let target = combined.clone();
2416            source.link(move |reason| target.abort(reason))
2417        };
2418        let links = (follow(request), follow(&self.waits));
2419        let result = host.handle_lane(lane, kind, payload, &combined);
2420        drop(links);
2421        if let Ok(value) = &result {
2422            let job = match kind {
2423                "shell.run" => value["id"].as_str(),
2424                _ => value["job"]["id"].as_str(),
2425            };
2426            if let Some(job) = job.filter(|_| kind != "shell.cancel") {
2427                self.track(host, lane, job, request);
2428            }
2429        }
2430        if self.cancelled(request) {
2431            return Err(CELL_CANCELLED_SHELL.into());
2432        }
2433        result
2434    }
2435
2436    /// Records a job this cell started; the first one arms the cancel listener.
2437    fn track(&self, host: &Arc<Host>, lane: &str, job: &str, request: &Signal) {
2438        let mut jobs = sync::lock(&self.jobs);
2439        if !jobs.0.iter().any(|known| known == job) {
2440            jobs.0.push(job.to_string());
2441        }
2442        if jobs.1 {
2443            return;
2444        }
2445        jobs.1 = true;
2446        drop(jobs);
2447        let stop = {
2448            let (host, lane, request, list) = (host.clone(), lane.to_string(), request.clone(), self.jobs.clone());
2449            move |_reason: String| stop_cell_jobs(&host, &lane, &request, &list)
2450        };
2451        if self.waits.on_abort(stop).is_none() {
2452            // Already aborted: the listener was dropped, so stop now.
2453            stop_cell_jobs(host, lane, request, &self.jobs);
2454        }
2455    }
2456}
2457
2458impl HostHandler for Router {
2459    fn handle(&self, kind: &str, payload: Map<String, Value>, signal: &Signal) -> Result<Value, String> {
2460        // The worker answers this itself, before the host (session-worker.ts `hostHandler`).
2461        if kind == "rlm.find_models" {
2462            return Ok(self.config.find_models());
2463        }
2464        if kind == "rlm.race_models" {
2465            return Ok(self.config.race_models());
2466        }
2467        if let Some(swarm) = &self.swarm
2468            && let Some(result) = swarm.handle(&self.lane, kind, &payload, signal)
2469        {
2470            return result;
2471        }
2472        if kind == crate::turns::CELL_OUTPUT {
2473            if let Some(progress) = &self.progress {
2474                crate::turns::publish_output(
2475                    progress,
2476                    payload.get("text").and_then(Value::as_str).unwrap_or(""),
2477                    &session_mask(&self.config),
2478                );
2479            }
2480            return Ok(Value::Null);
2481        }
2482        if Delegation::serves(kind) {
2483            return self.delegation.handle(kind, payload, signal);
2484        }
2485        // runtime.py's `ext` (Pi extension functions): Pi extensions are not supported by ultron-rs.
2486        if kind == "ext.call" || kind == "ext.list" {
2487            return Err(EXTENSIONS_UNSUPPORTED.into());
2488        }
2489        let shell = matches!(kind, "bash" | "shell.run" | "shell.result");
2490        let result = match &self.cell {
2491            Some(cell) if shell => cell.run(&self.host, &self.lane, kind, payload, signal),
2492            _ => self.host.handle_lane(&self.lane, kind, payload, signal),
2493        };
2494        if shell
2495            && let (Some(progress), Ok(value)) = (&self.progress, &result)
2496            && let Some(output) = value["output"].as_str().filter(|o| !o.is_empty())
2497            && let Some(progress) = sync::lock(progress).as_ref()
2498        {
2499            // Masked, as the cell's result will be: the durable partial output reaches the transcript too.
2500            let output = session_mask(&self.config)(output);
2501            progress.output(
2502                if output.ends_with('\n') {
2503                    output
2504                } else {
2505                    format!("{output}\n")
2506                }
2507                .as_str(),
2508            );
2509        }
2510        result
2511    }
2512}
2513
2514/// Cancels the shell jobs a cancelled cell started (`shell.cancel`: the host stops each job's own process group).
2515/// Nothing when `request` is aborted: the cell ended (or its kernel failed) rather than being cancelled.
2516fn stop_cell_jobs(host: &Arc<Host>, lane: &str, request: &Signal, jobs: &Mutex<(Vec<String>, bool)>) {
2517    if request.is_aborted() {
2518        return;
2519    }
2520    let ids = std::mem::take(&mut sync::lock(jobs).0);
2521    for id in ids {
2522        let mut payload = Map::new();
2523        payload.insert("id".into(), Value::String(id));
2524        let _ = host.handle_lane(lane, "shell.cancel", payload, &Signal::new());
2525    }
2526}
2527
2528/// Every host request of a lane's kernel, observed for the situational hints (what a cell waited on, polled or
2529/// detached).
2530struct ObservedByHints {
2531    inner: Arc<dyn HostHandler>,
2532    hints: Arc<kernel_apis::cell_hints::CellHints>,
2533    lane: String,
2534}
2535
2536impl HostHandler for ObservedByHints {
2537    fn handle(&self, kind: &str, payload: Map<String, Value>, signal: &Signal) -> Result<Value, String> {
2538        let started = jsrt::date::now_ms();
2539        let observed = payload.clone();
2540        let result = self.inner.handle(kind, payload, signal);
2541        self.hints
2542            .observe(&self.lane, kind, &observed, result.as_ref().ok(), started);
2543        result
2544    }
2545}
2546
2547/// `rlm.infer` / `rlm.map` under a cell: the frames see an abort of the request or of the cell (the cell's host
2548/// waits end as soon as it is cancelled, before its kernel is interrupted).
2549struct FramesOfCell {
2550    inner: Arc<dyn HostHandler>,
2551    cell: Signal,
2552}
2553
2554impl HostHandler for FramesOfCell {
2555    fn handle(&self, kind: &str, payload: Map<String, Value>, signal: &Signal) -> Result<Value, String> {
2556        if kind != "rlm.infer" && kind != "rlm.map" {
2557            return self.inner.handle(kind, payload, signal);
2558        }
2559        let combined = Signal::new();
2560        let done = Signal::new();
2561        let (cell, request, abort, finished) = (self.cell.clone(), signal.clone(), combined.clone(), done.clone());
2562        let watcher = std::thread::spawn(move || {
2563            while !finished.wait(Duration::from_millis(20)) {
2564                for source in [&cell, &request] {
2565                    if source.is_aborted() {
2566                        abort.abort(source.reason().unwrap_or_else(|| "the cell was cancelled".into()));
2567                        return;
2568                    }
2569                }
2570            }
2571        });
2572        let result = self.inner.handle(kind, payload, &combined);
2573        done.abort("finished");
2574        let _ = watcher.join();
2575        result
2576    }
2577}
2578
2579/// The summary of a task's end event (`taskEvent` of session-worker.ts): the task's definition, then its verdict
2580/// tag (`[passed, verified]`, `[unverified]`, ...) when it has one, then its reply (a non-string value as JSON) or,
2581/// unless it succeeded, its error.
2582pub fn task_event_summary(task: &Value) -> String {
2583    let result = &task["result"];
2584    let detail = if result["status"] == "succeeded" {
2585        match &result["value"] {
2586            Value::String(text) => text.clone(),
2587            other => other.to_string(),
2588        }
2589    } else {
2590        result["error"].as_str().unwrap_or_default().to_string()
2591    };
2592    let tag = if result.is_object() {
2593        delegation::verdict::verdict_tag(result)
2594    } else {
2595        None
2596    };
2597    let definition = task["definition"].as_str().unwrap_or("undefined");
2598    match tag {
2599        Some(tag) => format!("{definition}: {tag} {detail}"),
2600        None => format!("{definition}: {detail}"),
2601    }
2602}
2603
2604/// The session's masking of text that reaches the model: values MCP servers resolved (`registerSecretValues`) and
2605/// the shipped rules, unless `ULTRON_MASK_SECRETS` turns it off.
2606pub fn session_mask(config: &Config) -> crate::async_events::MaskText {
2607    let (masker, flag) = (config.masker.clone(), config.mask_secrets.clone());
2608    Arc::new(move |text: &str| masker.mask_counted(text, flag.as_deref()).0)
2609}
2610
2611/// Completions of work a run started that outlives its cell: typed tasks nobody awaited (`task_done`), subagents
2612/// (`child_done`) and detached cells (`cell_done`), of every lane. Each completion continues its lane's run as a
2613/// `<runtime_event>` message. `ULTRON_ASYNC_EVENTS=off` turns this off: nothing waits and nothing is announced.
2614pub struct RuntimeEvents {
2615    ends: Arc<(Mutex<Vec<RuntimeEvent>>, Condvar)>,
2616    enabled: bool,
2617    mask: crate::async_events::MaskText,
2618}
2619
2620impl RuntimeEvents {
2621    /// Over the three hosts' end channels; each is read on a thread of its own until its host goes away.
2622    fn new(
2623        (task_ends, child_ends, cell_ends): (
2624            Receiver<delegation::agents::TaskEnd>,
2625            Receiver<DetachedEnd>,
2626            Receiver<CellEnd>,
2627        ),
2628        enabled: bool,
2629        mask: crate::async_events::MaskText,
2630    ) -> Self {
2631        let ends: Arc<(Mutex<Vec<RuntimeEvent>>, Condvar)> = Arc::default();
2632        fn read<T: Send + 'static>(
2633            from: Receiver<T>,
2634            into: &Arc<(Mutex<Vec<RuntimeEvent>>, Condvar)>,
2635            event: fn(T) -> Option<RuntimeEvent>,
2636        ) {
2637            let into = into.clone();
2638            std::thread::spawn(move || {
2639                for end in from {
2640                    if let Some(event) = event(end) {
2641                        sync::lock(&into.0).push(event);
2642                        into.1.notify_all();
2643                    }
2644                }
2645            });
2646        }
2647        read(task_ends, &ends, task_end_event);
2648        read(child_ends, &ends, |end| Some(child_end_event(end)));
2649        read(cell_ends, &ends, |end| Some(cell_end_event(end)));
2650        RuntimeEvents { ends, enabled, mask }
2651    }
2652
2653    /// Every completion that arrived, for the event dispatcher (crate::async_events), each for the lane that owns
2654    /// the work: waits up to `wait` for the first when none has. A subagent's or cell's root is left for the caller.
2655    pub fn recv(&self, wait: Duration) -> Vec<RuntimeEvent> {
2656        let ends = sync::lock(&self.ends.0);
2657        let (mut ends, _) = self
2658            .ends
2659            .1
2660            .wait_timeout_while(ends, wait, |ends| ends.is_empty())
2661            .unwrap_or_else(std::sync::PoisonError::into_inner);
2662        std::mem::take(&mut *ends)
2663    }
2664
2665    /// The `<runtime_event>` lines of the root lane's `events`.
2666    pub fn root_lines(&self, events: &[RuntimeEvent]) -> Vec<String> {
2667        events
2668            .iter()
2669            .filter(|e| e.lane == session_journal::run::MAIN_LANE)
2670            .map(|e| {
2671                crate::async_events::runtime_event_line(&e.kind, &e.id, &e.status, &e.summary, &e.fetch, &self.mask)
2672            })
2673            .collect()
2674    }
2675
2676    /// Whether events are on (`ULTRON_ASYNC_EVENTS`).
2677    pub fn enabled(&self) -> bool {
2678        self.enabled
2679    }
2680}
2681
2682/// A typed task's end nobody awaited (`task_done`, as session-worker.ts `onDetachedEnd`), with its root.
2683fn task_end_event(end: delegation::agents::TaskEnd) -> Option<RuntimeEvent> {
2684    if end.awaited {
2685        return None;
2686    }
2687    let task = &end.task;
2688    Some(RuntimeEvent {
2689        kind: end.kind.into(),
2690        id: task["id"].as_str().unwrap_or_default().into(),
2691        status: task_status(task).into(),
2692        summary: task_event_summary(task),
2693        fetch: end.fetch.clone(),
2694        lane: end.owner_lane.clone(),
2695        root_id: end.root_id.clone(),
2696    })
2697}
2698
2699/// A subagent's end (`child_done`).
2700fn child_end_event(end: DetachedEnd) -> RuntimeEvent {
2701    let task = &end.task;
2702    RuntimeEvent {
2703        kind: end.kind.into(),
2704        id: task["id"].as_str().unwrap_or_default().into(),
2705        status: task_status(task).into(),
2706        summary: task_event_summary(task),
2707        fetch: end.fetch.clone(),
2708        lane: end.owner_lane.clone(),
2709        root_id: None,
2710    }
2711}
2712
2713/// A detached cell's end (`cell_done`).
2714fn cell_end_event(end: CellEnd) -> RuntimeEvent {
2715    let (status, summary) = match &end.outcome {
2716        Ok(result) => (
2717            if result.status == kernel::Status::Ok {
2718                "completed"
2719            } else {
2720                "failed"
2721            },
2722            [result.stdout.as_str(), result.result.as_deref().unwrap_or_default()].join(" "),
2723        ),
2724        Err(error) => ("failed", error.clone()),
2725    };
2726    RuntimeEvent {
2727        kind: "cell_done".into(),
2728        id: end.cell,
2729        status: status.into(),
2730        summary,
2731        fetch: "await rlm.cells()".into(),
2732        lane: end.lane,
2733        root_id: None,
2734    }
2735}
2736
2737/// A task's status: its result's, else its state, else `ended`.
2738fn task_status(task: &Value) -> &str {
2739    task["result"]["status"]
2740        .as_str()
2741        .or(task["state"].as_str())
2742        .unwrap_or("ended")
2743}
2744
2745/// Whether a value lists exactly the `rlm` tool: the invariant every request body keeps.
2746pub fn only_rlm(tools: &[Value]) -> bool {
2747    tools.len() == 1 && tools[0]["name"] == json!("rlm")
2748}
2749
2750/// Add `more` (each guard's `fileHooks.stats()` entry) into `totals`: the same guard by position and name, a new one
2751/// appended.
2752fn add_guard_stats(totals: &mut Vec<Value>, more: &[Value]) {
2753    const COUNTERS: [&str; 7] = [
2754        "checks",
2755        "blocked",
2756        "unchecked",
2757        "afterChecks",
2758        "afterFindings",
2759        "totalMs",
2760        "turnMs",
2761    ];
2762    for (index, stats) in more.iter().enumerate() {
2763        match totals.get_mut(index).filter(|t| t["name"] == stats["name"]) {
2764            Some(total) => {
2765                for key in COUNTERS {
2766                    let sum = total[key].as_u64().unwrap_or(0) + stats[key].as_u64().unwrap_or(0);
2767                    total[key] = json!(sum);
2768                }
2769            }
2770            None => totals.push(stats.clone()),
2771        }
2772    }
2773}