Skip to main content

rigspark_runtime/
application.rs

1use crate::{
2    acquire::{Acquisition, HfTransport},
3    adapters::{BackendAdapter, BackendError, BackendKind, RuntimeAdapter, ServeRequest},
4    command::{CommandRunner, NativeCommandRunner},
5    http::{HttpError, NativeTransport, Request, Response, Transport},
6    identity::{NativeProcessProbe, ProcessIdentity},
7    lifecycle::{Activation, Lifecycle, Registry},
8    ollama_installed::{InstalledModels, LocalVerifier, verify_catalog_manifest},
9    process_control::{
10        NativeProcessControl, ProcessControl, listener, resolve_binary, resolve_bitnet_server,
11        same_process,
12    },
13    pull::{PullRequest, PullService},
14    special_adapters::{LmStudioAdapter, MlxAdapter},
15    state::{Config, ServerState, StateStore},
16};
17use rigspark_core::{
18    catalog::{Catalog, CatalogModel, resolve},
19    reports::strip_control,
20    sizing::{Hardware, SizingRequest, evaluate},
21};
22use serde_json::{Value, json};
23use std::{path::PathBuf, time::Duration};
24use tokio_util::sync::CancellationToken;
25
26pub mod events;
27use events::{
28    LifecycleObserver, LifecycleScope, LifecycleStage, LifecycleWarning, ObservedAdapter,
29    download_progress, observe, warning,
30};
31
32pub struct LifecycleOptions {
33    pub command: String,
34    pub model: Option<String>,
35    pub backend: Option<String>,
36    pub port: Option<u16>,
37    pub context: Option<u32>,
38    pub installed: bool,
39    pub bypass: bool,
40    pub cache: crate::cache::CacheFlags,
41}
42impl LifecycleOptions {
43    pub fn validate(&self) -> Result<(), BackendError> {
44        if !self.cache.is_empty() {
45            if !["up", "switch"].contains(&self.command.as_str()) {
46                return Err(BackendError(format!(
47                    "{} does not accept cache options",
48                    self.command
49                )));
50            }
51            if self.installed {
52                return Err(BackendError(
53                    "cache options apply only to a runtime rigspark starts; --installed attaches to a running Ollama".into(),
54                ));
55            }
56            if let Some(profile) = self.cache.over(None) {
57                profile
58                    .validate()
59                    .map_err(|error| BackendError(error.to_string()))?;
60            }
61        }
62        if !["up", "switch", "down", "doctor"].contains(&self.command.as_str())
63            || self.port == Some(0)
64            || self
65                .context
66                .is_some_and(|value| !(1..=10000000).contains(&value))
67            || self
68                .backend
69                .as_ref()
70                .is_some_and(|value| !rigspark_core::catalog::BACKENDS.contains(&value.as_str()))
71        {
72            return Err(BackendError("invalid lifecycle options".into()));
73        }
74        if self.command == "down" || self.command == "doctor" {
75            if (self.command == "doctor" && self.model.is_some())
76                || self.backend.is_some()
77                || self.port.is_some()
78                || self.context.is_some()
79                || self.installed
80                || self.bypass
81            {
82                return Err(BackendError(format!(
83                    "{} does not accept selection options",
84                    self.command
85                )));
86            }
87        } else if self.model.is_none() {
88            return Err(BackendError("model is required".into()));
89        }
90        if let Some(query) = self.model.as_deref() {
91            if query.trim().is_empty() || query.len() > 8192 || query.chars().any(char::is_control)
92            {
93                return Err(BackendError("invalid model reference".into()));
94            }
95            if self.installed {
96                crate::adapters::model_id(query)?;
97            }
98        }
99        if self.installed
100            && (!self.bypass
101                || self
102                    .backend
103                    .as_ref()
104                    .is_some_and(|backend| backend != "ollama"))
105        {
106            return Err(BackendError(
107                "installed models require --bypass and Ollama".into(),
108            ));
109        }
110        Ok(())
111    }
112}
113struct CheckedHttp<'runtime> {
114    inner: &'runtime dyn Transport,
115    probe: &'runtime NativeProcessProbe,
116    expected: ProcessIdentity,
117}
118#[async_trait::async_trait]
119impl Transport for CheckedHttp<'_> {
120    async fn send(&self, request: Request) -> Result<Response, HttpError> {
121        let observed = listener(self.probe, request.url.as_str(), &CancellationToken::new())
122            .await
123            .map_err(|_| HttpError::Invalid)?;
124        if !same_process(&observed.identity, &self.expected) {
125            return Err(HttpError::Invalid);
126        }
127        self.inner.send(request).await
128    }
129}
130struct ContextActivation<'runtime> {
131    source: String,
132    context: Option<u32>,
133    installed: bool,
134    expected_manifest: Option<String>,
135    expected_sha: Option<String>,
136    expected_bytes: Option<u64>,
137    projectors: Vec<rigspark_core::sizing::ProjectorArtifact>,
138    root: PathBuf,
139    http: &'runtime NativeTransport,
140    probe: &'runtime NativeProcessProbe,
141    observer: Option<&'runtime LifecycleObserver>,
142}
143#[async_trait::async_trait]
144impl Activation for ContextActivation<'_> {
145    async fn finalize(
146        &self,
147        handle: &ServerState,
148        cancel: &CancellationToken,
149    ) -> Result<ServerState, BackendError> {
150        let observed = listener(self.probe, &handle.endpoint, cancel).await?;
151        if handle.pid != Some(observed.identity.pid)
152            || handle.process_executable.as_deref() != Some(&observed.identity.executable)
153            || handle.process_started_at.as_deref() != Some(&observed.identity.started)
154        {
155            return Err(BackendError(
156                "Ollama listener changed before activation".into(),
157            ));
158        }
159        let http = CheckedHttp {
160            inner: self.http,
161            probe: self.probe,
162            expected: observed.identity,
163        };
164        let verifier = LocalVerifier {
165            root: self.root.clone(),
166        };
167        let support = InstalledModels::new(&http, &verifier);
168        let model = support
169            .inspect(&handle.endpoint, &self.source, cancel)
170            .await
171            .map_err(|error| BackendError(error.to_string()))?;
172        if self
173            .expected_manifest
174            .as_ref()
175            .is_some_and(|digest| digest != &model.digest)
176        {
177            return Err(BackendError("installed source changed; retry".into()));
178        }
179        observe(
180            self.observer,
181            LifecycleScope::Runtime,
182            LifecycleStage::Verification,
183            async {
184                verify_catalog_manifest(
185                    &self.root,
186                    &model.id,
187                    &model.digest,
188                    self.expected_sha.as_deref(),
189                    self.expected_bytes,
190                    &self.projectors,
191                    cancel,
192                )
193                .await
194                .map_err(|error| BackendError(error.to_string()))
195            },
196        )
197        .await?;
198        let runtime = observe(
199            self.observer,
200            LifecycleScope::Runtime,
201            LifecycleStage::Activation,
202            async {
203                support
204                    .activate(&handle.endpoint, &model, self.context, cancel)
205                    .await
206                    .map_err(|error| BackendError(error.to_string()))
207            },
208        )
209        .await?;
210        let final_model = support
211            .inspect(&handle.endpoint, &self.source, cancel)
212            .await
213            .map_err(|error| BackendError(error.to_string()))?;
214        if final_model.digest != model.digest {
215            return Err(BackendError(
216                "installed source changed before commit".into(),
217            ));
218        }
219        let mut active = handle.clone();
220        active.runtime_model_id = Some(runtime);
221        active.context = self.context;
222        if self.installed {
223            active.integrity = Some("local-manifest".into());
224            active.local_manifest_digest = Some(model.digest);
225        }
226        Ok(active)
227    }
228}
229fn compatible(model: &CatalogModel, backend: &str) -> bool {
230    model.supports_backend(backend)
231}
232fn backend_known(backend: &str) -> bool {
233    rigspark_core::catalog::BACKENDS.contains(&backend)
234}
235/// Index into the resolved runtime binaries: ollama, llama-server, python3, lms, BitNet.
236fn backend_index(backend: &str) -> usize {
237    match backend {
238        "llamacpp" => 1,
239        "mlx" => 2,
240        "lmstudio" => 3,
241        "bitnet" => 4,
242        _ => 0,
243    }
244}
245/// Attach-intent commands follow the active backend; a conflicting override must fail, not be ignored.
246pub fn check_attach_override(
247    command: &str,
248    active: &str,
249    flag: Option<&str>,
250    env: Option<&str>,
251) -> Result<(), BackendError> {
252    if let Some(backend) = flag
253        && backend != active
254    {
255        return Err(BackendError(format!(
256            "{command} cannot change the active backend from {active} to {backend}; use up --backend {backend}"
257        )));
258    }
259    if let Some(backend) = env.map(str::trim).filter(|value| !value.is_empty())
260        && backend != active
261    {
262        return Err(BackendError(format!(
263            "RIGSPARK_BACKEND={} conflicts with the active {active} server; unset it or use up",
264            strip_control(backend)
265        )));
266    }
267    Ok(())
268}
269/// Flag, then non-blank `RIGSPARK_BACKEND`, then the user config default.
270pub fn preferred_backend(
271    flag: Option<&str>,
272    env: Option<&str>,
273    user: Option<&str>,
274) -> Option<String> {
275    flag.or(env.filter(|value| !value.trim().is_empty()))
276        .or(user)
277        .map(str::to_owned)
278}
279/// Backends compatible with the model, in auto-selection order; MLX leads only on Apple Silicon.
280/// Attach-only LM Studio is never auto-selected (spec Q1).
281pub fn auto_backend_order(model: &CatalogModel, hardware: &Hardware) -> Vec<&'static str> {
282    let apple = hardware.platform == rigspark_core::sizing::Platform::Darwin
283        && hardware.arch == rigspark_core::sizing::CpuArch::Arm64;
284    let order: &[&str] = if apple {
285        &["mlx", "ollama", "llamacpp", "bitnet"]
286    } else {
287        &["ollama", "llamacpp", "bitnet"]
288    };
289    order
290        .iter()
291        .copied()
292        .filter(|name| compatible(model, name))
293        .collect()
294}
295pub fn check_backend(
296    model: &CatalogModel,
297    backend: &str,
298    hardware: &Hardware,
299    installed: bool,
300) -> Result<(), BackendError> {
301    if !rigspark_core::catalog::BACKENDS.contains(&backend) {
302        return Err(BackendError("invalid backend selection".into()));
303    }
304    validate_backend_platform(backend, hardware.platform.clone(), hardware.arch.clone())?;
305    if backend == "lmstudio" && model.source.gguf.is_none() && model.source.mlx.is_some() {
306        validate_backend_platform("mlx", hardware.platform.clone(), hardware.arch.clone())?;
307    }
308    if !installed || !compatible(model, backend) {
309        return Err(BackendError(
310            "backend is unavailable or model source is unsupported".into(),
311        ));
312    }
313    Ok(())
314}
315#[derive(Debug, Clone, Copy)]
316pub struct PlanOptions {
317    pub simple_switch: bool,
318    pub bypass: bool,
319    pub context: Option<u32>,
320    /// Size the KV cache at this type; `None` keeps the conservative f16 estimate.
321    pub kv_cache: Option<rigspark_core::sizing::KvCacheType>,
322}
323#[derive(Debug)]
324pub struct QuantPlan {
325    pub quant: rigspark_core::sizing::Quantization,
326    pub estimated_fit: bool,
327}
328/// Picks the quantization to pull and enforces fit, bypass and disk preflight before any side effect.
329pub fn plan_quantization(
330    model: &CatalogModel,
331    explicit: Option<&rigspark_core::sizing::Quantization>,
332    backend: &str,
333    hardware: &Hardware,
334    options: PlanOptions,
335) -> Result<QuantPlan, BackendError> {
336    if options.simple_switch && backend != "ollama" {
337        return Err(BackendError(
338            "single-model and delegated runtimes require up to replace models".into(),
339        ));
340    }
341    if backend == "bitnet" {
342        if !model.supports_backend("bitnet") {
343            return Err(BackendError("BitNet requires an I2_S GGUF artifact".into()));
344        }
345        if options.context.is_some_and(|context| {
346            context == 0 || f64::from(context) > model.context_length.min(4096.0)
347        }) {
348            return Err(BackendError(
349                "BitNet context exceeds the model's supported range".into(),
350            ));
351        }
352    }
353    if options.context.is_some() && !["ollama", "bitnet"].contains(&backend) {
354        return Err(BackendError(
355            "explicit runtime context currently requires Ollama".into(),
356        ));
357    }
358    let mut sizing = match options.kv_cache {
359        Some(kind) => model
360            .with_kv_cache(kind)
361            .map_err(|error| BackendError(error.to_string()))?
362            .sizing(),
363        None => model.sizing(),
364    };
365    if let Some(quant) = explicit {
366        sizing.quantizations = vec![quant.clone()];
367    }
368    let fit = evaluate(&SizingRequest {
369        model: sizing,
370        hardware: hardware.clone(),
371        context: options.context.map(f64::from),
372    })
373    .map_err(|error| BackendError(error.to_string()))?;
374    if !options.simple_switch
375        && explicit.is_none()
376        && backend != "lmstudio"
377        && fit.fit.reason == Some("disk-bound")
378    {
379        return Err(BackendError("insufficient disk space".into()));
380    }
381    let quant = if options.simple_switch {
382        explicit.or_else(|| model.quantizations.first()).cloned()
383    } else {
384        explicit.cloned().or(fit.fit.quant.clone()).or_else(|| {
385            if options.bypass {
386                model
387                    .quantizations
388                    .iter()
389                    .min_by(|left, right| left.disk_bytes.total_cmp(&right.disk_bytes))
390                    .cloned()
391            } else {
392                None
393            }
394        })
395    }
396    .ok_or_else(|| {
397        BackendError("model does not fit; use --bypass to override estimated fit".into())
398    })?;
399    if !options.simple_switch
400        && backend != "lmstudio"
401        && quant.disk_bytes > hardware.free_disk_bytes
402    {
403        return Err(BackendError("insufficient disk space".into()));
404    }
405    if !options.simple_switch
406        && !fit.fit.fits
407        && !options.bypass
408        && (options.context.is_some() || explicit.is_none())
409    {
410        return Err(BackendError(
411            "model does not fit requested context; use --bypass".into(),
412        ));
413    }
414    Ok(QuantPlan {
415        quant,
416        estimated_fit: !options.simple_switch && !fit.fit.fits,
417    })
418}
419fn catalog_pull_request(
420    model: &CatalogModel,
421    quant: &rigspark_core::sizing::Quantization,
422    backend: &str,
423) -> Result<PullRequest, BackendError> {
424    Ok(PullRequest {
425        backend: backend.into(),
426        model_id: if backend == "ollama" {
427            model
428                .source
429                .ollama
430                .clone()
431                .ok_or_else(|| BackendError("missing Ollama source".into()))?
432        } else {
433            model.id.clone()
434        },
435        expected_bytes: quant.disk_bytes as u64,
436        expected_sha256: quant.sha256.clone(),
437        projectors: quant.projectors.clone(),
438        gguf: model.source.gguf.clone(),
439        mlx: model.source.mlx.clone(),
440    })
441}
442pub fn validate_backend_platform(
443    backend: &str,
444    platform: rigspark_core::sizing::Platform,
445    arch: rigspark_core::sizing::CpuArch,
446) -> Result<(), BackendError> {
447    if backend == "mlx"
448        && !(platform == rigspark_core::sizing::Platform::Darwin
449            && arch == rigspark_core::sizing::CpuArch::Arm64)
450    {
451        return Err(BackendError(
452            "MLX requires Apple Silicon (darwin/arm64)".into(),
453        ));
454    }
455    Ok(())
456}
457pub(crate) fn studio_trust(home: &std::path::Path) -> Vec<PathBuf> {
458    let paths = if cfg!(target_os = "macos") {
459        vec![
460            PathBuf::from("/Applications/LM Studio.app/Contents/MacOS/LM Studio"),
461            home.join("Applications/LM Studio.app/Contents/MacOS/LM Studio"),
462        ]
463    } else if cfg!(windows) {
464        let mut paths = vec![
465            PathBuf::from("C:\\Program Files\\LM Studio\\LM Studio.exe"),
466            PathBuf::from("C:\\Program Files\\LM Studio\\llmster.exe"),
467        ];
468        if let Some(local) = std::env::var_os("LOCALAPPDATA") {
469            paths.extend([
470                PathBuf::from(&local).join("Programs/LM Studio/LM Studio.exe"),
471                PathBuf::from(local).join("Programs/LM Studio/llmster.exe"),
472            ]);
473        }
474        paths
475    } else {
476        vec![
477            PathBuf::from("/usr/bin/llmster"),
478            PathBuf::from("/usr/local/bin/llmster"),
479            PathBuf::from("/opt/lm-studio/bin/llmster"),
480        ]
481    };
482    paths
483        .into_iter()
484        .map(|path| path.canonicalize().unwrap_or(path))
485        .collect()
486}
487pub async fn run_native(
488    options: &LifecycleOptions,
489    catalog: &Catalog,
490    hardware: Option<&Hardware>,
491    cancel: &CancellationToken,
492) -> Result<(Value, String), BackendError> {
493    run_native_observed(options, catalog, hardware, cancel, None).await
494}
495pub async fn run_native_observed(
496    options: &LifecycleOptions,
497    catalog: &Catalog,
498    hardware: Option<&Hardware>,
499    cancel: &CancellationToken,
500    observer: Option<&LifecycleObserver>,
501) -> Result<(Value, String), BackendError> {
502    let config = Config::load().map_err(|error| BackendError(error.to_string()))?;
503    run_native_with_config_observed(options, catalog, hardware, cancel, config, observer).await
504}
505/// `down --forget`: clears a stale attached pointer without probing or signalling any process.
506pub async fn forget_attached_with_config(
507    config: Config,
508    cancel: &CancellationToken,
509) -> Result<(Value, String), BackendError> {
510    let store = StateStore::new(config);
511    let registry = Registry::new(Vec::new());
512    let lifecycle = Lifecycle {
513        store: &store,
514        registry: &registry,
515        probe: &NativeProcessProbe,
516    };
517    Ok(match lifecycle.forget_attached(cancel).await? {
518        None => (
519            json!({"type":"no-active"}),
520            "No active server to forget.\n".into(),
521        ),
522        Some(active) => (
523            json!({"type":"forgotten","modelId":active.model_id,"endpoint":active.endpoint}),
524            format!(
525                "Forgot {} ({}); no process was signalled.\n",
526                strip_control(&active.model_id),
527                active.endpoint
528            ),
529        ),
530    })
531}
532pub async fn run_native_with_config(
533    options: &LifecycleOptions,
534    catalog: &Catalog,
535    hardware: Option<&Hardware>,
536    cancel: &CancellationToken,
537    config: Config,
538) -> Result<(Value, String), BackendError> {
539    run_native_with_config_observed(options, catalog, hardware, cancel, config, None).await
540}
541pub async fn run_native_with_config_observed(
542    options: &LifecycleOptions,
543    catalog: &Catalog,
544    hardware: Option<&Hardware>,
545    cancel: &CancellationToken,
546    config: Config,
547    observer: Option<&LifecycleObserver>,
548) -> Result<(Value, String), BackendError> {
549    options.validate()?;
550    let observer = observer.filter(|_| options.command != "doctor");
551    let store = StateStore::new(config.clone());
552    let prior = store
553        .read()
554        .map_err(|error| BackendError(error.to_string()))?;
555    if options.command == "switch" {
556        let active = prior
557            .active
558            .as_ref()
559            .ok_or_else(|| BackendError("no active server to switch; run up first".into()))?;
560        check_attach_override(
561            "switch",
562            &active.backend,
563            options.backend.as_deref(),
564            std::env::var("RIGSPARK_BACKEND").ok().as_deref(),
565        )?;
566        if options.context.is_none()
567            && !options.bypass
568            && let Some(port) = options.port
569            && port != active.port
570        {
571            return Err(BackendError(format!(
572                "switch without --context or --bypass cannot change the active port; use up --port {port}"
573            )));
574        }
575    }
576    if options.command == "down"
577        && let Some(active) = &prior.active
578    {
579        check_attach_override(
580            "down",
581            &active.backend,
582            None,
583            std::env::var("RIGSPARK_BACKEND").ok().as_deref(),
584        )?;
585    }
586    let home = std::env::var_os("HOME")
587        .or_else(|| std::env::var_os("USERPROFILE"))
588        .map(PathBuf::from)
589        .ok_or_else(|| BackendError("home unavailable".into()))?;
590    let bitnet_path = resolve_bitnet_server();
591    if ["down", "doctor"].contains(&options.command.as_str())
592        && prior
593            .active
594            .as_ref()
595            .is_some_and(|active| active.backend == "bitnet")
596    {
597        bitnet_path
598            .as_ref()
599            .map_err(|error| BackendError(error.clone()))?;
600    }
601    let mut paths = ["ollama", "llama-server", "python3", "lms"]
602        .map(|name| resolve_binary(name).ok())
603        .to_vec();
604    paths.push(bitnet_path.as_ref().ok().cloned());
605    let binary = |index: usize| {
606        paths[index]
607            .clone()
608            .unwrap_or_else(|| config.home.join(".unavailable").join(index.to_string()))
609    };
610    let http = NativeTransport::new().map_err(|error| BackendError(error.to_string()))?;
611    let probe = NativeProcessProbe;
612    let control = NativeProcessControl;
613    let commands = NativeCommandRunner;
614    let ollama_root = std::env::var_os("OLLAMA_MODELS")
615        .map(PathBuf::from)
616        .unwrap_or_else(|| home.join(".ollama/models"));
617    let ollama = RuntimeAdapter::new(BackendKind::Ollama, binary(0), &http, &probe, &control)
618        .with_ollama_models(ollama_root.clone())?;
619    let llama = RuntimeAdapter::new(BackendKind::LlamaCpp, binary(1), &http, &probe, &control);
620    let bitnet = RuntimeAdapter::new(BackendKind::BitNet, binary(4), &http, &probe, &control);
621    let mlx = MlxAdapter {
622        binary: binary(2),
623        http: &http,
624        probe: &probe,
625        control: &control,
626        commands: &commands,
627        token: None,
628    };
629    let studio = LmStudioAdapter {
630        binary: binary(3),
631        trusted_executables: studio_trust(&home),
632        http: &http,
633        probe: &probe,
634        commands: &commands,
635        token: std::env::var("LM_API_TOKEN").ok(),
636    };
637    let acquisition_daemon =
638        ObservedAdapter::new(&ollama, observer, LifecycleScope::AcquisitionDaemon);
639    let ollama = ObservedAdapter::new(&ollama, observer, LifecycleScope::Runtime);
640    let llama = ObservedAdapter::new(&llama, observer, LifecycleScope::Runtime);
641    let mlx = ObservedAdapter::new(&mlx, observer, LifecycleScope::Runtime);
642    let studio = ObservedAdapter::new(&studio, observer, LifecycleScope::Runtime);
643    let bitnet = ObservedAdapter::new(&bitnet, observer, LifecycleScope::Runtime);
644    let registry = Registry::new(vec![&ollama, &llama, &mlx, &studio, &bitnet]);
645    let lifecycle = Lifecycle {
646        store: &store,
647        registry: &registry,
648        probe: &probe,
649    };
650    if options.command == "doctor" {
651        let Some(active) = prior.active else {
652            return Ok((
653                json!({"name":"state","status":"ok","detail":"no active server recorded"}),
654                String::new(),
655            ));
656        };
657        let model = catalog
658            .models
659            .iter()
660            .find(|model| model.id == active.model_id);
661        let path = if active.backend == "mlx" {
662            let source = model
663                .and_then(|model| model.source.mlx.as_ref())
664                .ok_or_else(|| BackendError("active MLX source unavailable".into()))?;
665            let (owner, name) = source
666                .repo
667                .split_once('/')
668                .ok_or_else(|| BackendError("invalid source".into()))?;
669            Some(
670                config
671                    .home
672                    .join("cache/mlx")
673                    .join(owner)
674                    .join(format!("{name}@{}", source.revision)),
675            )
676        } else if ["llamacpp", "bitnet"].contains(&active.backend.as_str()) {
677            let source = model
678                .and_then(|model| model.source.gguf.as_ref())
679                .ok_or_else(|| BackendError("active GGUF source unavailable".into()))?;
680            let (owner, name) = source
681                .repo
682                .split_once('/')
683                .ok_or_else(|| BackendError("invalid source".into()))?;
684            Some(
685                config
686                    .home
687                    .join("cache")
688                    .join(&active.backend)
689                    .join(owner)
690                    .join(format!("{name}@{}", source.revision))
691                    .join(&source.file),
692            )
693        } else {
694            active.model_path.as_ref().map(PathBuf::from)
695        };
696        let request = ServeRequest {
697            model_id: active.model_id.clone(),
698            endpoint: active.endpoint.clone(),
699            model_path: path,
700            context: None,
701            cache: None,
702        };
703        lifecycle.health(&active, &request, cancel).await?;
704        return Ok((
705            json!({"name":"state","status":"ok","detail":format!("serving {} at {}",strip_control(&active.model_id),active.endpoint)}),
706            String::new(),
707        ));
708    }
709    if options.command == "down" {
710        let stopped = lifecycle
711            .down_with_target(cancel, || {
712                options
713                    .model
714                    .as_deref()
715                    .map(|query| {
716                        resolve(catalog, query)
717                            .map(|resolved| resolved.model.id.clone())
718                            .map_err(|error| BackendError(error.message))
719                    })
720                    .transpose()
721            })
722            .await?;
723        let Some(active) = stopped else {
724            return Ok((
725                json!({"type":"no-active"}),
726                "No active server to stop.\n".into(),
727            ));
728        };
729        return Ok((
730            json!({"type":if active.owned_by_us{"stopped"}else{"detached"},"modelId":active.model_id,"endpoint":active.endpoint}),
731            if active.owned_by_us {
732                format!(
733                    "Stopped {} ({}).\n",
734                    strip_control(&active.model_id),
735                    active.endpoint
736                )
737            } else {
738                format!(
739                    "Detached from {} ({}); it was not started by rigspark and is still running.\n",
740                    strip_control(&active.model_id),
741                    active.endpoint
742                )
743            },
744        ));
745    }
746    let query = options
747        .model
748        .as_deref()
749        .ok_or_else(|| BackendError("model required".into()))?;
750    let installed_fallback = options.bypass
751        && resolve(catalog, query).is_err_and(|error| error.code == "MODEL_RESOLUTION_ERROR");
752    if options.installed || installed_fallback {
753        warning(observer, LifecycleWarning::InstalledBypass);
754        if options
755            .backend
756            .as_ref()
757            .is_some_and(|backend| backend != "ollama")
758        {
759            return Err(BackendError(
760                "installed model bypass requires Ollama".into(),
761            ));
762        }
763        let port = options
764            .port
765            .or_else(|| {
766                prior
767                    .active
768                    .as_ref()
769                    .filter(|active| active.backend == "ollama")
770                    .map(|active| active.port)
771            })
772            .unwrap_or(11434);
773        let endpoint = format!("http://127.0.0.1:{port}");
774        let reviewed = lifecycle.review(query, cancel).await?;
775        if !control.occupied(&endpoint).await? {
776            return Err(BackendError(
777                "installed activation requires an existing Ollama daemon".into(),
778            ));
779        }
780        let observed = listener(&probe, &endpoint, cancel).await?;
781        if !ollama.trusts(&observed.identity) {
782            return Err(BackendError("untrusted Ollama daemon".into()));
783        }
784        let checked = CheckedHttp {
785            inner: &http,
786            probe: &probe,
787            expected: observed.identity,
788        };
789        let verifier = LocalVerifier {
790            root: ollama_root.clone(),
791        };
792        let support = InstalledModels::new(&checked, &verifier);
793        let model = support
794            .inspect(&endpoint, query, cancel)
795            .await
796            .map_err(|error| BackendError(error.to_string()))?;
797        let catalog_quant = catalog
798            .models
799            .iter()
800            .find(|entry| entry.source.ollama.as_deref() == Some(model.id.as_str()))
801            .and_then(|entry| {
802                entry
803                    .quantizations
804                    .iter()
805                    .find(|quant| Some(&quant.name) == model.quant.as_ref())
806                    .or_else(|| entry.quantizations.first())
807            });
808        let activation = ContextActivation {
809            source: model.id.clone(),
810            context: options.context,
811            installed: true,
812            expected_manifest: Some(model.digest),
813            expected_sha: catalog_quant.and_then(|quant| quant.sha256.clone()),
814            expected_bytes: catalog_quant.map(|quant| quant.disk_bytes as u64),
815            projectors: catalog_quant
816                .map(|quant| quant.projectors.clone())
817                .unwrap_or_default(),
818            root: ollama_root,
819            http: &http,
820            probe: &probe,
821            observer,
822        };
823        let request = ServeRequest {
824            model_id: model.id,
825            endpoint,
826            model_path: None,
827            context: options.context,
828            cache: options.cache.over(None),
829        };
830        let active = lifecycle
831            .attach_installed(&request, &reviewed, cancel, &activation)
832            .await?;
833        return Ok(up_output(&active, "local-manifest"));
834    }
835    let resolved = resolve(catalog, query).map_err(|error| BackendError(error.message))?;
836    let model = resolved.model;
837    // A switch keeps the running profile unless a flag overrides part of it.
838    let prior_cache = prior.active.as_ref().and_then(|active| active.cache);
839    let cache_kept = options.command == "switch"
840        && crate::cache::requested(options.cache, true, prior_cache, None) == prior_cache;
841    if options.command == "switch"
842        && prior
843            .active
844            .as_ref()
845            .is_some_and(|active| active.model_id == model.id)
846        && options.context.is_none()
847        && !options.bypass
848        && cache_kept
849    {
850        let active = prior
851            .active
852            .as_ref()
853            .ok_or_else(|| BackendError("no active model".into()))?;
854        return Ok((
855            json!({"type":"already-active","modelId":model.id,"endpoint":active.endpoint}),
856            format!("{} is already active.\n", model.id),
857        ));
858    }
859    let hardware =
860        hardware.ok_or_else(|| BackendError("hardware required for model selection".into()))?;
861    let simple_switch = options.command == "switch"
862        && options.context.is_none()
863        && !options.bypass
864        && cache_kept
865        && prior
866            .active
867            .as_ref()
868            .is_none_or(|active| active.backend != "bitnet");
869    let env_backend = std::env::var("RIGSPARK_BACKEND").ok();
870    let user = config
871        .user_config()
872        .map_err(|error| BackendError(error.to_string()))?;
873    let requested = crate::cache::requested(
874        options.cache,
875        options.command == "switch",
876        prior_cache,
877        user.cache,
878    );
879    let user_backend = user.default_backend;
880    let configured = preferred_backend(
881        options.backend.as_deref(),
882        env_backend.as_deref(),
883        user_backend.as_deref(),
884    );
885    let backend = if options.command == "switch" {
886        prior
887            .active
888            .as_ref()
889            .ok_or_else(|| BackendError("no active model".into()))?
890            .backend
891            .clone()
892    } else if let Some(backend) = configured {
893        backend
894    } else {
895        let mut selected = None;
896        for name in auto_backend_order(model, hardware) {
897            if name == "bitnet" {
898                bitnet_path
899                    .as_ref()
900                    .map_err(|error| BackendError(error.clone()))?;
901            }
902            let index = backend_index(name);
903            if paths[index].is_some() {
904                let args = if name == "mlx" {
905                    vec![
906                        "-I".into(),
907                        "-c".into(),
908                        "import importlib.metadata; print(importlib.metadata.version('mlx-lm'))"
909                            .into(),
910                    ]
911                } else {
912                    vec!["--version".into()]
913                };
914                if let Ok(version) = commands
915                    .run(&binary(index), &args, cancel, Duration::from_secs(5))
916                    .await
917                    && (name != "mlx" || version.trim() == "0.31.3")
918                {
919                    selected = Some(name.to_owned());
920                    break;
921                }
922            }
923        }
924        selected.ok_or_else(|| BackendError("no installed backend supports this model".into()))?
925    };
926    if backend == "bitnet" {
927        bitnet_path
928            .as_ref()
929            .map_err(|error| BackendError(error.clone()))?;
930    }
931    check_backend(
932        model,
933        &backend,
934        hardware,
935        backend_known(&backend) && paths[backend_index(&backend)].is_some(),
936    )?;
937    let index = backend_index(&backend);
938    crate::cache::launch_delta(requested.as_ref(), &backend, true)
939        .map_err(|error| BackendError(error.to_string()))?;
940    let plan = plan_quantization(
941        model,
942        resolved.quant,
943        &backend,
944        hardware,
945        PlanOptions {
946            simple_switch,
947            bypass: options.bypass,
948            context: options.context,
949            kv_cache: requested
950                .filter(|profile| profile.kv_k == profile.kv_v)
951                .map(|profile| profile.kv_k),
952        },
953    )?;
954    let quant = plan.quant;
955    let reviewed = lifecycle.review(&model.id, cancel).await?;
956    let pull_request = catalog_pull_request(model, &quant, &backend)?;
957    if plan.estimated_fit {
958        warning(observer, LifecycleWarning::EstimatedFit);
959    }
960    let diagnostics = observer.and_then(|observer| observer.diagnostics.clone());
961    let acquisition = Acquisition::new(config.home.join("cache"))?.with_progress(
962        move |completed, total, file| {
963            download_progress(diagnostics.as_ref(), completed, total, file)
964        },
965    );
966    let download = HfTransport::new()?;
967    let studio_root = home.join(".lmstudio/models");
968    let pulls = PullService {
969        acquisition: &acquisition,
970        download: &download,
971        commands: &commands,
972        ollama_models: &ollama_root,
973        studio_models: &studio_root,
974    };
975    let port = options
976        .port
977        .or_else(|| {
978            if options.command == "switch" {
979                prior.active.as_ref().map(|active| active.port)
980            } else {
981                None
982            }
983        })
984        .unwrap_or(match backend.as_str() {
985            "ollama" => 11434,
986            "lmstudio" => 1234,
987            _ => 8080,
988        });
989    let endpoint = format!("http://127.0.0.1:{port}");
990    let pull_binary = binary(index);
991    let pull = pulls.pull_at_observed(&pull_request, &pull_binary, &endpoint, cancel, observer);
992    let prepared = if backend == "ollama" {
993        crate::pull::with_ollama_daemon(&acquisition_daemon, &endpoint, cancel, pull).await?
994    } else {
995        pull.await?
996    };
997    if !prepared.digest_verified {
998        warning(observer, LifecycleWarning::SizeOnly);
999    }
1000    if simple_switch {
1001        let active = lifecycle
1002            .switch_pointer(&model.id, &reviewed, cancel)
1003            .await?;
1004        return Ok((
1005            json!({"type":"switched","modelId":active.model_id,"endpoint":active.endpoint}),
1006            format!("Switched to {} ({}).\n", active.model_id, active.endpoint),
1007        ));
1008    }
1009    let request = ServeRequest {
1010        model_id: model.id.clone(),
1011        endpoint,
1012        model_path: prepared.model_path,
1013        context: if backend == "bitnet" {
1014            Some(
1015                options
1016                    .context
1017                    .unwrap_or(model.context_length.min(4096.0) as u32),
1018            )
1019        } else {
1020            options.context
1021        },
1022        cache: requested,
1023    };
1024    let active = if options.context.is_some() && backend == "ollama" {
1025        let activation = ContextActivation {
1026            source: pull_request.model_id,
1027            context: options.context,
1028            installed: false,
1029            expected_manifest: prepared.local_manifest_digest,
1030            expected_sha: quant.sha256.clone(),
1031            expected_bytes: Some(quant.disk_bytes as u64),
1032            projectors: quant.projectors.clone(),
1033            root: ollama_root,
1034            http: &http,
1035            probe: &probe,
1036            observer,
1037        };
1038        lifecycle
1039            .replace_with(&backend, &request, &reviewed, cancel, &activation)
1040            .await?
1041    } else {
1042        lifecycle
1043            .replace(&backend, &request, &reviewed, cancel)
1044            .await?
1045    };
1046    Ok(up_output(
1047        &active,
1048        if prepared.digest_verified {
1049            "verified"
1050        } else {
1051            "size-only"
1052        },
1053    ))
1054}
1055fn up_output(active: &ServerState, integrity: &str) -> (Value, String) {
1056    let mut report = json!({"modelId":active.model_id,"backend":active.backend,"endpoint":active.endpoint,"ownership":if active.owned_by_us{"owned"}else{"attached"},"integrity":integrity});
1057    let mut text = format!(
1058        "{} ready at {}\n",
1059        strip_control(&active.model_id),
1060        active.endpoint
1061    );
1062    if let Some(runtime) = &active.runtime_model_id {
1063        text.push_str(&format!("Runtime model: {}", strip_control(runtime)));
1064        if let Some(context) = active.context {
1065            text.push_str(&format!(" (context {context})"));
1066        }
1067        text.push('\n');
1068    }
1069    if let Some(cache) = &active.cache {
1070        report["cache"] = json!(cache);
1071        text.push_str(&format!("Cache: {}\n", cache.summary()));
1072    }
1073    (report, text)
1074}
1075
1076pub async fn installed_inventory(
1077    hardware: &Hardware,
1078    model: Option<&str>,
1079    port: u16,
1080    context: Option<u32>,
1081    fits_only: bool,
1082    cancel: &CancellationToken,
1083) -> Result<(Value, String, u8), BackendError> {
1084    if port == 0 || context.is_some_and(|context| !(1..=10000000).contains(&context)) {
1085        return Err(BackendError("invalid installed comparison options".into()));
1086    }
1087    let binary = resolve_binary("ollama")?;
1088    let endpoint = format!("http://127.0.0.1:{port}");
1089    let http = NativeTransport::new().map_err(|error| BackendError(error.to_string()))?;
1090    let probe = NativeProcessProbe;
1091    let before = listener(&probe, &endpoint, cancel).await?;
1092    if binary.to_str() != Some(before.identity.executable.as_str()) {
1093        return Err(BackendError(
1094            "untrusted installed inventory listener".into(),
1095        ));
1096    }
1097    let checked = CheckedHttp {
1098        inner: &http,
1099        probe: &probe,
1100        expected: before.identity.clone(),
1101    };
1102    let root = std::env::var_os("OLLAMA_MODELS")
1103        .map(PathBuf::from)
1104        .unwrap_or_else(|| {
1105            std::env::var_os("HOME")
1106                .or_else(|| std::env::var_os("USERPROFILE"))
1107                .map(PathBuf::from)
1108                .unwrap_or_default()
1109                .join(".ollama/models")
1110        });
1111    let verifier = LocalVerifier { root };
1112    let support = InstalledModels::new(&checked, &verifier);
1113    let models = if let Some(model) = model {
1114        vec![
1115            support
1116                .inspect(&endpoint, model, cancel)
1117                .await
1118                .map_err(|error| BackendError(error.to_string()))?,
1119        ]
1120    } else {
1121        let mut models = Vec::new();
1122        for entry in support
1123            .list(&endpoint, cancel)
1124            .await
1125            .map_err(|error| BackendError(error.to_string()))?
1126        {
1127            models.push(
1128                support
1129                    .inspect(&endpoint, &entry.id, cancel)
1130                    .await
1131                    .map_err(|error| BackendError(error.to_string()))?,
1132            );
1133        }
1134        models
1135    };
1136    let mut results = Vec::new();
1137    let mut lines = Vec::new();
1138    for entry in models {
1139        let sized = crate::ollama_installed::size_installed(&entry, hardware, context)
1140            .map_err(|error| BackendError(error.to_string()))?;
1141        if fits_only && sized["fit"] != "yes" {
1142            continue;
1143        }
1144        lines.push(format!(
1145            "{}: context {}; estimated {} fit {}; weights {:.2} GiB ({}); throughput unknown",
1146            strip_control(&entry.id),
1147            context
1148                .map(|value| value.to_string())
1149                .unwrap_or_else(|| "default".into()),
1150            sized["memoryKind"].as_str().unwrap_or("ram"),
1151            sized["fit"].as_str().unwrap_or("unknown"),
1152            entry.size_bytes as f64 / 1073741824.0,
1153            if sized["weightsFit"] == true {
1154                "fit"
1155            } else {
1156                "over budget"
1157            }
1158        ));
1159        results.push(sized);
1160    }
1161    let after = listener(&probe, &endpoint, cancel).await?;
1162    if !same_process(&before.identity, &after.identity) {
1163        return Err(BackendError("inventory listener changed".into()));
1164    }
1165    let exit =
1166        u8::from(model.is_some() && results.first().is_some_and(|result| result["fit"] == "no"));
1167    Ok((
1168        json!({"source":"local-runtime-metadata","models":results}),
1169        format!(
1170            "{}\n",
1171            if lines.is_empty() {
1172                "No installed models match.".into()
1173            } else {
1174                lines.join("\n")
1175            }
1176        ),
1177        exit,
1178    ))
1179}
1180
1181#[cfg(test)]
1182mod acquisition_contract_tests {
1183    use super::*;
1184
1185    #[test]
1186    fn catalog_pull_preserves_quant_digest_size_and_runtime_model_id() {
1187        let mut catalog = Catalog::parse(rigspark_core::MODELS_JSON).unwrap();
1188        let model = catalog
1189            .models
1190            .iter_mut()
1191            .find(|model| model.source.ollama.is_some())
1192            .unwrap();
1193        model.quantizations[0].sha256 = Some("b".repeat(64));
1194        model.quantizations[0].disk_bytes = 5_000_000_000.0;
1195        let id = model.id.clone();
1196        let quant_query = format!("{id}-{}", model.quantizations[0].name);
1197        for query in [&id, &quant_query] {
1198            let resolved = resolve(&catalog, query).unwrap();
1199            let quant = resolved.quant.unwrap_or(&resolved.model.quantizations[0]);
1200            let request = catalog_pull_request(resolved.model, quant, "ollama").unwrap();
1201            assert_eq!(request.expected_sha256, Some("b".repeat(64)));
1202            assert_eq!(request.expected_bytes, 5_000_000_000);
1203            assert_eq!(Some(request.model_id), resolved.model.source.ollama);
1204        }
1205        let model = &mut catalog.models[0];
1206        model.source.ollama = None;
1207        assert!(catalog_pull_request(model, &model.quantizations[0], "ollama").is_err());
1208    }
1209
1210    #[test]
1211    fn success_lines_strip_controls_and_report_integrity_and_ownership() {
1212        let active = ServerState {
1213            backend: "ollama".into(),
1214            model_id: "evil\u{1b}[31m\nid".into(),
1215            endpoint: "http://127.0.0.1:11434".into(),
1216            port: 11434,
1217            owned_by_us: true,
1218            pid: Some(7),
1219            runtime_model_id: Some("variant\u{7}".into()),
1220            context: Some(65_536),
1221            integrity: None,
1222            local_manifest_digest: None,
1223            model_path: None,
1224            process_executable: None,
1225            process_started_at: None,
1226            auth_token: None,
1227            cache: None,
1228        };
1229        let (report, text) = up_output(&active, "size-only");
1230        assert_eq!(
1231            (report["ownership"].as_str(), report["integrity"].as_str()),
1232            (Some("owned"), Some("size-only"))
1233        );
1234        assert!(
1235            !text
1236                .chars()
1237                .any(|character| character.is_control() && character != '\n'),
1238            "{text:?}"
1239        );
1240        assert_eq!(text.lines().count(), 2, "{text:?}");
1241        assert!(text.ends_with("(context 65536)\n"));
1242    }
1243}