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