Skip to main content

session_core/
lane.rs

1//! The root lane every prompted mode runs on (print mode, `--mode json`, `--mode rpc`): the model, its key and the
2//! native worker's system prompt (`session-worker.ts`), the single `rlm` tool whose cells run in a persistent kernel
3//! (crates/kernel) over the host stack the composition root builds ([`crate::compose`]), the provider call, and the
4//! clock lines (`ultron/clock-context.ts`) and REPL result footers a request carries.
5
6use crate::compose::{Config, Runtime, RuntimeEvents, Stack};
7use crate::{ModelFlags, RunEnv as Env};
8use agent::{AgentTool, AgentToolResult, StreamFn, ToolUpdate};
9use ai::http::{BoxFuture, ReqwestTransport};
10use ai::model_registry::ModelRegistry;
11use ai::{
12    AbortSignal, AssistantMessage, EventSink, Message, Model, SimpleStreamOptions, StopReason, TextContent, Tool,
13    TranscriptContext, Transport, UserContent, UserMessage, UserMessageContent,
14};
15use host::Host;
16use host::cell::{CellFormat, cell_output};
17use host::secrets::OutputMasker;
18use kernel::Kernel;
19use lanes::{CellOutcome, Lanes};
20use serde_json::{Value, json};
21use session_journal::run::MAIN_LANE;
22use std::future::Future;
23use std::path::{Path, PathBuf};
24use std::pin::pin;
25use std::sync::{Arc, Mutex};
26use std::task::Poll;
27use std::time::Duration;
28
29pub const CLOCK_CONTEXT_ENV: &str = "ULTRON_CLOCK_CONTEXT";
30
31/// `RLM_TOOL_DESCRIPTION` and `RLM_TOOL_SNIPPET` from ultron/rlm/prompt.ts.
32const RLM_DESCRIPTION: &str = "Run a Python cell in your persistent REPL: variables, imports and functions persist across calls, top-level `await` works, and the last expression's value is shown with anything printed (kept as `_`).\nPre-imported: `bash`, `read`, `edit`, `write`, `view_image`, `rlm`, `agents`, `workflows`, `background`, `tools`, `mcp`, `ctx`, `skills`, `memory`, `hints`, `agent`, `Budget`, `state`, `preview`, `asyncio`; `help(obj)` shows any API's docs.";
33const RLM_SNIPPET: &str = "Python REPL for files, shell (`bash`), edits (`edit`), data and subagents";
34
35/// What an aborted `rlm` cell reports (the harness's tool abort text).
36pub const ABORT_REQUESTED: &str = "Abort requested";
37
38/// The model's only tool. Every capability is a kernel API reached from a cell; nothing adds a second tool.
39pub fn rlm_tool() -> Tool {
40    Tool {
41        name: "rlm".into(),
42        description: RLM_DESCRIPTION.into(),
43        parameters: json!({
44            "type": "object",
45            "properties": {"code": {"type": "string", "description": "Python code for persistent RLM computation, typed agents, and data processing"}},
46            "required": ["code"],
47        }),
48        constrained_sampling: None,
49    }
50}
51
52use jsrt::date::now_ms;
53
54pub fn text_block(text: String) -> UserContent {
55    UserContent::Text(TextContent {
56        text,
57        text_signature: None,
58    })
59}
60
61/// `formatClock`: local time with its UTC offset, to the minute ("2026-10-05 14:03 UTC+02:00"), in `zone` (the
62/// session's `TZ`, else `/etc/localtime`).
63pub fn format_clock(ms: i64, zone: &jsrt::localtime::Zone) -> String {
64    let offset = zone.offset(ms as f64);
65    let local = jsrt::localtime::fields(ms as f64, offset);
66    let minutes = offset.div_euclid(60);
67    let sign = if minutes >= 0 { '+' } else { '-' };
68    format!(
69        "{}-{:02}-{:02} {:02}:{:02} UTC{sign}{:02}:{:02}",
70        local.year,
71        local.month,
72        local.day,
73        local.hour,
74        local.minute,
75        minutes.abs() / 60,
76        minutes.abs() % 60
77    )
78}
79
80/// `CLOCK_GAP_MS`: a user message this long after the one before it gets a clock line.
81pub const CLOCK_GAP_MS: i64 = 10 * 60 * 1000;
82
83/// `formatGap`: "12 min", "3 h", "2 d".
84pub fn format_gap(ms: i64) -> String {
85    let minutes = ms.div_euclid(60_000);
86    if minutes < 120 {
87        return format!("{minutes} min");
88    }
89    let hours = minutes / 60;
90    if hours < 48 {
91        format!("{hours} h")
92    } else {
93        format!("{} d", hours / 24)
94    }
95}
96
97/// The zone clock lines are in: the session's `TZ`, else `/etc/localtime` (`new Date(...)` of the TypeScript worker).
98pub fn clock_zone(env: &Env) -> jsrt::localtime::Zone {
99    jsrt::localtime::Zone::from_env((env.var)("TZ").as_deref())
100}
101
102/// `clockContextEnabled`: `ULTRON_CLOCK_CONTEXT=off|0|false` disables clock lines.
103pub fn clock_enabled(env: &Env) -> bool {
104    !env.flag_off(CLOCK_CONTEXT_ENV)
105}
106
107/// The clock lines of `withClockLines` as `(index, text, timestamp)`: one before each user message that opens the
108/// conversation or follows a gap of `CLOCK_GAP_MS` or more; `index` is the user message the line precedes.
109fn clock_texts(messages: &[Value], zone: &jsrt::localtime::Zone) -> Vec<(usize, String, i64)> {
110    let mut out = Vec::new();
111    let mut previous: Option<i64> = None;
112    for (index, message) in messages.iter().enumerate() {
113        let at = message
114            .get("timestamp")
115            .and_then(Value::as_f64)
116            .filter(|t| t.is_finite() && *t > 0.0)
117            .map(|t| t as i64);
118        if let Some(at) = at
119            && message.get("role").and_then(Value::as_str) == Some("user")
120            && !is_compaction_summary(message)
121            && previous.is_none_or(|p| at - p >= CLOCK_GAP_MS)
122        {
123            let gap = previous.map_or(String::new(), |p| {
124                format!(", {} after the previous message", format_gap(at - p))
125            });
126            out.push((index, format!("[clock] {}{gap}", format_clock(at, zone)), at));
127        }
128        if at.is_some() {
129            previous = at;
130        }
131    }
132    out
133}
134
135/// A durable conversation's compaction summary (a user message there; `compactionSummary` in TypeScript, which
136/// gets no clock line).
137fn is_compaction_summary(message: &Value) -> bool {
138    let text = match &message["content"] {
139        Value::String(text) => Some(text.as_str()),
140        Value::Array(blocks) => blocks.first().and_then(|block| block["text"].as_str()),
141        _ => None,
142    };
143    text.is_some_and(|text| text.starts_with(session_journal::context::COMPACTION_SUMMARY_PREFIX))
144}
145
146/// One clock line (a user message) per [`clock_texts`] entry, with the index of the message it precedes.
147pub fn clock_lines_in(messages: &[Value], zone: &jsrt::localtime::Zone) -> Vec<(usize, Message)> {
148    clock_texts(messages, zone)
149        .into_iter()
150        .map(|(index, text, at)| {
151            let line = Message::User(UserMessage {
152                content: UserMessageContent::Blocks(vec![text_block(text)]),
153                timestamp: at,
154            });
155            (index, line)
156        })
157        .collect()
158}
159
160/// `withClockLines`: the messages with their clock lines in place; `None` when no line was added. Lines are derived,
161/// never stored.
162pub fn with_clock_lines_in(messages: &[Value], zone: &jsrt::localtime::Zone) -> Option<Vec<Value>> {
163    let lines = clock_texts(messages, zone);
164    if lines.is_empty() {
165        return None;
166    }
167    let mut out = Vec::with_capacity(messages.len() + lines.len());
168    let mut pending = lines.into_iter().peekable();
169    for (index, message) in messages.iter().enumerate() {
170        if let Some((_, text, at)) = pending.next_if(|(i, _, _)| *i == index) {
171            out.push(json!({"role": "user", "content": [{"type": "text", "text": text}], "timestamp": at}));
172        }
173        out.push(message.clone());
174    }
175    Some(out)
176}
177
178/// `[t+12m04s ctx 41k]`: when a REPL result came back, counted from the session's start, and the context the request
179/// that made the call held (its input, cached and output tokens; left out when the provider reported none).
180pub fn result_footer(at_ms: i64, start_ms: i64, context_tokens: u64) -> String {
181    let seconds = (at_ms - start_ms).max(0) / 1000;
182    let (minutes, hours) = (seconds / 60, seconds / 3600);
183    let elapsed = if seconds < 60 {
184        format!("{seconds}s")
185    } else if minutes < 60 {
186        format!("{minutes}m{:02}s", seconds % 60)
187    } else if hours < 48 {
188        format!("{hours}h{:02}m", minutes % 60)
189    } else {
190        format!("{}d{}h", hours / 24, hours % 24)
191    };
192    if context_tokens == 0 {
193        return format!("[t+{elapsed}]");
194    }
195    let context = if context_tokens < 1000 {
196        context_tokens.to_string()
197    } else {
198        format!("{}k", (context_tokens + 500) / 1000)
199    };
200    format!("[t+{elapsed} ctx {context}]")
201}
202
203/// A footer ([`result_footer`]) after each tool result of a request (the `rlm.resultFooter` setting,
204/// crate::compose::Config::result_footer): derived from the stored messages (the result's
205/// timestamp, the usage of the response that made the call), never stored, so an earlier result's footer reads the
206/// same in every request and the prompt cache keeps it.
207pub fn add_result_footers(messages: &mut [Message], start_ms: i64) {
208    let mut context = 0;
209    for message in messages {
210        match message {
211            Message::Assistant(assistant) => {
212                let usage = &assistant.usage;
213                context = usage.input + usage.cache_read + usage.cache_write + usage.output;
214            }
215            Message::ToolResult(result) if result.timestamp > 0 => {
216                result
217                    .content
218                    .push(text_block(result_footer(result.timestamp, start_ms, context)));
219            }
220            _ => {}
221        }
222    }
223}
224
225/// Session messages as the model sees them (`convertToLlm`): custom roles become user messages, excluded bash runs
226/// are dropped.
227pub fn to_llm(messages: &[Value]) -> Vec<Message> {
228    session_journal::context::convert_to_llm(messages)
229        .into_iter()
230        .filter_map(|m| serde_json::from_value(m).ok())
231        .collect()
232}
233
234/// The native worker's system prompt for a lane whose only tool is `rlm`. `loki_root` is where Loki's policy is read
235/// (None: Loki is off, so no policy note).
236pub fn system_prompt(env: &Env, cwd: &str, loki_root: Option<&Path>) -> Result<String, String> {
237    system_prompt_with_guide(env, cwd, loki_root, &Default::default())
238}
239
240/// [`system_prompt`] whose runtime guide gets `guide` (the REPL's `mcp` tool and MCP servers), in the mode the
241/// global settings name ([`PromptMode`]).
242pub fn system_prompt_with_guide(
243    env: &Env,
244    cwd: &str,
245    loki_root: Option<&Path>,
246    guide: &resources::runtime_guide::RuntimeGuideOptions,
247) -> Result<String, String> {
248    let settings = config::settings::SettingsManager::for_worker(Path::new(cwd), &env.agent_dir(), &env.home);
249    let mode = PromptMode::from_settings(&settings);
250    system_prompt_in_mode(env, cwd, loki_root, guide, &mode).map(|(prompt, _)| prompt)
251}
252
253/// What the settings change about the system prompt. Engineering mode (the `engineering` setting, `/engineering`,
254/// `/mode`) puts the always-on skills (`alwaysSkills`) in the prompt; off, they are listed like any skill.
255#[derive(Clone, Debug, Default, PartialEq, Eq)]
256pub struct PromptMode {
257    pub engineering: bool,
258    pub always_skills: Vec<String>,
259    /// `--no-skills`: no skills listed (bundled ones included), none always on.
260    pub no_skills: bool,
261    /// `--no-context-files`: no AGENTS.md / CLAUDE.md.
262    pub no_context_files: bool,
263    /// `"persona": "ultron"`: `<agent dir>/personality.md` is a section of the prompt (resources::persona), read
264    /// when the prompt renders (session start, a change of the mode), never per request.
265    pub persona: bool,
266    /// The id of the model the prompt is for: its family's notes are a section (resources::model_notes) under the
267    /// Rust guide. Empty: none.
268    pub model: String,
269}
270
271impl PromptMode {
272    /// `getEngineering` and `getAlwaysSkills` (the string entries of `alwaysSkills`).
273    pub fn from_settings(settings: &config::settings::SettingsManager) -> PromptMode {
274        let settings = settings.settings();
275        PromptMode {
276            engineering: settings.get("engineering") == Some(&Value::Bool(true)),
277            always_skills: settings
278                .get("alwaysSkills")
279                .and_then(Value::as_array)
280                .map(|names| names.iter().filter_map(Value::as_str).map(str::to_string).collect())
281                .unwrap_or_default(),
282            persona: resources::persona::enabled(settings),
283            ..PromptMode::default()
284        }
285    }
286}
287
288/// [`system_prompt_with_guide`] in an explicit mode, with the `alwaysSkills` problems (a skill that is not loaded,
289/// cannot be read, or would pass the always-on size limit) as warnings.
290pub fn system_prompt_in_mode(
291    env: &Env,
292    cwd: &str,
293    loki_root: Option<&Path>,
294    guide: &resources::runtime_guide::RuntimeGuideOptions,
295    mode: &PromptMode,
296) -> Result<(String, Vec<String>), String> {
297    let resources = crate::session_resources::resolve_default(env);
298    system_prompt_with_resources(env, cwd, loki_root, guide, mode, &resources)
299}
300
301/// [`system_prompt_in_mode`] with the session's resources (crate::session_resources): their skills are listed
302/// (none with `--no-skills`), and SYSTEM.md / APPEND_SYSTEM.md shape the prompt.
303pub fn system_prompt_with_resources(
304    env: &Env,
305    cwd: &str,
306    loki_root: Option<&Path>,
307    guide: &resources::runtime_guide::RuntimeGuideOptions,
308    mode: &PromptMode,
309    extra: &crate::session_resources::SessionResources,
310) -> Result<(String, Vec<String>), String> {
311    use resources::system_prompt::{BuildOptions, build_system_prompt};
312    let agent_dir = env.agent_dir().display().to_string();
313    let bundled = crate::session_resources::bundled_skills(&env.skills(), &*env.var);
314    let mut skills = crate::session_resources::skills(cwd, &agent_dir, extra, mode.no_skills, bundled.as_deref());
315    let mut warnings = Vec::new();
316    if !mode.no_skills {
317        // Skills the user set always on carry their text into the prompt (resource-loader.ts `applyAlwaysSkills`).
318        warnings = resources::skills::apply_always_skills(&mut skills, &mode.always_skills)
319            .into_iter()
320            .map(|d| d.message)
321            .collect();
322    }
323    let persona = if mode.persona {
324        match resources::persona::read_personality(&env.agent_dir()) {
325            Ok(text) => text,
326            Err(warning) => {
327                warnings.push(warning);
328                None
329            }
330        }
331    } else {
332        None
333    };
334    let runtime = resources::runtime_guide::rlm_runtime_prompt(&["rlm"], guide).unwrap_or_default();
335    let loki_note = loki_root.and_then(loki::session_note);
336    let options = BuildOptions {
337        selected_tools: vec!["rlm".into()],
338        tool_snippets: vec![("rlm".into(), RLM_SNIPPET.into())],
339        tool_guidelines: vec![("rlm".into(), resources::runtime_guide::rlm_tool_guidelines(&["rlm"]))],
340        include_harness_docs: false,
341        context_files: if mode.no_context_files {
342            Vec::new()
343        } else {
344            resources::context_files::load_project_context_files(cwd, &agent_dir, &env.home.display().to_string())
345        },
346        skills,
347        bundled_skills_dir: bundled,
348        // SYSTEM.md replaces Pi's preamble, tools and rules; APPEND_SYSTEM.md is the addendum (`resourceLoader`).
349        custom_prompt: extra.system_prompt.clone(),
350        append_system_prompt: extra.append_system_prompt.join("\n\n"),
351        sections: [("runtime".to_string(), runtime)]
352            .into_iter()
353            .chain(loki_note.map(|note| ("loki".to_string(), note)))
354            // The TypeScript guide (`ULTRON_GUIDE=ts`, its recorded replays) keeps TypeScript's prompt.
355            .chain(
356                resources::model_notes::model_notes(&mode.model)
357                    .filter(|_| guide.durable_apis)
358                    .map(|notes| ("model_notes".to_string(), notes)),
359            )
360            .collect(),
361        engineering: mode.engineering,
362        persona,
363        // Engineering mode with the Rust guide: the bundled skills are used without being asked (the TypeScript
364        // guide keeps TypeScript's wording).
365        proactive_skills: mode.engineering && guide.durable_apis,
366        ..BuildOptions::new(cwd)
367    };
368    Ok((build_system_prompt(&options, None)?, warnings))
369}
370
371/// The profile's models.json over the built-in catalog (custom providers and models, overrides, keys, headers).
372/// The registry also restores stored catalogs (models-store.json beside models.json) and imports a Radius provider's
373/// legacy credential catalog on first sight (`ModelRuntime.create`'s offline refresh).
374pub fn registry(env: &Env) -> ModelRegistry {
375    let paths = config::paths::AgentPaths::new(env.agent_dir());
376    let models = paths.models();
377    let mut registry = ModelRegistry::load(&models, &env.home);
378    if let Some(credentials) = std::fs::read_to_string(paths.auth())
379        .ok()
380        .and_then(|text| config::json::parse(&text).ok())
381    {
382        let store = config::models_store::ModelsStore::beside(&models);
383        registry.import_legacy_radius(&credentials, &store, now_ms());
384    }
385    registry
386}
387
388/// The model `provider`/`id` (built-in or from models.json), ready for requests.
389pub fn catalog_model(provider: &str, id: &str, env: &Env) -> Result<Model, String> {
390    let registry = registry(env);
391    let model = registry
392        .find(provider, id)
393        .ok_or_else(|| format!("Model \"{provider}/{id}\" not found"))?;
394    Ok(for_requests(&registry, model, env))
395}
396
397/// `model` ready for requests: models.json headers resolved per request, and the base URL of the provider's stored
398/// OAuth credential (GitHub Copilot's token endpoint) read per request, over the catalog's or models.json's.
399pub fn for_requests(registry: &ModelRegistry, model: Model, env: &Env) -> Model {
400    prepare(registry, model, env)
401}
402
403/// The providers whose requests run on a subscription, so their costs are notional (`/usage`'s
404/// `subscriptionProviders`, session-worker.ts: every provider of the runtime's models that
405/// `modelRuntime.isUsingSubscription`): Claude Code when it is configured, a provider signed in with an OAuth login
406/// that is a subscription (Anthropic Pro/Max, OpenAI Codex, GitHub Copilot, ...), and always `claude-subscription`
407/// (the Claude Code login; TypeScript has no such provider).
408pub fn subscription_providers(env: &Env) -> Vec<String> {
409    let registry = registry(env);
410    let options = crate::stored_auth::OAuthOptions::for_env(env);
411    let mut providers: Vec<String> = registry
412        .provider_ids()
413        .into_iter()
414        .filter(|p| {
415            if p == ai::claude_code::PROVIDER {
416                return registry.auth_configured(p, &*env.var, false);
417            }
418            stored_oauth(env, p)
419                && crate::stored_auth::oauth_handler_with(env, p, &options).is_some_and(|oauth| oauth.is_subscription())
420        })
421        .collect();
422    let dynamic = ai::claude_subscription::PROVIDER.to_string();
423    if !providers.contains(&dynamic) {
424        providers.push(dynamic);
425    }
426    providers
427}
428
429/// Whether the provider's stored credential is an OAuth one.
430fn stored_oauth(env: &Env, provider: &str) -> bool {
431    let auth = config::paths::AgentPaths::new(env.agent_dir()).auth();
432    config::auth::read_stored_credential(&auth, provider)
433        .is_some_and(|c| c.get("type").and_then(Value::as_str) == Some("oauth"))
434}
435
436/// The stored credential's request auth (an OAuth credential's base URL and headers, an api-key credential's env) is
437/// resolved for each request, whatever was stored when the model was chosen: a `/login` while the session runs
438/// (Kimi For Coding's OAuth over `KIMI_API_KEY`, Copilot's endpoint) applies to the current model's next request,
439/// as TypeScript's `getAuth` per request does.
440fn prepare(registry: &ModelRegistry, model: Model, env: &Env) -> Model {
441    let mut model = registry.for_requests(model, env.var.clone());
442    // Claude Code's own login authenticates its CLI providers; nothing stored in auth.json reaches them.
443    if [ai::claude_code::PROVIDER, ai::claude_subscription::PROVIDER].contains(&model.provider.as_str()) {
444        return model;
445    }
446    let (env, provider) = (env.clone(), model.provider.clone());
447    // Whether the provider needs it is read per request too (auth.json now), so a provider with nothing stored runs
448    // its models.json `!command` key once per request, as before.
449    model.request.get_or_insert_default().stored_auth = Some(Arc::new(move || {
450        crate::stored_auth::has_request_auth(&env, &provider)
451            .then(|| crate::stored_auth::request_auth(&env, &provider))
452            .flatten()
453    }));
454    model
455}
456
457/// `--provider`/`--model` against the built-in catalog and models.json (`resolveCliModel`: fuzzy ids, `provider/`
458/// prefixes, `<pattern>:<thinking>`, the custom-id fallback), ready for requests; without `--model`, the initial
459/// model of a new session.
460pub fn resolve_model(flags: &ModelFlags, env: &Env) -> Result<Model, String> {
461    resolve_choice(flags, env, false).map(|choice| choice.model)
462}
463
464/// The model a session starts on and the thinking level its choice names explicitly (a `:<thinking>` suffix, a
465/// scoped pattern's level); `None` leaves the level to the settings (sdk.ts: per-model level, default, medium).
466#[derive(Clone, Debug)]
467pub struct ModelChoice {
468    pub model: Model,
469    pub thinking: Option<String>,
470    /// `resolveCliModel`'s warning (an invalid suffix, a custom model id).
471    pub warning: Option<String>,
472}
473
474/// `resolveCliModel({cliProvider, cliModel, modelRuntime})` over the profile's models; the model as listed, not
475/// prepared for requests. With `authenticated`, the providers that have configured credentials break ties
476/// (`hasConfiguredAuth`); without, none do (a runtime created without its first refresh has no configured providers
477/// yet, as `ultron auth check`'s).
478pub fn resolve_cli_model(
479    env: &Env,
480    provider: Option<&str>,
481    model: &str,
482    authenticated: bool,
483) -> ai::model_resolver::CliModel {
484    let registry = registry(env);
485    let configured = if authenticated {
486        configured_providers(env, &registry)
487    } else {
488        Vec::new()
489    };
490    registry.resolve_cli(provider, model, None, &|p: &str| configured.iter().any(|c| c == p))
491}
492
493/// [`resolve_model`] with the thinking level the choice carries. `continuing`: the session already has history,
494/// so scoped models (`--models`, `enabledModels`) do not pick its model.
495pub fn resolve_choice(flags: &ModelFlags, env: &Env, continuing: bool) -> Result<ModelChoice, String> {
496    let Some(spec) = flags.model.as_deref() else {
497        if let Some(choice) = durable_choice(flags, env) {
498            return Ok(choice);
499        }
500        return initial_choice(flags, env, continuing)
501            .ok_or_else(|| "No model selected: pass --model <provider>/<id>".to_string());
502    };
503    let registry = registry(env);
504    let configured = configured_providers(env, &registry);
505    let has_auth = |p: &str| configured.iter().any(|c| c == p);
506    let resolved = registry.resolve_cli(flags.provider.as_deref(), spec, flags.thinking.as_deref(), &has_auth);
507    let model = match (resolved.model, resolved.error) {
508        (Some(model), _) => model,
509        (None, error) => return Err(error.unwrap_or_else(|| format!("Model \"{spec}\" not found"))),
510    };
511    Ok(ModelChoice {
512        model: for_requests(&registry, model, env),
513        thinking: resolved.thinking_level,
514        warning: resolved.warning,
515    })
516}
517
518/// Whether this run belongs to the durable instance: one of its session workers (config::settings
519/// `is_durable_process`) or a client of it (`ultron durable ...`, `ultron-s`: [`config::settings::DURABLE_CLIENT_ENV`]).
520pub fn is_durable(env: &Env) -> bool {
521    config::settings::is_durable_process() || (env.var)(config::settings::DURABLE_CLIENT_ENV).as_deref() == Some("1")
522}
523
524/// A new session of the durable instance with no `--model`, `--provider` or `--models` starts on `durable.model`
525/// (default `claude-code/claude-opus-5-5`, the Claude subscription), ahead of `defaultProvider`/`defaultModel`; a
526/// resumed one keeps its stored lane (crate::core `lane_config` resolves no model for it without flags). Resolved as an explicit choice would be, so a missing `claude` login fails on the subscription with its own
527/// error instead of moving the session to the global default's provider. A `durable.model` that does not resolve
528/// leaves the session to the global defaults.
529fn durable_choice(flags: &ModelFlags, env: &Env) -> Option<ModelChoice> {
530    if flags.provider.is_some() || flags.models.is_some() || !is_durable(env) {
531        return None;
532    }
533    let spec = config::settings::SettingsManager::for_worker(&env.cwd, &env.agent_dir(), &env.home).durable_model();
534    let registry = registry(env);
535    let configured = configured_providers(env, &registry);
536    let resolved = registry.resolve_cli(None, &spec, None, &|p: &str| configured.iter().any(|c| c == p));
537    let model = resolved.model.filter(|_| resolved.error.is_none())?;
538    Some(ModelChoice {
539        model: for_requests(&registry, model, env),
540        thinking: resolved.thinking_level,
541        warning: resolved.warning,
542    })
543}
544
545fn initial_choice(flags: &ModelFlags, env: &Env, continuing: bool) -> Option<ModelChoice> {
546    let settings = config::settings::SettingsManager::for_worker(&env.cwd, &env.agent_dir(), &env.home);
547    let all = settings.settings();
548    let text = |v: Option<Value>| v.and_then(|v| v.as_str().map(str::to_string));
549    let registry = registry(env);
550    let available = available_models(env);
551    let patterns: Vec<String> = match &flags.models {
552        Some(patterns) => patterns.clone(),
553        None => all
554            .get("enabledModels")
555            .and_then(Value::as_array)
556            .map(|a| a.iter().filter_map(Value::as_str).map(str::to_string).collect())
557            .unwrap_or_default(),
558    };
559    let (default_provider, default_model) = (text(settings.default_provider()), text(settings.default_model()));
560    let choice = |model: Model, thinking: Option<String>| ModelChoice {
561        model: for_requests(&registry, model, env),
562        thinking,
563        warning: None,
564    };
565    if !continuing && !patterns.is_empty() {
566        let (scoped, _) = ai::model_resolver::resolve_model_scope(&patterns, &available);
567        // `buildSessionOptions`: the saved default when it is in scope, else the first scoped model.
568        let saved = scoped.iter().find(|s| {
569            default_provider.as_deref() == Some(s.model.provider.as_str())
570                && default_model.as_deref() == Some(s.model.id.as_str())
571        });
572        if let Some(pick) = saved.or(scoped.first()) {
573            return Some(choice(pick.model.clone(), pick.thinking_level.clone()));
574        }
575    }
576    let levels = all
577        .get("modelThinkingLevels")
578        .and_then(Value::as_object)
579        .map(|m| {
580            m.iter()
581                .filter_map(|(k, v)| Some((k.clone(), v.as_str()?.to_string())))
582                .collect()
583        })
584        .unwrap_or_default();
585    let initial = ai::model_resolver::InitialSettings {
586        default_provider,
587        default_model_id: default_model,
588        default_thinking_level: all
589            .get("defaultThinkingLevel")
590            .and_then(Value::as_str)
591            .map(str::to_string),
592        model_thinking_levels: levels,
593    };
594    let configured: Vec<String> = available.iter().map(|m| m.provider.clone()).collect();
595    let has_auth = |p: &str| configured.iter().any(|c| c == p);
596    let mut models = registry.all_models();
597    // A saved default on the dynamic claude-subscription catalog lists no models of its own.
598    if let (Some(p), Some(id)) = (&initial.default_provider, &initial.default_model_id)
599        && let Some(found) = registry.find(p, id)
600        && !models.iter().any(|m| m.provider == found.provider && m.id == found.id)
601    {
602        models.push(found);
603    }
604    // sdk.ts takes only the model: its thinking level comes from the settings, as for any other start.
605    let (model, _) = ai::model_resolver::find_initial_model(&[], continuing, &initial, &models, &available, &has_auth);
606    model.map(|model| choice(model, None))
607}
608
609/// The thinking level a session starts with when nothing names one: the settings' level for `model`
610/// (`modelThinkingLevels`), else `defaultThinkingLevel`, else medium.
611fn initial_level(all: &serde_json::Map<String, Value>, model: &Model) -> String {
612    all.get("modelThinkingLevels")
613        .and_then(|levels| levels.get(format!("{}/{}", model.provider, model.id)))
614        .and_then(Value::as_str)
615        .or_else(|| all.get("defaultThinkingLevel").and_then(Value::as_str))
616        .unwrap_or(model_scope::DEFAULT_THINKING_LEVEL)
617        .to_string()
618}
619
620/// The thinking level a session starts with when `--thinking` is not given: the settings' level for `model`
621/// (`modelThinkingLevels`), else `defaultThinkingLevel`, else medium. Stored as chosen, like TS: requests clamp it
622/// to what the model supports.
623pub fn initial_thinking(model: &Model, env: &Env) -> String {
624    let settings = config::settings::SettingsManager::for_worker(&env.cwd, &env.agent_dir(), &env.home);
625    initial_level(settings.settings(), model)
626}
627
628/// The providers with credentials (`hasConfiguredAuth`): a stored credential, the models.json key, or the built-in
629/// provider's environment key.
630fn configured_providers(env: &Env, registry: &ModelRegistry) -> Vec<String> {
631    let auth = config::paths::AgentPaths::new(env.agent_dir()).auth();
632    registry
633        .provider_ids()
634        .into_iter()
635        .filter(|p| {
636            config::auth::read_stored_credential(&auth, p).is_some()
637                || registry.auth_configured(p, &*env.var, env_api_key_with(env, registry, p).is_some())
638        })
639        .collect()
640}
641
642/// The model runtime's available snapshot: the models of providers with credentials (a stored credential, the
643/// models.json key, or the built-in provider's environment key), ready for requests.
644pub fn available_models(env: &Env) -> Vec<Model> {
645    let registry = registry(env);
646    let mut models: Vec<Model> = configured_providers(env, &registry)
647        .into_iter()
648        .flat_map(|p| {
649            let registry = &registry;
650            provider_models(env, registry, &p)
651                .into_iter()
652                .map(move |m| prepare(registry, m, env))
653        })
654        .collect();
655    models.extend(subscription_models(env, &registry, &models));
656    models
657}
658
659/// A configured provider's models as `getAvailable` lists them: [`ai::auth::filter_models`] with its stored
660/// credential.
661fn provider_models(env: &Env, registry: &ModelRegistry, provider: &str) -> Vec<Model> {
662    let models = registry.models(provider);
663    let credential = || {
664        let auth = config::paths::AgentPaths::new(env.agent_dir()).auth();
665        config::auth::read_stored_credential(&auth, provider).and_then(|c| ai::auth::Credential::from_json(&c))
666    };
667    ai::auth::filter_models(provider, &models, |m| m.id.as_str(), credential)
668        .into_iter()
669        .cloned()
670        .collect()
671}
672
673/// The Claude subscription's pinned models, when Claude Code is installed. Its catalog takes any id, so the registry
674/// lists none of them; without this they are reachable only as `--model claude-subscription/<id>`. Models already
675/// listed (a models.json entry for the provider) are not repeated.
676fn subscription_models(env: &Env, registry: &ModelRegistry, listed: &[Model]) -> Vec<Model> {
677    use ai::claude_subscription::{PROVIDER, catalog, process};
678    let mut lookup: ai::claude_subscription::Env = [
679        process::COMMAND_ENV,
680        ai::claude_code_cli::CLAUDE_CODE_BIN_ENV,
681        "PATH",
682        "HOME",
683    ]
684    .into_iter()
685    .filter_map(|k| (env.var)(k).map(|v| (k.to_string(), v)))
686    .collect();
687    lookup
688        .entry("HOME".into())
689        .or_insert_with(|| env.home.to_string_lossy().into_owned());
690    if process::resolve_claude(None, &lookup).is_none() {
691        return Vec::new();
692    }
693    catalog::pinned_routes()
694        .into_iter()
695        .filter(|(_, id, _)| !listed.iter().any(|m| m.provider == PROVIDER && m.id == *id))
696        .filter_map(|(_, id, _)| registry.find(PROVIDER, id))
697        .map(|m| prepare(registry, m, env))
698        .collect()
699}
700
701/// The key a request of `provider` carries (`ModelRuntime.getAuth`): `--api-key` (a runtime key: pass it only for
702/// the provider it was given for, the starting model's; a session's lanes use [`crate::request_keys::Keys`]), else the auth.json
703/// credential (an api key, or an OAuth access token; a stored credential owns the provider), else the models.json
704/// key, else the environment; `None` when there is none or the configured one does not resolve.
705pub fn api_key(flags: &ModelFlags, env: &Env, provider: &str) -> Option<String> {
706    request_key(flags, env, provider).ok().flatten()
707}
708
709/// [`api_key`] with the error of a key that does not resolve (a models.json `$VAR` unset, `!command` failing, an
710/// unreadable auth.json, a failed OAuth refresh).
711pub fn request_key(flags: &ModelFlags, env: &Env, provider: &str) -> Result<Option<String>, String> {
712    if let Some(key) = flags.api_key.as_deref() {
713        return Ok(Some(key.to_string()));
714    }
715    if let Some(key) = crate::stored_auth::resolved_key(env, provider)? {
716        return Ok(key);
717    }
718    match crate::stored_auth::stored_key(env, provider)? {
719        crate::stored_auth::Stored::Owns(key) => Ok(key),
720        crate::stored_auth::Stored::Nothing => {
721            let registry = registry(env);
722            let inherited = env_api_key_with(env, &registry, provider);
723            registry.api_key(provider, None, &*env.var, inherited)
724        }
725    }
726}
727
728/// Whether `provider` authenticates requests by headers alone: a stored OAuth credential's (Kimi For Coding's
729/// `Authorization: Bearer`, `toAuth` with no key), `ANTHROPIC_AUTH_TOKEN`, the AI Gateway (`getAuth` resolves, so a
730/// request needs no API key).
731pub fn header_auth(env: &Env, provider: &str) -> bool {
732    crate::stored_auth::oauth_request_auth(env, provider).is_some_and(|auth| auth.headers.is_some())
733        || crate::stored_auth::header_owned(env, provider)
734}
735
736/// The provider's key from the environment and the profile's credential files. A models.json Radius provider
737/// inherits the built-in Radius key (`RADIUS_API_KEY`).
738pub fn env_api_key(env: &Env, provider: &str) -> Option<String> {
739    env_api_key_with(env, &registry(env), provider)
740}
741
742/// [`env_api_key`] with `stored` (a stored credential's `env`) read before the environment.
743pub(crate) fn env_api_key_over(
744    env: &Env,
745    provider: &str,
746    stored: &std::collections::HashMap<String, String>,
747) -> Option<String> {
748    let lookup = |name: &str| stored.get(name).cloned().or_else(|| (env.var)(name));
749    env_api_key_in(env, &registry(env), provider, &lookup)
750}
751
752fn env_api_key_with(env: &Env, registry: &ModelRegistry, provider: &str) -> Option<String> {
753    env_api_key_in(env, registry, provider, &*env.var)
754}
755
756fn env_api_key_in(
757    env: &Env,
758    registry: &ModelRegistry,
759    provider: &str,
760    lookup: &dyn Fn(&str) -> Option<String>,
761) -> Option<String> {
762    let provider = if registry.radius_gateway(provider).is_some() {
763        "radius"
764    } else {
765        provider
766    };
767    let source = ai::env::EnvSource {
768        lookup,
769        exists: &|p: &Path| p.exists(),
770        home: Some(env.home.clone()),
771    };
772    ai::env::env_api_key_in(provider, &source)
773}
774
775/// Whether the Rust providers stream this API: every API of `ai::dispatch` (the TypeScript API registry).
776pub fn api_supported(api: &str) -> bool {
777    ai::dispatch::APIS.contains(&api)
778}
779
780/// A client with this process's proxy variables as Pi's HTTP stack reads them (`EnvHttpProxyAgent` over
781/// `process.env`): a session worker's environment carries the run's `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY`.
782pub fn process_transport() -> ReqwestTransport {
783    ReqwestTransport::for_env(&|key| std::env::var(key).ok(), None)
784}
785
786/// Reads the worker's settings as they are now ([`crate::compose::Config::settings_reader`]).
787pub type SettingsReader = Arc<dyn Fn() -> config::settings::SettingsManager + Send + Sync>;
788
789/// A transport whose idle timeout follows `httpIdleTimeoutMs` as it is now (TS reconfigures its process dispatcher
790/// when the setting changes): rebuilt when the setting changes.
791struct LiveTransport {
792    current: Mutex<(Option<std::time::Duration>, Arc<dyn Transport>)>,
793}
794
795/// The model call for every API the Rust providers cover. A request whose signal is already aborted is not sent:
796/// it ends as an empty aborted message. `api_key` fills requests that carry none (a subagent's loop).
797pub struct Provider {
798    transport: Arc<dyn Transport>,
799    api_key: Option<String>,
800    /// Routes `claude-subscription` calls (subscription first, API credits when out of usage); `None`: the
801    /// process's router.
802    router: Option<Arc<ai::claude_subscription::fallback::Router>>,
803    /// What the settings fill into every request (`thinkingBudgets`, `websocketConnectTimeoutMs`, the stream
804    /// options and `transport`).
805    request: crate::request_settings::RequestSettings,
806    /// Read before each request instead of `request` (see [`Provider::with_live_settings`]).
807    live: Option<SettingsReader>,
808    /// With `live`: the process transport at the idle timeout the settings name now.
809    live_transport: Option<LiveTransport>,
810}
811
812impl Provider {
813    pub fn new() -> Self {
814        Provider {
815            transport: Arc::new(process_transport().with_idle_timeout(None)),
816            api_key: None,
817            router: None,
818            request: Default::default(),
819            live: None,
820            live_transport: None,
821        }
822    }
823
824    /// Requests take `request`'s settings where they set none (crate::request_settings).
825    pub fn with_request_settings(mut self, request: crate::request_settings::RequestSettings) -> Self {
826        self.request = request;
827        self
828    }
829
830    /// Requests take the settings as `settings` reads them before each request, so a `/settings` change of
831    /// `transport`, `httpIdleTimeoutMs` (the request timeout and the transport's idle timeout) or `retry.provider`
832    /// applies to the next request (TS `harness.setStreamOptions`). The process transport follows `httpIdleTimeoutMs`
833    /// too, until [`with_transport`](Self::with_transport) replaces it.
834    pub fn with_live_settings(mut self, settings: SettingsReader) -> Self {
835        let idle = ai::http::http_idle_timeout(settings().settings().get("httpIdleTimeoutMs"));
836        let transport: Arc<dyn Transport> = Arc::new(process_transport().with_idle_timeout(idle));
837        self.transport = transport.clone();
838        self.live_transport = Some(LiveTransport {
839            current: Mutex::new((idle, transport)),
840        });
841        self.live = Some(settings);
842        self
843    }
844
845    /// Requests go over `transport` (tests and embedders), whatever `httpIdleTimeoutMs` says.
846    pub fn with_transport(mut self, transport: Arc<dyn Transport>) -> Self {
847        self.transport = transport;
848        self.live_transport = None;
849        self
850    }
851
852    /// The request settings now, and the transport to send on.
853    fn current(
854        &self,
855    ) -> (
856        std::borrow::Cow<'_, crate::request_settings::RequestSettings>,
857        Arc<dyn Transport>,
858    ) {
859        let Some(read) = &self.live else {
860            return (std::borrow::Cow::Borrowed(&self.request), self.transport.clone());
861        };
862        let settings = read();
863        let request = crate::request_settings::RequestSettings::from_manager(&settings);
864        let transport = match &self.live_transport {
865            Some(live) => {
866                let idle = ai::http::http_idle_timeout(settings.settings().get("httpIdleTimeoutMs"));
867                let mut current = live.current.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
868                if current.0 != idle {
869                    *current = (idle, Arc::new(process_transport().with_idle_timeout(idle)));
870                }
871                current.1.clone()
872            }
873            None => self.transport.clone(),
874        };
875        (std::borrow::Cow::Owned(request), transport)
876    }
877
878    /// The stream options requests carry now (an operation's `streamOptions` in the session journal).
879    pub fn stream_options(&self) -> Option<Value> {
880        self.current().0.stream_options()
881    }
882
883    /// [`Provider::with_transport`] whose Claude subscription calls go through `router`.
884    pub fn with_router(router: Arc<ai::claude_subscription::fallback::Router>, transport: Arc<dyn Transport>) -> Self {
885        Provider {
886            router: Some(router),
887            ..Provider::new()
888        }
889        .with_transport(transport)
890    }
891
892    pub fn with_key(api_key: Option<String>) -> Self {
893        Provider {
894            api_key,
895            ..Provider::new()
896        }
897    }
898
899    /// A provider whose requests fail when headers or the stream stall for `idle` (`httpIdleTimeoutMs`).
900    pub fn with_idle_timeout(idle: Option<std::time::Duration>) -> Self {
901        Provider {
902            transport: Arc::new(process_transport().with_idle_timeout(idle)),
903            ..Provider::new()
904        }
905    }
906}
907
908impl Default for Provider {
909    fn default() -> Self {
910        Self::new()
911    }
912}
913
914impl StreamFn for Provider {
915    fn stream<'a>(
916        &'a self,
917        model: &'a Model,
918        context: &'a TranscriptContext,
919        options: &'a SimpleStreamOptions,
920        sink: &'a mut EventSink<'_>,
921    ) -> BoxFuture<'a, AssistantMessage> {
922        Box::pin(async move {
923            if options.base.signal.as_ref().is_some_and(AbortSignal::aborted) {
924                let mut message = error_message(model, String::new());
925                message.stop_reason = StopReason::Aborted;
926                message.error_message = None;
927                return message;
928            }
929            let mut keyed = options.clone();
930            if keyed.base.api_key.is_none() && self.api_key.is_some() {
931                keyed.base.api_key = self.api_key.clone();
932            }
933            let (request, transport) = self.current();
934            if let Err(error) = request.apply(&mut keyed) {
935                return error_message(model, error);
936            }
937            let options = &keyed;
938            // A stored OAuth credential may name the request's base URL (Copilot's token endpoint) and headers
939            // (Kimi's bearer); models.json headers (and `authHeader`'s bearer) go out over them, under the caller's.
940            let (routed, prepared) = match ai::model_registry::prepare_request(model, options) {
941                Ok(prepared) => prepared,
942                Err(error) => return error_message(model, error),
943            };
944            let model = routed.as_ref().unwrap_or(model);
945            let options = prepared.as_ref().unwrap_or(options);
946            // Every API the TypeScript session streams (`streamSimple` over the API registry), the Claude ones through
947            // this provider's router.
948            match &self.router {
949                Some(router) => {
950                    ai::dispatch::stream_simple_routed(router, model, context, options, &*transport, sink).await
951                }
952                None => ai::dispatch::stream_simple(model, context, options, &*transport, sink).await,
953            }
954            .unwrap_or_else(|e| error_message(model, e))
955        })
956    }
957}
958
959pub fn error_message(model: &Model, error: String) -> AssistantMessage {
960    let mut message: AssistantMessage = serde_json::from_value(json!({
961        "content": [], "api": model.api, "provider": model.provider, "model": model.id,
962        "usage": ai::Usage::default(), "stopReason": "stop", "timestamp": now_ms(),
963    }))
964    .expect("an empty assistant message deserializes");
965    message.stop_reason = StopReason::Error;
966    message.error_message = Some(error);
967    message
968}
969
970/// Resolves with `work`'s output, or `None` once `signal` aborts first.
971async fn until_aborted<T>(work: impl Future<Output = T>, signal: &AbortSignal) -> Option<T> {
972    let mut work = pin!(work);
973    let mut cancelled = pin!(signal.cancelled());
974    std::future::poll_fn(|cx| {
975        if let Poll::Ready(value) = work.as_mut().poll(cx) {
976            return Poll::Ready(Some(value));
977        }
978        match cancelled.as_mut().poll(cx) {
979            Poll::Ready(()) => Poll::Ready(None),
980            Poll::Pending => Poll::Pending,
981        }
982    })
983    .await
984}
985
986/// How long a cell may run before its tool call returns with the cell still running (detached). Cells that park
987/// on a host-side wait detach at once; in a lane nothing wakes, others run as long as they need, as in TypeScript.
988const CELL_BUDGET: Duration = Duration::from_secs(24 * 60 * 60);
989
990/// How long a woken lane's cell holds its tool call by default before it continues in the background: short, so
991/// the user can always keep chatting (anything a cell waits on, `bash` included, yields with it).
992const DEFAULT_CELL_YIELD_AFTER: Duration = Duration::from_secs(10);
993
994/// `ULTRON_CELL_YIELD_AFTER` seconds (default 10): a woken lane's cell still running then is detached, so the turn
995/// ends and its end arrives as a `cell_done` event. `0`, `off`, a negative or a non-finite number keep the cell in its
996/// tool call until it ends; an unreadable value is the default.
997pub fn cell_yield_after(raw: Option<&str>) -> Option<Duration> {
998    let raw = raw.map(|raw| raw.trim().to_lowercase()).unwrap_or_default();
999    if raw.is_empty() {
1000        return Some(DEFAULT_CELL_YIELD_AFTER);
1001    }
1002    if matches!(raw.as_str(), "off" | "none" | "false" | "no") {
1003        return None;
1004    }
1005    match raw.parse::<f64>() {
1006        Ok(seconds) if seconds.is_finite() && seconds > 0.0 => Some(Duration::from_secs_f64(seconds)),
1007        Ok(_) => None,
1008        Err(_) => Some(DEFAULT_CELL_YIELD_AFTER),
1009    }
1010}
1011
1012/// The `rlm` tool (`createUltronRlmTool` for one lane): each call runs its cell in the lane of the session's REPL
1013/// lanes (crates/delegation `Lanes`). Aborting the turn cancels the running cell.
1014pub struct Rlm {
1015    tool: Tool,
1016    lanes: Lanes,
1017    lane: String,
1018    /// The session's masker: values MCP servers resolve (env, headers) are registered in it.
1019    masker: Arc<OutputMasker>,
1020    mask_secrets: Option<String>,
1021    max_bytes: usize,
1022    spill_dir: PathBuf,
1023    /// Situational hints (`ULTRON_HINTS=on`; the loop guards without it): one `[hint:<tag>]` line at the end of a
1024    /// cell's result.
1025    hints: Option<Arc<kernel_apis::cell_hints::CellHints>>,
1026    /// The images a cell attaches with `view_image` (crate::view_images).
1027    images: Arc<crate::view_images::ViewImages>,
1028    /// The lane's host, whose after-cell file hooks see each cell start and end; what they found arrives with
1029    /// the lane's next cell result.
1030    host: Option<Arc<Host>>,
1031    /// The budget line a cell's result ends with (crate::budget_note), once wired.
1032    budget: Arc<std::sync::OnceLock<crate::budget_note::BudgetNote>>,
1033    /// The session's runtime counters: each cell is counted where it runs.
1034    stats: Option<Arc<crate::session_stats::SessionStats>>,
1035    /// The context-pressure reminder a cell's result ends with when the lane nears its limit
1036    /// (crate::context_reminder).
1037    reminders: Option<Arc<crate::context_reminder::ContextReminders>>,
1038    /// Whether the host wakes this lane when its work ends (crate::wake): how a detached cell's note words its end,
1039    /// and whether a slow cell yields its tool call ([`cell_yield_after`]).
1040    wake: crate::wake::RootWake,
1041    /// How long a woken lane's cell holds its tool call ([`cell_yield_after`]); `None`: until it ends.
1042    yield_after: Option<Duration>,
1043}
1044
1045impl Rlm {
1046    /// How long this lane's next cell holds its tool call: a woken lane's slow cell yields after
1047    /// [`cell_yield_after`] (its end wakes the lane); any other lane's waits, as nothing would deliver its end.
1048    fn cell_budget(&self) -> Duration {
1049        match self.yield_after {
1050            Some(after) if self.wake.woken(&self.lane) => after,
1051            _ => CELL_BUDGET,
1052        }
1053    }
1054
1055    /// This tool with the stack's wake rule (crate::wake) for its detached-cell note.
1056    pub(crate) fn with_wake(mut self, wake: crate::wake::RootWake) -> Rlm {
1057        self.wake = wake;
1058        self
1059    }
1060
1061    pub(crate) fn with_budget_note(mut self, budget: Arc<std::sync::OnceLock<crate::budget_note::BudgetNote>>) -> Rlm {
1062        self.budget = budget;
1063        self
1064    }
1065
1066    /// This tool with its cells counted in `stats` (`stats.cell(lane, code, {failed, masked})`).
1067    pub(crate) fn with_stats(mut self, stats: Arc<crate::session_stats::SessionStats>) -> Rlm {
1068        self.stats = Some(stats);
1069        self
1070    }
1071
1072    pub(crate) fn with_context_reminders(mut self, reminders: Arc<crate::context_reminder::ContextReminders>) -> Rlm {
1073        self.reminders = Some(reminders);
1074        self
1075    }
1076
1077    /// The context reminder this lane's result `text` (with `images` images) ends with, if it is due.
1078    fn context_reminder(&self, text: &str, images: usize) -> Option<String> {
1079        self.reminders.as_ref()?.reminder(&self.lane, text, images)
1080    }
1081
1082    /// An error result's text, ending with the context reminder when it is due.
1083    fn with_reminder(&self, text: String) -> String {
1084        match self.context_reminder(&text, 0) {
1085            Some(line) => format!("{text}\n{line}"),
1086            None => text,
1087        }
1088    }
1089
1090    fn count_cell(&self, code: &str, failed: bool, masked: usize) {
1091        if let Some(stats) = &self.stats {
1092            stats.cell(&self.lane, code, failed, masked);
1093        }
1094    }
1095
1096    /// The budget line this cell's result ends with, if any (`budgetNote(lane, operationId)`).
1097    fn budget_line(&self) -> Option<String> {
1098        self.budget.get().and_then(|note| note(&self.lane))
1099    }
1100
1101    /// The hint the cell earned with this result text (or error message), if any.
1102    fn hint(&self, text: &str, ename: Option<&str>) -> Option<String> {
1103        let outcome = kernel_apis::cell_hints::CellOutcome { text, ename };
1104        self.hints
1105            .as_ref()
1106            .and_then(|hints| hints.end_cell(&self.lane, &outcome))
1107    }
1108
1109    /// The cell's result text (or error message) with the hint its cell earned, if any.
1110    fn with_hint(&self, text: String, ename: Option<&str>) -> String {
1111        match self.hint(&text, ename) {
1112            Some(hint) => format!("{text}\n{hint}"),
1113            None => text,
1114        }
1115    }
1116
1117    /// Tells the file hooks this lane's cell ended; what they found since earlier cells, to go with its result.
1118    fn end_cell(&self) -> Option<String> {
1119        let host = self.host.as_ref()?;
1120        host.cell_ended(&self.lane);
1121        host.take_pending(&self.lane)
1122    }
1123
1124    /// How this lane's cell results are finished (masking, the byte budget, the spill directory).
1125    fn cell_format(&self) -> CellFormat<'_> {
1126        CellFormat {
1127            masker: &self.masker,
1128            mask_secrets: self.mask_secrets.as_deref(),
1129            max_bytes: self.max_bytes,
1130            spill_dir: Some(&self.spill_dir),
1131        }
1132    }
1133}
1134
1135impl AgentTool for Rlm {
1136    fn tool(&self) -> &Tool {
1137        &self.tool
1138    }
1139    fn execute<'a>(
1140        &'a self,
1141        _id: &'a str,
1142        args: Value,
1143        signal: &'a AbortSignal,
1144        _update: &'a ToolUpdate<'a>,
1145    ) -> BoxFuture<'a, Result<AgentToolResult, String>> {
1146        Box::pin(self.run_cell(args, signal))
1147    }
1148}
1149
1150impl Rlm {
1151    /// One cell, as its result text (or error message). A cell run in a side lane because this lane is still busy
1152    /// (`Lanes::start_routed`) starts its result with the side-lane note.
1153    async fn run_cell(&self, args: Value, signal: &AbortSignal) -> Result<AgentToolResult, String> {
1154        let note = Mutex::new(None);
1155        let result = self.run_routed_cell(args, signal, &note).await;
1156        let Some(note) = note.lock().unwrap_or_else(std::sync::PoisonError::into_inner).take() else {
1157            return result;
1158        };
1159        match result {
1160            Err(text) => Err(format!("{note}\n{text}")),
1161            Ok(mut result) => {
1162                match result.content.iter_mut().find_map(|part| match part {
1163                    UserContent::Text(text) => Some(text),
1164                    UserContent::Image(_) => None,
1165                }) {
1166                    Some(text) => text.text = format!("{note}\n{}", text.text),
1167                    None => result.content.insert(0, text_block(note)),
1168                }
1169                Ok(result)
1170            }
1171        }
1172    }
1173
1174    async fn run_routed_cell(
1175        &self,
1176        args: Value,
1177        signal: &AbortSignal,
1178        note: &Mutex<Option<String>>,
1179    ) -> Result<AgentToolResult, String> {
1180        {
1181            let code = args["code"].as_str().ok_or("rlm needs a `code` string")?.to_string();
1182            if let Some(hints) = &self.hints {
1183                if let Some(refusal) = hints.refusal(&self.lane, &code) {
1184                    return Err(refusal);
1185                }
1186                hints.begin_cell(&self.lane, &code);
1187            }
1188            self.images.begin(&self.lane);
1189            // Files a cell changes by other means than checked writes are handed to the hooks after it, in the
1190            // background; what they find arrives with this lane's next cell result.
1191            if let Some(host) = &self.host {
1192                host.cell_started(&self.lane);
1193            }
1194            // A busy lane never refuses the cell: it runs in a side lane (crates/delegation `Lanes::start_routed`).
1195            let (lanes, lane, source) = (self.lanes.clone(), self.lane.clone(), code.clone());
1196            let started = tokio::task::spawn_blocking(move || lanes.start_routed(&lane, &source))
1197                .await
1198                .map_err(|e| e.to_string())
1199                .and_then(|started| started);
1200            let started = match started {
1201                Ok(started) => {
1202                    *note.lock().unwrap_or_else(std::sync::PoisonError::into_inner) = started.note.clone();
1203                    Ok(started.cell)
1204                }
1205                Err(error) => Err(error),
1206            };
1207            let waited = match &started {
1208                Ok(id) => {
1209                    let (lanes, id) = (self.lanes.clone(), id.clone());
1210                    let budget = self.cell_budget();
1211                    Some(tokio::task::spawn_blocking(move || lanes.wait(&id, budget)))
1212                }
1213                Err(_) => None,
1214            };
1215            let outcome: Result<Result<CellOutcome, String>, String> = match (started, waited) {
1216                (Ok(id), Some(mut cell)) => match until_aborted(&mut cell, signal).await {
1217                    Some(done) => done.map_err(|e| e.to_string()),
1218                    None => {
1219                        let _ = self.lanes.cancel(&id, ABORT_REQUESTED);
1220                        let _ = cell.await;
1221                        self.count_cell(&code, true, 0);
1222                        let findings = self.end_cell();
1223                        self.images.take(&self.lane);
1224                        self.images.take_display(&self.lane);
1225                        return Err(match findings {
1226                            Some(findings) => format!("{ABORT_REQUESTED}\n{findings}"),
1227                            None => ABORT_REQUESTED.into(),
1228                        });
1229                    }
1230                },
1231                (Err(error), _) => Ok(Err(error)),
1232                (Ok(_), None) => Err("cell vanished".into()),
1233            };
1234            // A cell that could not run, or ended without a result, is counted as failed now; one with a result
1235            // when its text is made (below).
1236            let has_result = matches!(outcome, Ok(Ok(CellOutcome::Done(Ok(_)))));
1237            if !has_result {
1238                let left_running = matches!(outcome, Ok(Ok(CellOutcome::Running { .. })));
1239                self.count_cell(&code, !left_running, 0);
1240            }
1241            let findings = self.end_cell();
1242            // Findings follow the result text (and an error's hint), as session-worker.ts `withFindings`.
1243            let with_findings = |text: String| match &findings {
1244                Some(findings) => format!("{text}\n{findings}"),
1245                None => text,
1246            };
1247            // What the cell attached ends with its tool call (a cell that keeps running loses later ones).
1248            let outcome = outcome.map_err(|e| self.with_reminder(with_findings(e.to_string())));
1249            let images = self.images.take(&self.lane);
1250            let shown = self.images.take_display(&self.lane);
1251            let outcome = outcome?.map_err(|e| self.with_reminder(with_findings(e.to_string())))?;
1252            if signal.aborted() {
1253                if has_result {
1254                    // It ran to its end; the turn was aborted meanwhile.
1255                    self.count_cell(&code, false, 0);
1256                }
1257                return Err(with_findings(ABORT_REQUESTED.into()));
1258            }
1259            let result = match outcome {
1260                CellOutcome::Done(result) => {
1261                    result.map_err(|e| self.with_reminder(with_findings(self.with_hint(e, Some("Error")))))?
1262                }
1263                CellOutcome::Running { cell, parked } => {
1264                    if !parked {
1265                        self.lanes.detach(&cell)?;
1266                    }
1267                    return Ok(AgentToolResult {
1268                        content: vec![text_block(with_findings(match parked {
1269                            true => detached_note(&cell, self.wake.woken(&self.lane)),
1270                            false => yielded_note(&cell, self.cell_budget()),
1271                        }))],
1272                        details: json!({}),
1273                        usage: None,
1274                        terminate: None,
1275                    });
1276                }
1277            };
1278            let output = cell_output(&result, &self.cell_format());
1279            self.count_cell(
1280                &code,
1281                output.is_err(),
1282                output
1283                    .as_ref()
1284                    .map_or_else(|failure| failure.masked, |output| output.masked),
1285            );
1286            let output = output.map_err(|failure| {
1287                self.with_reminder(with_findings(self.with_hint(failure.message, Some(&failure.ename))))
1288            })?;
1289            // Only a hint is appended: output that itself starts with a newline stays as it is.
1290            let hint = self.hint(&output.text, None);
1291            let text = with_findings(crate::view_images::with_display_lines(
1292                match output.text.is_empty() {
1293                    true => "(no result)".to_string(),
1294                    false => output.text,
1295                },
1296                &shown,
1297            ));
1298            let text = match hint {
1299                Some(hint) => format!("{text}\n{hint}"),
1300                None => text,
1301            };
1302            // The budget line comes last, after the hint, as `[text, hint, line].join("\n")`.
1303            let text = match self.budget_line() {
1304                Some(line) => format!("{text}\n{line}"),
1305                None => text,
1306            };
1307            // The context reminder ends it, once per approach to the lane's limit.
1308            let image_count = images.as_ref().map_or(0, |i| i.images.len());
1309            let text = match self.context_reminder(&text, image_count) {
1310                Some(line) => format!("{text}\n{line}"),
1311                None => text,
1312            };
1313            Ok(AgentToolResult {
1314                content: crate::view_images::cell_content(images.as_ref(), text),
1315                details: crate::view_images::with_display_details(
1316                    self.host.as_ref().map_or_else(
1317                        || json!({}),
1318                        |host| {
1319                            let mask = |text: &str| self.masker.mask_counted(text, self.mask_secrets.as_deref()).0;
1320                            crate::cell_file_changes::details(host, &self.lane, &mask)
1321                        },
1322                    ),
1323                    &shown,
1324                ),
1325                usage: None,
1326                terminate: None,
1327            })
1328        }
1329    }
1330}
1331
1332/// One session's root lane: the `rlm` tool over the "main" REPL lane of the session's host stack.
1333pub struct Lane {
1334    /// The host operations (shell, writes) behind the stack, for host-side commands such as RPC `bash`.
1335    pub host: Arc<Host>,
1336    pub stack: Arc<Stack>,
1337    pub tool: Arc<Rlm>,
1338    /// Completions of work the session's runs started (subagents, detached cells), delivered between turns.
1339    pub events: Arc<RuntimeEvents>,
1340}
1341
1342impl Lane {
1343    /// Start the root lane ("main") of `session_id` over `runtime`'s host stack.
1344    pub fn open(runtime: &Runtime, model: &Model, api_key: Option<String>, session_id: &str) -> Result<Lane, String> {
1345        Lane::open_with(runtime, model, api_key, session_id, None)
1346    }
1347
1348    /// [`Lane::open`] whose subagents run as `subagents` says.
1349    pub fn open_with(
1350        runtime: &Runtime,
1351        model: &Model,
1352        api_key: Option<String>,
1353        session_id: &str,
1354        subagents: Option<crate::compose::SubagentHost>,
1355    ) -> Result<Lane, String> {
1356        let stack = runtime.stack_with(model, api_key, session_id, subagents)?;
1357        let tool = Arc::new(stack.rlm(MAIN_LANE)?);
1358        Ok(Lane {
1359            host: stack.host.clone(),
1360            events: stack.events.clone(),
1361            tool,
1362            stack,
1363        })
1364    }
1365
1366    /// The transcript's first message: the system prompt and the declared `rlm` tool.
1367    pub fn system_message(&self, system: &str) -> Option<Message> {
1368        ai::transcript::create_initial_system_message(Some(system), Some(std::slice::from_ref(&self.tool.tool)))
1369            .map(Message::System)
1370    }
1371
1372    /// The model's tool list: exactly the lane's `rlm` tool.
1373    pub fn tools(&self) -> Vec<Arc<dyn AgentTool>> {
1374        vec![self.tool.clone() as Arc<dyn AgentTool>]
1375    }
1376
1377    /// The root lane's kernel, once open.
1378    pub fn kernel(&self) -> Option<Arc<Kernel>> {
1379        self.stack.lanes.kernel(MAIN_LANE)
1380    }
1381
1382    pub fn shutdown(&self) {
1383        self.stack.close();
1384    }
1385
1386    /// Shut down for a successor worker: shell jobs keep running for it.
1387    pub fn hand_over(&self) {
1388        self.stack.hand_over();
1389    }
1390}
1391
1392/// The result of a call whose cell keeps running detached: how its end reaches a lane the host wakes (`woken`: the
1393/// end starts a new turn) or one nothing wakes (the end is reported with a later result; stop it or check on it).
1394pub fn detached_note(cell: &str, woken: bool) -> String {
1395    if woken {
1396        format!(
1397            "Cell {cell} is still running in the background (it waits on the host); its end arrives as a <runtime_event kind=\"cell_done\" id=\"{cell}\">. Do other work or end your turn."
1398        )
1399    } else {
1400        format!(
1401            "Cell {cell} is still running in the background (it waits on the host); its end is reported as a <runtime_event kind=\"cell_done\" id=\"{cell}\"> with a later rlm result, and nothing wakes you after you reply. Do other work meanwhile; `await rlm.cells()` lists it while it runs and `await rlm.cancel(\"{cell}\")` stops it."
1402        )
1403    }
1404}
1405
1406/// The tool result of a cell that ran past its budget and continues in the background (only a woken lane's: see
1407/// [`Rlm::cell_budget`]).
1408pub fn yielded_note(cell: &str, after: Duration) -> String {
1409    format!(
1410        "Cell {cell} was still running after {} s, so it continues in the background; its end (with its result) arrives as a <runtime_event kind=\"cell_done\" id=\"{cell}\">. Do other work or end your turn. Its variables are not in your next cell until it ends (that cell runs in a side lane); `await rlm.cancel(\"{cell}\")` stops it.",
1411        after.as_secs_f64()
1412    )
1413}
1414
1415pub(crate) fn rlm_over(
1416    config: &Config,
1417    lanes: Lanes,
1418    lane: &str,
1419    spill_dir: PathBuf,
1420    hints: Option<Arc<kernel_apis::cell_hints::CellHints>>,
1421    images: Arc<crate::view_images::ViewImages>,
1422    host: Option<Arc<Host>>,
1423) -> Rlm {
1424    let mut tool = rlm_tool();
1425    // `codeSkillsToolSection`: the tool description lists the profile's active code skills.
1426    let listing = kernel_apis::CodeSkills::new(kernel_apis::CodeSkillsOptions::new(
1427        &config.skills_dir,
1428        &config.runtime_path,
1429    ))
1430    .describe();
1431    if !listing.is_empty() {
1432        tool.description = format!("{}\n{listing}", tool.description);
1433    }
1434    Rlm {
1435        tool,
1436        lanes,
1437        lane: lane.to_string(),
1438        masker: config.masker.clone(),
1439        mask_secrets: config.mask_secrets.clone(),
1440        max_bytes: kernel::rlm_output_budget(config.output_bytes.as_deref()) as usize,
1441        spill_dir,
1442        hints,
1443        images,
1444        host,
1445        budget: Arc::new(std::sync::OnceLock::new()),
1446        stats: None,
1447        reminders: None,
1448        wake: crate::wake::RootWake::default(),
1449        yield_after: cell_yield_after(config.cell_yield_after.as_deref()),
1450    }
1451}
1452
1453#[cfg(test)]
1454mod tests {
1455    use super::*;
1456
1457    #[test]
1458    fn cell_yield_after_defaults_to_ten_seconds_and_can_be_turned_off() {
1459        assert_eq!(cell_yield_after(None), Some(Duration::from_secs(10)));
1460        assert_eq!(cell_yield_after(Some("  ")), Some(Duration::from_secs(10)));
1461        assert_eq!(cell_yield_after(Some("2.5")), Some(Duration::from_millis(2500)));
1462        assert_eq!(cell_yield_after(Some("junk")), Some(Duration::from_secs(10)));
1463        for off in ["0", "off", "OFF", "none", "-1", "inf", "NaN"] {
1464            assert_eq!(cell_yield_after(Some(off)), None, "{off}");
1465        }
1466    }
1467
1468    #[test]
1469    fn a_yielded_cell_says_its_end_arrives_as_an_event() {
1470        let note = yielded_note("cell-7", Duration::from_secs(10));
1471        assert!(note.starts_with("Cell cell-7 was still running after 10 s"));
1472        assert!(note.contains("<runtime_event kind=\"cell_done\" id=\"cell-7\">"));
1473        assert!(note.contains("end your turn"));
1474    }
1475}