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