offgrid-ai 0.9.6 → 0.10.1

package/src/benchmark.mjs

@@ -6,5 +6,7 @@ export { findBenchmarkRepo, linkBenchmarkRepo } from "./benchmark/repo.mjs";
 export { prepareBenchmarkRun } from "./benchmark/prepare.mjs";
 export { runBenchmarkInPi } from "./benchmark/pi-runner.mjs";
 export { queryServerMetrics } from "./benchmark/metrics.mjs";
-export { unloadModelFromServer, finalizeBenchmarkRun, renderBenchmarkSummary } from "./benchmark/finalize.mjs";
+// unloadModelFromServer now lives in src/process.mjs (managed-server counterpart to stopProfile).
+export { unloadModelFromServer } from "./process.mjs";
+export { finalizeBenchmarkRun, renderBenchmarkSummary } from "./benchmark/finalize.mjs";
 export { benchmarkForProfile, benchmarkFlow } from "./benchmark/flow.mjs";

package/src/commands/main.mjs

@@ -1,10 +1,11 @@
 import { findLlamaServer, ensureDirs } from "../config.mjs";
 import { backendFor } from "../backends.mjs";
 import { scanGgufModels } from "../scan.mjs";
+import { scanMlxModels } from "../mlx-discovery.mjs";
 import { loadProfiles } from "../profiles.mjs";
 import { hasPi } from "../harness-pi.mjs";
 import { offerManagedLlamaRuntimeUpdate } from "../runtime.mjs";
-import { hasLmStudioInstalled, hasOllamaInstalled, hasOmlxInstalled, scanManagedModels } from "../managed.mjs";
+import { hasLmStudioInstalled, hasOmlxInstalled, scanManagedModels } from "../managed.mjs";
 import { recommendedModel } from "../recommendations.mjs";
 import { pc, startInteractive, createPrompt } from "../ui.mjs";
 import { onboardFlow } from "./onboard.mjs";
@@ -26,9 +27,10 @@ export async function mainFlow() {
   const llamaBinary = await findLlamaServer();
   const { models: ggufModels, drafters } = await scanGgufModels();
   const managedModels = await scanManagedModels();
+  const mlxModels = await scanMlxModels();
   const profiles = await loadProfiles();
   const hasAnyBackend = llamaBinary || managedModels.some((item) => item.status === "ok" && item.models.length > 0);
-  const hasAnyModels = ggufModels.length > 0 || managedModels.some((item) => item.status === "ok" && item.models.length > 0);
+  const hasAnyModels = ggufModels.length > 0 || mlxModels.length > 0 || managedModels.some((item) => item.status === "ok" && item.models.length > 0);
 
   const piInstalled = await hasPi();
   const needsLlama = ggufModels.length > 0 || profiles.some((profile) => backendFor(profile.backend).type === "local-server");
@@ -56,16 +58,16 @@ export async function mainFlow() {
   if (!process.stdin.isTTY) return await statusCommand();
 
   startInteractive("offgrid-ai");
-  return await modelCommandCenter({ profiles, ggufModels, managedModels, drafters });
+  return await modelCommandCenter({ profiles, ggufModels, managedModels, mlxModels, drafters });
 }
 
 async function printNoModelsHelp(llamaBinary) {
   console.log(pc.yellow("No models found."));
   console.log(pc.dim("You need to download a model to use offgrid-ai.\n"));
 
-  const [ollamaInstalled, omlxInstalled] = await Promise.all([hasOllamaInstalled(), hasOmlxInstalled()]);
+  const omlxInstalled = await hasOmlxInstalled();
   const lmStudioInstalled = hasLmStudioInstalled();
-  const hasBackends = llamaBinary || ollamaInstalled || omlxInstalled || lmStudioInstalled;
+  const hasBackends = llamaBinary || omlxInstalled || lmStudioInstalled;
   if (!hasBackends) {
     console.log(pc.dim("Run offgrid-ai to install a backend and download a model."));
     return;
@@ -73,7 +75,6 @@ async function printNoModelsHelp(llamaBinary) {
 
   console.log(pc.bold("Backend status:"));
   console.log(`  ${lmStudioInstalled ? pc.green("✓") : pc.red("✗")} LM Studio ${lmStudioInstalled ? "— installed" : "— not installed"}`);
-  console.log(`  ${ollamaInstalled ? pc.green("✓") : pc.red("✗")} Ollama ${ollamaInstalled ? "— installed" : "— not installed"}`);
   console.log(`  ${omlxInstalled ? pc.green("✓") : pc.red("✗")} oMLX ${omlxInstalled ? "— installed" : "— not installed"}`);
   console.log(`  ${llamaBinary ? pc.green("✓") : pc.red("✗")} llama-server ${llamaBinary ? "— installed" : "— not installed"}`);
   console.log();
@@ -84,6 +85,5 @@ async function printNoModelsHelp(llamaBinary) {
     console.log("  Open LM Studio → browse models → download");
     console.log(pc.dim(`  Recommended: ${model.label}`));
   }
-  if (ollamaInstalled) console.log(pc.bold(`  ollama pull ${model.ollama}`));
   if (omlxInstalled) console.log(pc.bold("  omlx start"));
 }

package/src/commands/models.mjs

@@ -6,7 +6,7 @@ import { syncPiConfig, removeFromPiConfig } from "../harness-pi.mjs";
 import { configureLocalProfile } from "../profile-setup.mjs";
 import { pc, startInteractive, createPrompt } from "../ui.mjs";
 import { buildCatalogItems, createManagedProfile, itemKey, loadModelCatalog, normalizeCatalog } from "../model-catalog.mjs";
-import { modelSelectOption, modelNameWidth, printGgufModelDetails, printManagedModelDetails, printWorkspaceHeader, printBenchmarkLine, printProfileDetails } from "../model-presenters.mjs";
+import { modelSelectOption, modelNameWidth, printGgufModelDetails, printMlxModelDetails, printManagedModelDetails, printWorkspaceHeader, printBenchmarkLine, printProfileDetails } from "../model-presenters.mjs";
 import { runProfile } from "./run.mjs";
 
 const { stripVTControlCharacters } = await import("node:util");
@@ -40,7 +40,6 @@ export async function modelCommandCenter(initialCatalog) {
   }
 
   const runningProfilesNow = [];
-  const serverUpIds = new Set();
   const modelMissingIds = new Set();
   for (const profile of normalized.profiles) {
     if (await isProfileRunning(profile)) {
@@ -48,11 +47,10 @@ export async function modelCommandCenter(initialCatalog) {
       continue;
     }
     if (backendFor(profile.backend).type === "managed-server" && await isProfileServerUp(profile)) {
-      if (await modelAvailableOnServer(profile)) serverUpIds.add(profile.id);
-      else modelMissingIds.add(profile.id);
+      if (!(await modelAvailableOnServer(profile))) modelMissingIds.add(profile.id);
     }
   }
-  printWorkspaceHeader(normalized, runningProfilesNow, serverUpIds, modelMissingIds);
+  printWorkspaceHeader(normalized, runningProfilesNow, modelMissingIds);
   await printBenchmarkLine();
 
   const nameWidth = modelNameWidth(allItems);
@@ -62,13 +60,12 @@ export async function modelCommandCenter(initialCatalog) {
       if (item.fileMissing) return "missing";
       if (runningProfilesNow.some((profile) => profile.id === item.profile.id)) return "running";
       if (modelMissingIds.has(item.profile.id)) return "missing";
-      if (serverUpIds.has(item.profile.id)) return "serverup";
       return "ready";
     }
     return "setup";
   };
 
-  const groupOrder = ["running", "serverup", "ready", "setup", "missing"];
+  const groupOrder = ["running", "ready", "setup", "missing"];
   const grouped = new Map(groupOrder.map((key) => [key, []]));
   for (const item of allItems) grouped.get(statusFor(item)).push(item);
 
@@ -77,7 +74,7 @@ export async function modelCommandCenter(initialCatalog) {
     const bucket = grouped.get(group);
     if (!bucket || bucket.length === 0) continue;
     for (const item of bucket) {
-      const opt = modelSelectOption(item, { runningProfilesNow, serverUpIds, modelMissingIds, nameWidth });
+      const opt = modelSelectOption(item, { runningProfilesNow, modelMissingIds, nameWidth });
       choices.push({ value: opt.value, label: opt.label, hint: opt.hint });
     }
   }
@@ -159,6 +156,7 @@ async function performAction(prompt, action, item) {
   if (action === "inspect") {
     if (item.type === "profile") return await printProfileDetails(await readProfile(item.profile.id));
     if (item.type === "managed") return printManagedModelDetails(item.model, BACKENDS[item.backendId]);
+    if (item.model?.format === "mlx") return await printMlxModelDetails(item.model);
     return printGgufModelDetails(item.model, item.drafter);
   }
   if (action === "benchmark") {
@@ -169,20 +167,13 @@ async function performAction(prompt, action, item) {
     const { benchmarkFlow } = await import("../benchmark.mjs");
     return await benchmarkFlow();
   }
-  if (action === "run") return await runItem(prompt, item);
+  if (action === "run") return await runItem(item);
   if (action === "reconfigure" || action === "setup") return await setupItem(prompt, item, action);
   if (action === "remove" && item.type === "profile") return await removeProfileInteractive(item.profile.id);
 }
 
-async function runItem(prompt, item) {
-  if (item.type === "profile") return await runProfile(await readProfile(item.profile.id));
-  const profile = await createProfileFromModel(item.model, null, item.drafter?.path);
-  const configured = await configureLocalProfile(prompt, profile);
-  if (!configured) return;
-  await saveProfile(configured);
-  await syncPiConfig(configured);
-  printProfileSaved(configured.id);
-  return await runProfile(configured);
+async function runItem(item) {
+  return await runProfile(await readProfile(item.profile.id));
 }
 
 function printProfileSaved(id) {
@@ -205,6 +196,18 @@ async function setupItem(prompt, item, action) {
     printProfileSaved(profile.id);
     return;
   }
+  // MLX models: build a mlx-vlm profile and run interactive config.
+  if (item.model.format === "mlx") {
+    const { createProfileFromMlxModel } = await import("../profiles.mjs");
+    const { configureMlxProfile } = await import("../profile-setup.mjs");
+    const profile = await createProfileFromMlxModel(item.model);
+    const configured = await configureMlxProfile(prompt, profile);
+    if (!configured) return;
+    await saveProfile(configured, { writeCommand: true });
+    await syncPiConfig(configured);
+    printProfileSaved(configured.id);
+    return;
+  }
   const profile = await createProfileFromModel(item.model, null, item.drafter?.path);
   const configured = await configureLocalProfile(prompt, profile);
   if (!configured) return;

package/src/commands/onboard.mjs

@@ -1,14 +1,17 @@
 import { existsSync } from "node:fs";
-import { ensureDirs, findLlamaServer, hasHomebrew } from "../config.mjs";
+import { ensureDirs, findLlamaServer, hasHomebrew, HF_HUB_DIR } from "../config.mjs";
 import { BACKENDS } from "../backends.mjs";
 import { scanGgufModels } from "../scan.mjs";
+import { scanMlxModels } from "../mlx-discovery.mjs";
 import { hasPi } from "../harness-pi.mjs";
 import { offerManagedLlamaRuntimeUpdate } from "../runtime.mjs";
 import { scanManagedModels } from "../managed.mjs";
 import { BACKEND_INSTALL_CHOICES, BACKEND_INSTALLERS } from "../backend-installers.mjs";
-import { installedRamGB, recommendedModel } from "../recommendations.mjs";
+import { recommendedModel, selectFormat, allFittingModels } from "../recommendations.mjs";
+import { hasHuggingfaceHub, resolveHfDownload, downloadToHfCache } from "../huggingface.mjs";
+import { detectHardware, getFreeDiskBytes, installedRamGB } from "../hardware.mjs";
 import { runCommand } from "../exec.mjs";
-import { pc, renderRows, renderSection, startInteractive, createPrompt } from "../ui.mjs";
+import { pc, formatBytes, renderRows, renderSection, startInteractive, createPrompt } from "../ui.mjs";
 
 export async function onboardFlow() {
   await ensureDirs();
@@ -24,14 +27,22 @@ export async function onboardFlow() {
     const llamaBinary = await ensureLlamaRuntime(prompt);
     if (!(await ensurePi(prompt, run))) return;
 
-    const { models: ggufModels } = await scanGgufModels();
-    const managedModels = await scanManagedModels();
+    const [{ models: ggufModels }, managedModels, mlxModels] = await Promise.all([
+      scanGgufModels(),
+      scanManagedModels(),
+      scanMlxModels(),
+    ]);
     const totalManaged = managedModels.reduce((sum, item) => sum + item.models.length, 0);
-    const hasModels = ggufModels.length > 0 || totalManaged > 0;
+    const hasModels = ggufModels.length > 0 || totalManaged > 0 || mlxModels.length > 0;
 
     if (hasModels) {
-      printFoundModels(ggufModels, managedModels, llamaBinary);
+      printFoundModels(ggufModels, managedModels, mlxModels, llamaBinary);
     } else {
+      const canDownload = await hasHuggingfaceHub();
+      if (canDownload) {
+        const downloaded = await offerModelDownload(prompt);
+        if (downloaded) return;
+      }
       await offerBackendInstall(prompt, run);
       return;
     }
@@ -52,7 +63,7 @@ async function ensureLlamaRuntime(prompt) {
     ]), { formatBorder: pc.cyan }));
     await offerManagedLlamaRuntimeUpdate(prompt);
     llamaBinary = await findLlamaServer();
-    if (!llamaBinary) console.log(pc.yellow("Skipping llama.cpp for now. You can still use Ollama/oMLX, or run offgrid-ai again to install the managed runtime."));
+    if (!llamaBinary) console.log(pc.yellow("Skipping llama.cpp for now. You can still use oMLX, or run offgrid-ai again to install the managed runtime."));
   }
   if (llamaBinary) console.log(pc.green(`✓ llama-server: ${llamaBinary}`));
   return llamaBinary;
@@ -85,11 +96,14 @@ async function ensurePi(prompt, run) {
   return true;
 }
 
-function printFoundModels(ggufModels, managedModels, llamaBinary) {
+function printFoundModels(ggufModels, managedModels, mlxModels, llamaBinary) {
   if (ggufModels.length > 0) {
     console.log(pc.green(`✓ Found ${ggufModels.length} GGUF model${ggufModels.length === 1 ? "" : "s"}`));
     if (!llamaBinary) console.log(pc.yellow("Install the managed llama.cpp runtime to run these GGUF models."));
   }
+  if (mlxModels.length > 0) {
+    console.log(pc.green(`✓ Found ${mlxModels.length} MLX model${mlxModels.length === 1 ? "" : "s"}`));
+  }
   for (const { backendId, models, status, reason } of managedModels) {
     if (status === "unavailable") {
       console.log(pc.yellow(`${BACKENDS[backendId].label}: unavailable${reason ? ` — ${reason}` : ""}`));
@@ -99,6 +113,50 @@ function printFoundModels(ggufModels, managedModels, llamaBinary) {
   }
 }
 
+async function offerModelDownload(prompt) {
+  const hardware = detectHardware();
+  const candidates = allFittingModels(hardware)
+    .map((entry) => ({ entry, format: selectFormat(entry, hardware) }))
+    .filter((item) => item.format != null);
+  if (candidates.length === 0) {
+    console.log(pc.yellow("No curated models fit your hardware."));
+    return false;
+  }
+
+  const primary = candidates[0];
+  console.log(renderSection("Download a recommended model", renderRows([
+    ["Model", pc.bold(primary.entry.label)],
+    ["Format", primary.format],
+    ["Minimum RAM", String(primary.entry.minRamGb) + " GB"],
+    ["Your RAM", installedRamGB() + " GB"],
+  ]), { formatBorder: pc.cyan }));
+
+  const shouldDownload = await prompt.yesNo("Download " + primary.entry.label + " (" + primary.format + ")?", true);
+  if (!shouldDownload) return false;
+
+  const hfRef = primary.format === "mlx" ? primary.entry.mlx : primary.entry.gguf;
+  try {
+    const plan = await resolveHfDownload(hfRef);
+    console.log(pc.dim("Total size: " + formatBytes(plan.totalSizeBytes)));
+    const freeBytes = getFreeDiskBytes(HF_HUB_DIR);
+    if (plan.totalSizeBytes > 0 && freeBytes < plan.totalSizeBytes * 1.1) {
+      console.log(pc.red(`Not enough disk space in ${HF_HUB_DIR}: need ~${formatBytes(plan.totalSizeBytes)}, only ${formatBytes(freeBytes)} free.`));
+      return false;
+    }
+    await downloadToHfCache(plan, {
+      onProgress({ percentage }) {
+        process.stdout.write(pc.cyan("\r  " + percentage + "% downloaded"));
+      },
+    });
+    process.stdout.write("\n");
+    console.log(pc.green("✓ Download complete. Run offgrid-ai to use the model."));
+    return true;
+  } catch (err) {
+    console.log(pc.red("Download failed: " + err.message));
+    return false;
+  }
+}
+
 async function offerBackendInstall(prompt, run) {
   console.log(pc.yellow("\nNo models found."));
   console.log(pc.dim("You need at least one model backend to use offgrid-ai.\n"));

package/src/commands/run.mjs

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import { ensureDirs } from "../config.mjs";
 import { backendFor } from "../backends.mjs";
 import { normalizeProfile, readProfile, saveProfile } from "../profiles.mjs";
-import { startServer, stopProfile, waitForReady, serverReady, serverMatchesProfile, modelAvailableOnServer } from "../process.mjs";
+import { startServer, stopProfile, waitForReady, serverReady, serverMatchesProfile, modelAvailableOnServer, unloadModelFromServer } from "../process.mjs";
 import { syncPiConfig, hasPiModel, launchPi, hasPi } from "../harness-pi.mjs";
 import { tailFriendly } from "../logs.mjs";
 import { estimateMemory } from "../estimate.mjs";
@@ -35,7 +35,7 @@ export async function runProfile(profile, options = {}) {
     }
     const available = await modelAvailableOnServer(profile);
     if (!available) {
-      const modelId = profile.omlxModel ?? profile.ollamaModel ?? profile.modelAlias ?? profile.label;
+      const modelId = profile.omlxModel ?? profile.modelAlias ?? profile.label;
       throw new Error(`${modelId} is not available on ${backend.label} at ${profile.baseUrl}.`);
     }
     console.log(pc.green(`[ready] ${backend.label} at ${profile.baseUrl}`));
@@ -116,9 +116,24 @@ async function launchHarness(profile, options, isManaged, withHarness, backend)
   try {
     await launchPi(profile);
   } finally {
-    if (!isManaged && !options["keep-server"]) {
-      const result = await stopProfile(profile);
-      console.log(result.stopped ? pc.green(`[stop] ${result.message}`) : pc.dim(`[stop] ${result.message}`));
+    if (!options["keep-server"]) {
+      if (!isManaged) {
+        const result = await stopProfile(profile);
+        console.log(result.stopped ? pc.green(`[stop] ${result.message}`) : pc.dim(`[stop] ${result.message}`));
+      } else {
+        // Managed-server backends (oMLX): unload the model from the
+        // server's memory via its HTTP API. The server itself stays running
+        // (offgrid-ai doesn't manage it), but the model is released — same UX
+        // as local-server backends where stopProfile kills the process.
+        const result = await unloadModelFromServer(profile);
+        if (result.unloaded) {
+          console.log(pc.green(`[unload] ${backend.label}: model unloaded`));
+        } else if (result.reason) {
+          console.log(pc.dim(`[unload] ${backend.label}: ${result.reason}`));
+        } else if (result.error) {
+          console.log(pc.yellow(`[unload] ${backend.label}: ${result.error}`));
+        }
+      }
     }
   }
 }

package/src/commands/status.mjs

@@ -42,7 +42,7 @@ export async function statusCommand() {
     const detailRows = [];
     for (const { profile, status } of [...managedUpMissing, ...managedUpNotLoaded]) {
       const backend = backendFor(profile.backend);
-      const modelId = profile.omlxModel ?? profile.ollamaModel ?? profile.modelAlias ?? profile.id;
+      const modelId = profile.omlxModel ?? profile.modelAlias ?? profile.id;
       const state = status.modelAvailable
         ? pc.yellow("server up · model not loaded")
         : pc.red("server up · model missing");

package/src/config.mjs

@@ -15,9 +15,17 @@ export const MANAGED_LLAMA_SERVER = join(RUNTIME_DIR, "bin", "llama-server");
 
 // ── Default scan directories ──────────────────────────────────────────────
 
+// HuggingFace hub cache: $HF_HUB_CACHE, else $HF_HOME/hub, else
+// ~/.cache/huggingface/hub. This is where huggingface_hub stores
+// models--org--name/... and where offgrid-ai scans + downloads. Pointing at the
+// hub (not the HF root) keeps the HF-hub MLX/GGUF scanners and the downloader
+// on the same layout.
+export const HF_HUB_DIR = process.env.HF_HUB_CACHE
+  || (process.env.HF_HOME ? join(process.env.HF_HOME, "hub") : join(homedir(), ".cache", "huggingface", "hub"));
+
 export const DEFAULT_MODEL_DIRS = [
   join(homedir(), ".lmstudio", "models"),
-  join(homedir(), ".cache", "huggingface", "hub"),
+  HF_HUB_DIR,
 ];
 
 // ── External config paths ─────────────────────────────────────────────────
@@ -65,7 +73,8 @@ export async function saveConfig(config) {
 
 export async function getModelScanDirs() {
   const config = await loadConfig();
-  return [...DEFAULT_MODEL_DIRS, ...config.modelScanDirs];
+  // Dedupe (a user may list a default dir explicitly) so we never scan twice.
+  return [...DEFAULT_MODEL_DIRS, ...config.modelScanDirs].filter((dir, i, arr) => arr.indexOf(dir) === i);
 }
 
 // ── Binary discovery ──────────────────────────────────────────────────────

package/src/discovery-shared.mjs

@@ -0,0 +1,44 @@
+// Shared discovery helpers used by both the GGUF scanner (scan.mjs) and the
+// MLX scanner (mlx-discovery.mjs). Keeping these here avoids a cross-dependency
+// between the two format-specific scanners.
+
+import { basename, dirname } from "node:path";
+
+/** Minimum on-disk size for a model to count as real (skips tiny test/embedding files). */
+export const MIN_MODEL_SIZE_BYTES = 10 * 1024 * 1024; // 10 MB
+
+/**
+ * Model-type / architecture names that indicate an embedding model. Shared by
+ * GGUF filtering (general.architecture) and MLX filtering (config.model_type /
+ * architectures[0]). Format-specific heuristics (e.g. GGUF filename patterns)
+ * live alongside this set in each scanner.
+ */
+export const EMBEDDING_MODEL_TYPES = new Set([
+  "bert",
+  "roberta",
+  "mpnet",
+  "nomic_bert",
+  "nomic-bert",
+  "jina",
+  "e5",
+  "gte",
+  "bge",
+  "all_minilm",
+  "all-minilm",
+  "sentence_transformers",
+  "sentence-transformers",
+]);
+
+/**
+ * Infer a human-readable source label from a model scan path.
+ * Generic container folders (models, hub, cache) defer to their parent name
+ * (e.g. ~/.cache/huggingface/hub -> "huggingface"; ~/.lmstudio/models -> "lmstudio").
+ */
+export function inferSourceLabel(scanPath) {
+  const name = basename(scanPath).replace(/^\./, "");
+  const parent = basename(dirname(scanPath));
+  if (name === "models" || name === "hub" || name === "cache") {
+    return parent.replace(/^\./, "");
+  }
+  return name;
+}

package/src/hardware.mjs

@@ -0,0 +1,49 @@
+// Hardware detection — pure functions, no side effects.
+// Ported from deprecated-offgrid-desktop/src/main/hardware.ts.
+//
+// This is the canonical source for hardware facts the model-serving logic
+// needs: recommendations, onboarding, MLX context sizing, disk-space guards,
+// and memory estimation.
+
+import { totalmem } from "node:os";
+import { statfsSync, existsSync } from "node:fs";
+import { dirname } from "node:path";
+
+/**
+ * Detect system hardware via the Node.js `os` module.
+ * Pure function — no side effects, trivially testable.
+ */
+export function detectHardware() {
+  return {
+    totalRamBytes: totalmem(),
+    platform: process.platform,
+    arch: process.arch,
+  };
+}
+
+/** Installed RAM in GB (integer). */
+export function installedRamGB() {
+  return Math.round(totalmem() / (1024 ** 3));
+}
+
+/**
+ * Get available disk space for a directory (in bytes).
+ *
+ * If the directory doesn't exist yet, walks up to the nearest existing parent
+ * directory. Returns a very large number if the check fails (so we don't block
+ * a download unnecessarily).
+ */
+export function getFreeDiskBytes(dir) {
+  try {
+    let checkDir = dir;
+    while (!existsSync(checkDir)) {
+      const parent = dirname(checkDir);
+      if (parent === checkDir) break; // reached root
+      checkDir = parent;
+    }
+    const stats = statfsSync(checkDir);
+    return stats.bavail * stats.bsize;
+  } catch {
+    return Number.MAX_SAFE_INTEGER;
+  }
+}

package/src/harness-pi.mjs

@@ -5,6 +5,18 @@ import { loadProfiles } from "./profiles.mjs";
 import { readJson, writeJson } from "./json.mjs";
 import pc from "picocolors";
 
+// ── Pi model id ─────────────────────────────────────────────────────────────
+
+/**
+ * The model id Pi must send in requests. mlx-vlm registers the loaded model
+ * with the full --model path as its API id (verified via /v1/models); sending
+ * the repo-id label instead makes mlx-vlm unload the local model and re-fetch
+ * the repo from HuggingFace. Other backends use the friendly modelAlias.
+ */
+export function piApiModelId(profile) {
+  return profile.backend === "mlx-vlm" ? profile.modelPath : profile.modelAlias;
+}
+
 // ── Sync Pi config ─────────────────────────────────────────────────────────
 
 export async function syncPiConfig(profile) {
@@ -30,26 +42,27 @@ export async function removeFromPiConfig(profile) {
   const provider = config.providers[profile.providerId];
   if (!provider?.models) return { cleaned: false, reason: `no ${profile.providerId} provider in Pi config` };
   const before = provider.models.length;
-  provider.models = provider.models.filter((m) => m.id !== profile.modelAlias);
+  const apiId = piApiModelId(profile);
+  provider.models = provider.models.filter((m) => m.id !== apiId);
   if (provider.models.length === 0) delete config.providers[profile.providerId];
   if (before > provider.models.length) {
     await writeJson(PI_CONFIG, config);
     return { cleaned: true, removed: before - provider.models.length };
   }
-  return { cleaned: false, reason: `${profile.modelAlias} not in Pi config` };
+  return { cleaned: false, reason: `${apiId} not in Pi config` };
 }
 
 // ── Check if Pi has the model ──────────────────────────────────────────────
 
 export async function hasPiModel(profile) {
   const config = await readJson(PI_CONFIG, null);
-  return Boolean(config?.providers?.[profile.providerId]?.models?.some?.((m) => m.id === profile.modelAlias));
+  return Boolean(config?.providers?.[profile.providerId]?.models?.some?.((m) => m.id === piApiModelId(profile)));
 }
 
 // ── Launch Pi ──────────────────────────────────────────────────────────────
 
 export async function launchPi(profile) {
-  const model = profile.harnesses?.pi?.model ?? `${profile.providerId}/${profile.modelAlias}`;
+  const model = `${profile.providerId}/${piApiModelId(profile)}`;
   console.log(pc.bold(`[pi] pi --model ${model}`));
   await runForeground("pi", ["--model", model]);
 }
@@ -88,7 +101,7 @@ function piModelConfig(profile) {
   const compat = modelCompat(profile);
   const reasoning = modelReasoning(profile);
   return {
-    id: profile.modelAlias,
+    id: piApiModelId(profile),
     name: profile.label,
     input: modelInput(profile),
     ...(reasoning === undefined ? {} : { reasoning }),
@@ -99,7 +112,9 @@ function piModelConfig(profile) {
 }
 
 function modelInput(profile) {
-  return profile.mmprojPath && existsSync(profile.mmprojPath) ? ["text", "image"] : ["text"];
+  if (profile.mmprojPath && existsSync(profile.mmprojPath)) return ["text", "image"];
+  if (profile.capabilities?.vision) return ["text", "image"];
+  return ["text"];
 }
 
 function modelCompat(profile) {
@@ -119,15 +134,14 @@ function modelReasoning(profile) {
 }
 
 function modelFamily(profile) {
-  return [profile.id, profile.label, profile.modelAlias, profile.modelPath, profile.ollamaModel, profile.omlxModel].filter(Boolean).join(" ").toLowerCase();
+  return [profile.id, profile.label, profile.modelAlias, profile.modelPath, profile.omlxModel].filter(Boolean).join(" ").toLowerCase();
 }
 
-function piApiKey(providerId) {
-  return providerId === "ollama" ? "ollama" : "none";
+function piApiKey() {
+  return "none";
 }
 
-function providerCompat(providerId) {
-  if (providerId === "ollama") return { supportsDeveloperRole: true, supportsReasoningEffort: false };
+function providerCompat() {
   return { supportsDeveloperRole: false, supportsReasoningEffort: false };
 }