@otto-code/brain 0.8.0 → 0.8.2

package/dist/commands/runtime.d.ts

@@ -17,5 +17,6 @@ export declare function runRuntimeListCommand(_options: unknown, _command: Comma
 export declare function addRuntimeInstallOptions(cmd: Command): Command;
 export declare function runRuntimeInstallCommand(options: {
     build?: string;
+    variant?: string;
 }, _command: Command): Promise<AnyCommandResult<RuntimeRow>>;
 //# sourceMappingURL=runtime.d.ts.map

package/dist/commands/runtime.js

@@ -1,6 +1,7 @@
 import { loadBrainConfig } from "../config/index.js";
 import { resolveBrainPaths } from "../config/paths.js";
-import { defaultRuntimeSpec, installManagedRuntime, listAllRuntimes } from "../runtime/index.js";
+import { CommandError } from "../output/types.js";
+import { defaultRuntimeSpec, installManagedRuntime, listAllRuntimes, listRuntimeDevices, probeNvidiaGpu, supportedVariants, } from "../runtime/index.js";
 const runtimeSchema = {
     idField: "dir",
     columns: [
@@ -32,12 +33,26 @@ export async function runRuntimeListCommand(_options, _command) {
 export function addRuntimeInstallOptions(cmd) {
     return cmd
         .description("Download a self-contained llama.cpp runtime")
-        .option("--build <tag>", "llama.cpp release build tag");
+        .option("--build <tag>", "llama.cpp release build tag")
+        .option("--variant <name>", `accelerator to install (${supportedVariants().join("|")}); defaults to the best one this machine can use`);
 }
 export async function runRuntimeInstallCommand(options, _command) {
     loadBrainConfig();
     const { runtimesDir } = resolveBrainPaths();
-    const spec = defaultRuntimeSpec(options.build);
+    const available = supportedVariants();
+    if (options.variant && !available.includes(options.variant)) {
+        throw new CommandError({
+            code: "UNSUPPORTED_VARIANT",
+            message: `llama.cpp publishes no "${options.variant}" build for ${process.platform}/${process.arch}` +
+                ` - available: ${available.join(", ") || "(none)"}`,
+        });
+    }
+    // Only "auto" needs the GPU probe, and only to choose between CUDA and Vulkan
+    // on the platforms that have both.
+    const spec = defaultRuntimeSpec(options.build, {
+        variant: options.variant ?? "auto",
+        hasNvidiaGpu: options.variant ? undefined : await probeNvidiaGpu(),
+    });
     process.stderr.write(`  installing ${spec.label} (${spec.version})…\n`);
     const runtime = await installManagedRuntime(spec, runtimesDir, (p) => {
         if (p.phase === "downloading" && p.totalBytes) {
@@ -48,6 +63,20 @@ export async function runRuntimeInstallCommand(options, _command) {
             process.stderr.write("\n  extracting…\n");
     });
     process.stderr.write("\n");
+    // A GPU variant that finds no device still runs - on the CPU, at roughly a
+    // fortieth of the prefill throughput, and says nothing about it. Measured on
+    // WSL2, which carries no NVIDIA Vulkan ICD. Warn rather than fail: the runtime
+    // is genuinely installed and usable, just not accelerated.
+    // One line on purpose. The daemon's BrainOpsManager keeps the *last* stderr line
+    // as the job's message, so a multi-line warning would surface in the UI as a
+    // dangling fragment. As one line it survives intact on both the CLI and the GUI.
+    if (spec.variant !== "cpu") {
+        const devices = await listRuntimeDevices(runtime);
+        if (devices.length === 0) {
+            process.stderr.write(`  warning: this ${spec.variant} runtime reports no GPU device, so inference will run` +
+                ` on the CPU until a working ${spec.variant} driver for this GPU is installed.\n`);
+        }
+    }
     return {
         type: "single",
         data: {

package/dist/config/paths.d.ts

@@ -4,11 +4,13 @@ export interface BrainPaths {
     configFile: string;
     profilesFile: string;
     catalogFile: string;
+    renameMapFile: string;
     modelsDir: string;
     runtimesDir: string;
     pidFile: string;
     activityFile: string;
     logFile: string;
+    logsDir: string;
     resultsDir: string;
 }
 export declare function resolveBrainPaths(env?: NodeJS.ProcessEnv): BrainPaths;

package/dist/config/paths.js

@@ -15,6 +15,7 @@ export function resolveBrainPaths(env = process.env) {
         configFile: path.join(root, "config.json"),
         profilesFile: path.join(root, "profiles.json"),
         catalogFile: path.join(root, "catalog.json"),
+        renameMapFile: path.join(root, "rename-map.json"),
         modelsDir: path.join(root, "models"),
         runtimesDir: path.join(root, "runtimes"),
         pidFile: path.join(root, "otto-brain.pid"),
@@ -23,6 +24,7 @@ export function resolveBrainPaths(env = process.env) {
         // service - which is what answers /__host/status - never sees them otherwise.
         activityFile: path.join(root, "otto-brain.activity"),
         logFile: path.join(root, "otto-brain.log"),
+        logsDir: path.join(root, "logs"),
         resultsDir: path.join(root, "results"),
     };
 }

package/dist/models/index.js

@@ -4,6 +4,7 @@ import { CatalogSchema } from "../config/schema.js";
 import { loadCatalog } from "../config/store.js";
 import { resolveModelsDirs } from "./dirs.js";
 import { enrichWithCatalog } from "./enrich.js";
+import { loadRenameMap } from "./rename-map.js";
 import { scan } from "./scan.js";
 export * from "./scan.js";
 export { pickModel, pickAutoModel } from "./pick.js";
@@ -30,6 +31,12 @@ export function scanModels(config, env = process.env, options = {}) {
         }
     }
     const enriched = enrichWithCatalog(all, loadCatalogSafe(env));
+    const renameMap = loadRenameMap(resolveBrainPaths(env));
+    for (const model of enriched) {
+        if (renameMap[model.id]) {
+            model.displayName = renameMap[model.id];
+        }
+    }
     enriched.sort((a, b) => a.displayName.localeCompare(b.displayName));
     return enriched;
 }

package/dist/models/rename-map.d.ts

@@ -0,0 +1,12 @@
+import { type BrainPaths } from "../config/paths.js";
+/** Every function here only ever touches renameMapFile; narrowed to that one
+ * field (rather than the full BrainPaths) so a test's fake paths object is
+ * actually type-checked instead of passing only because tsconfig excludes
+ * *.test.ts from the build. */
+type RenameMapPaths = Pick<BrainPaths, "renameMapFile">;
+export declare function loadRenameMap(paths?: RenameMapPaths): Record<string, string>;
+export declare function saveRenameMap(map: Record<string, string>, paths?: RenameMapPaths): void;
+export declare function updateDisplayName(modelId: string, displayName: string, paths?: RenameMapPaths): Record<string, string>;
+export declare function deleteDisplayName(modelId: string, paths?: RenameMapPaths): Record<string, string>;
+export {};
+//# sourceMappingURL=rename-map.d.ts.map

package/dist/models/rename-map.js

@@ -0,0 +1,39 @@
+/**
+ * User-defined model display-name overrides, keyed by model id, persisted at
+ * `$OTTO_HOME/otto-brain/rename-map.json`. Kept as its own file (rather than a
+ * field on the profiles store) so renaming a model never touches the
+ * calibration/profile data profiles.json carries.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { z } from "zod";
+import { resolveBrainPaths } from "../config/paths.js";
+import { writePrivateFileAtomicSync } from "../config/private-files.js";
+const RenameMapSchema = z.record(z.string());
+export function loadRenameMap(paths = resolveBrainPaths()) {
+    if (!existsSync(paths.renameMapFile))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(paths.renameMapFile, "utf8"));
+        const result = RenameMapSchema.safeParse(parsed);
+        return result.success ? result.data : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function saveRenameMap(map, paths = resolveBrainPaths()) {
+    writePrivateFileAtomicSync(paths.renameMapFile, `${JSON.stringify(map, null, 2)}\n`);
+}
+export function updateDisplayName(modelId, displayName, paths = resolveBrainPaths()) {
+    const map = loadRenameMap(paths);
+    map[modelId] = displayName;
+    saveRenameMap(map, paths);
+    return map;
+}
+export function deleteDisplayName(modelId, paths = resolveBrainPaths()) {
+    const map = loadRenameMap(paths);
+    delete map[modelId];
+    saveRenameMap(map, paths);
+    return map;
+}
+//# sourceMappingURL=rename-map.js.map

package/dist/runtime/args.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Translates a profile into llama-server arguments and builds the PATH the child
+ * needs. Runtime-source agnostic: works the same for an LM Studio runtime or a
+ * managed one, since both resolve to a `Runtime` (exe + optional vendorDir).
+ */
 import type { Profile } from "../config/schema.js";
 import type { Runtime } from "../types.js";
 export interface ServeTarget {
@@ -5,10 +10,18 @@ export interface ServeTarget {
     host?: string;
 }
 /**
- * PATH value the child process needs so the stub can resolve its DLLs. Both the
- * runtime dir and its vendor dir go first, ahead of the inherited PATH.
+ * Loader environment the child process needs so it can resolve its shared
+ * libraries. Both the runtime dir and its vendor dir go first, ahead of the
+ * inherited values.
+ *
+ * PATH is the Windows half of this (the DLL-stub trap). The other two platforms
+ * do not read PATH for libraries at all: a llama.cpp tarball puts
+ * `libggml*.so`/`libllama.so` (or the `.dylib` equivalents) next to the binary,
+ * so Linux needs LD_LIBRARY_PATH and macOS needs DYLD_LIBRARY_PATH or the
+ * binary dies at load with an unresolved-library error before it prints a line.
+ * PATH is still set everywhere - harmless, and it keeps the shape uniform.
  */
-export declare function buildEnv(runtime: Runtime, baseEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function buildEnv(runtime: Runtime, baseEnv?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
 /**
  * Translate a profile into llama-server arguments.
  *

package/dist/runtime/args.js

@@ -1,21 +1,27 @@
 /**
- * Translates a profile into llama-server arguments and builds the PATH the child
- * needs. Runtime-source agnostic: works the same for an LM Studio runtime or a
- * managed one, since both resolve to a `Runtime` (exe + optional vendorDir).
- */
-import path from "node:path";
-/**
- * PATH value the child process needs so the stub can resolve its DLLs. Both the
- * runtime dir and its vendor dir go first, ahead of the inherited PATH.
+ * Loader environment the child process needs so it can resolve its shared
+ * libraries. Both the runtime dir and its vendor dir go first, ahead of the
+ * inherited values.
+ *
+ * PATH is the Windows half of this (the DLL-stub trap). The other two platforms
+ * do not read PATH for libraries at all: a llama.cpp tarball puts
+ * `libggml*.so`/`libllama.so` (or the `.dylib` equivalents) next to the binary,
+ * so Linux needs LD_LIBRARY_PATH and macOS needs DYLD_LIBRARY_PATH or the
+ * binary dies at load with an unresolved-library error before it prints a line.
+ * PATH is still set everywhere - harmless, and it keeps the shape uniform.
  */
-export function buildEnv(runtime, baseEnv = process.env) {
+export function buildEnv(runtime, baseEnv = process.env, platform = process.platform) {
     const parts = [runtime.dir];
     if (runtime.vendorDir)
         parts.push(runtime.vendorDir);
-    return {
-        ...baseEnv,
-        PATH: `${parts.join(path.delimiter)}${path.delimiter}${baseEnv.PATH || ""}`,
-    };
+    const delimiter = platform === "win32" ? ";" : ":";
+    const prepend = (existing) => `${parts.join(delimiter)}${delimiter}${existing || ""}`;
+    const env = { ...baseEnv, PATH: prepend(baseEnv.PATH) };
+    if (platform === "darwin")
+        env.DYLD_LIBRARY_PATH = prepend(baseEnv.DYLD_LIBRARY_PATH);
+    else if (platform !== "win32")
+        env.LD_LIBRARY_PATH = prepend(baseEnv.LD_LIBRARY_PATH);
+    return env;
 }
 /**
  * Translate a profile into llama-server arguments.

package/dist/runtime/index.d.ts

@@ -1,13 +1,19 @@
 import type { BrainConfig } from "../config/schema.js";
 import type { Runtime } from "../types.js";
-import { type InstallProgress } from "./managed.js";
+import { type InstallProgress, type RuntimeTarget } from "./managed.js";
 export { BACKENDS_DIR, LMSTUDIO_ROOT, listRuntimes as listLmStudioRuntimes } from "./lmstudio.js";
 export { buildArgs, buildEnv, formatCommand, type ServeTarget } from "./args.js";
-export { installManagedRuntime, listManagedRuntimes, defaultRuntimeSpec, DEFAULT_LLAMA_BUILD, type RuntimeSpec, type InstallProgress, } from "./managed.js";
+export { installManagedRuntime, listManagedRuntimes, listRuntimeDevices, verifyRuntimeExecutable, defaultRuntimeSpec, extractArchive, resolveRuntimeVariant, serverExeName, supportedVariants, DEFAULT_LLAMA_BUILD, type RuntimeSpec, type RuntimeTarget, type RuntimeVariant, type InstallProgress, } from "./managed.js";
 /** Every runtime available on this machine, managed first then LM Studio. */
 export declare function listAllRuntimes(env?: NodeJS.ProcessEnv): Runtime[];
+/**
+ * Whether this machine has an NVIDIA GPU, for picking a managed build. Returns
+ * false rather than throwing when nvidia-smi is absent, which is the normal
+ * case on macOS and on AMD/Intel machines.
+ */
+export declare function probeNvidiaGpu(): Promise<boolean>;
 /** The runtime to use given config, or null when none is available. */
 export declare function resolveRuntime(config: BrainConfig, env?: NodeJS.ProcessEnv): Runtime | null;
 /** Ensure a runtime exists, downloading the default managed build if none does. */
-export declare function ensureRuntime(config: BrainConfig, env?: NodeJS.ProcessEnv, onProgress?: (progress: InstallProgress) => void): Promise<Runtime>;
+export declare function ensureRuntime(config: BrainConfig, env?: NodeJS.ProcessEnv, onProgress?: (progress: InstallProgress) => void, target?: RuntimeTarget): Promise<Runtime>;
 //# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.js

@@ -4,18 +4,32 @@
  * path) and `lmstudio` (discovered from an existing LM Studio install, a
  * zero-download fast path). Selection follows config: an explicit path override
  * wins; otherwise `auto` prefers a managed runtime and falls back to LM Studio.
+ *
+ * Both providers are cross-platform. Which accelerator a managed install picks
+ * is decided in `managed.resolveRuntimeVariant` from the platform, the arch and
+ * whether an NVIDIA GPU answered - `probeNvidiaGpu` below is the one place that
+ * asks, so the download layer stays free of process spawning.
  */
+import { query as queryGpu } from "../gpu.js";
 import { resolveBrainPaths } from "../config/paths.js";
 import { listRuntimes as listLmStudioRuntimes, resolveOverride } from "./lmstudio.js";
 import { defaultRuntimeSpec, installManagedRuntime, listManagedRuntimes, } from "./managed.js";
 export { BACKENDS_DIR, LMSTUDIO_ROOT, listRuntimes as listLmStudioRuntimes } from "./lmstudio.js";
 export { buildArgs, buildEnv, formatCommand } from "./args.js";
-export { installManagedRuntime, listManagedRuntimes, defaultRuntimeSpec, DEFAULT_LLAMA_BUILD, } from "./managed.js";
+export { installManagedRuntime, listManagedRuntimes, listRuntimeDevices, verifyRuntimeExecutable, defaultRuntimeSpec, extractArchive, resolveRuntimeVariant, serverExeName, supportedVariants, DEFAULT_LLAMA_BUILD, } from "./managed.js";
 /** Every runtime available on this machine, managed first then LM Studio. */
 export function listAllRuntimes(env = process.env) {
     const paths = resolveBrainPaths(env);
     return [...listManagedRuntimes(paths.runtimesDir), ...listLmStudioRuntimes()];
 }
+/**
+ * Whether this machine has an NVIDIA GPU, for picking a managed build. Returns
+ * false rather than throwing when nvidia-smi is absent, which is the normal
+ * case on macOS and on AMD/Intel machines.
+ */
+export async function probeNvidiaGpu() {
+    return (await queryGpu()) !== null;
+}
 /** The runtime to use given config, or null when none is available. */
 export function resolveRuntime(config, env = process.env) {
     const rc = config.runtime;
@@ -31,11 +45,15 @@ export function resolveRuntime(config, env = process.env) {
     return managed[0] ?? lmstudio[0] ?? null; // auto
 }
 /** Ensure a runtime exists, downloading the default managed build if none does. */
-export async function ensureRuntime(config, env = process.env, onProgress) {
+export async function ensureRuntime(config, env = process.env, onProgress, target = {}) {
     const existing = resolveRuntime(config, env);
     if (existing)
         return existing;
     const paths = resolveBrainPaths(env);
-    return installManagedRuntime(defaultRuntimeSpec(), paths.runtimesDir, onProgress);
+    const resolved = {
+        ...target,
+        hasNvidiaGpu: target.hasNvidiaGpu ?? (await probeNvidiaGpu()),
+    };
+    return installManagedRuntime(defaultRuntimeSpec(null, resolved), paths.runtimesDir, onProgress);
 }
 //# sourceMappingURL=index.js.map

package/dist/runtime/lmstudio.d.ts

@@ -4,7 +4,7 @@ export declare const BACKENDS_DIR: string;
 export declare function extractVersion(dirName: string): string;
 /** Compare dotted version strings numerically, descending. */
 export declare function compareVersionsDesc(a: string, b: string): number;
-export declare function listRuntimes(backendsDir?: string): Runtime[];
+export declare function listRuntimes(backendsDir?: string, platform?: NodeJS.Platform): Runtime[];
 /** Resolve an explicit runtime directory or exe override into a Runtime. */
-export declare function resolveOverride(override: string): Runtime;
+export declare function resolveOverride(override: string, platform?: NodeJS.Platform): Runtime;
 //# sourceMappingURL=lmstudio.d.ts.map

package/dist/runtime/lmstudio.js

@@ -1,33 +1,73 @@
 /**
- * Locates the llama-server binary shipped inside LM Studio.
+ * Locates the llama-server binary shipped inside LM Studio, on all three
+ * desktop platforms. LM Studio keeps its backends under `~/.lmstudio` on
+ * Windows, macOS and Linux alike, so only the directory naming and the binary
+ * name differ per platform.
  *
- * Important gotcha: that executable is a ~20KB stub. Launching it without the
- * matching `backends/vendor/...` directory on PATH fails with
+ * Important gotcha (Windows): that executable is a ~20KB stub. Launching it
+ * without the matching `backends/vendor/...` directory on PATH fails with
  * STATUS_DLL_NOT_FOUND (0xC0000135) and prints absolutely nothing, so we always
- * pair a runtime with its vendor directory. This is one of two runtime sources
- * (the other being the self-contained `managed` runtime); it stays as a
- * zero-download fast path when LM Studio is already installed.
+ * pair a runtime with its vendor directory, and a Windows runtime whose vendor
+ * dir is missing is skipped rather than offered. macOS and Linux builds are
+ * self-contained and fail loudly through the dynamic loader when they are not,
+ * which is why the name-shape fallback below is enabled only there.
+ *
+ * This is one of two runtime sources (the other being the self-contained
+ * `managed` runtime); it stays as a zero-download fast path when LM Studio is
+ * already installed.
  */
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { serverExeName } from "./managed.js";
 export const LMSTUDIO_ROOT = path.join(os.homedir(), ".lmstudio");
 export const BACKENDS_DIR = path.join(LMSTUDIO_ROOT, "extensions", "backends");
-// Most preferred first. Each entry maps a runtime prefix to its vendor dir.
-const RUNTIME_PREFERENCE = [
-    {
-        prefix: "llama.cpp-win-x86_64-nvidia-cuda12-",
-        vendor: "win-llama-cuda12-vendor-v2",
-        label: "CUDA 12",
-    },
-    {
-        prefix: "llama.cpp-win-x86_64-nvidia-cuda-",
-        vendor: "win-llama-cuda-vendor-v2",
-        label: "CUDA 11",
-    },
-    { prefix: "llama.cpp-win-x86_64-vulkan-", vendor: "win-llama-vulkan-vendor-v2", label: "Vulkan" },
-    { prefix: "llama.cpp-win-x86_64-avx2-", vendor: null, label: "CPU (AVX2)" },
-];
+/**
+ * Most preferred first, per platform. Each entry maps a runtime directory
+ * prefix to its vendor dir.
+ *
+ * Prefix (not substring) matching is deliberate: a CUDA directory is named
+ * `llama.cpp-win-x86_64-nvidia-cuda12-avx2-<version>`, so a substring rule for
+ * the AVX2 entry would match it a second time and offer the same runtime twice
+ * under the wrong label.
+ *
+ * The Windows rows are verified against a real install. The macOS and Linux
+ * rows follow LM Studio's documented naming but have not been read off a live
+ * install here - the shape fallback in `listRuntimes` is what makes discovery
+ * correct on those platforms regardless.
+ */
+const PREFERENCES = {
+    win32: [
+        {
+            prefix: "llama.cpp-win-x86_64-nvidia-cuda12-",
+            vendor: "win-llama-cuda12-vendor-v2",
+            label: "CUDA 12",
+        },
+        {
+            prefix: "llama.cpp-win-x86_64-nvidia-cuda-",
+            vendor: "win-llama-cuda-vendor-v2",
+            label: "CUDA 11",
+        },
+        {
+            prefix: "llama.cpp-win-x86_64-vulkan-",
+            vendor: "win-llama-vulkan-vendor-v2",
+            label: "Vulkan",
+        },
+        { prefix: "llama.cpp-win-x86_64-avx2-", vendor: null, label: "CPU (AVX2)" },
+    ],
+    darwin: [
+        { prefix: "llama.cpp-mac-arm64-apple-metal-", vendor: null, label: "Metal" },
+        { prefix: "llama.cpp-mac-arm64-", vendor: null, label: "CPU (arm64)" },
+        { prefix: "llama.cpp-mac-x86_64-", vendor: null, label: "CPU (x86_64)" },
+    ],
+    linux: [
+        { prefix: "llama.cpp-linux-x86_64-nvidia-cuda12-", vendor: null, label: "CUDA 12" },
+        { prefix: "llama.cpp-linux-x86_64-nvidia-cuda-", vendor: null, label: "CUDA 11" },
+        { prefix: "llama.cpp-linux-x86_64-vulkan-", vendor: null, label: "Vulkan" },
+        { prefix: "llama.cpp-linux-x86_64-avx2-", vendor: null, label: "CPU (AVX2)" },
+        { prefix: "llama.cpp-linux-aarch64-", vendor: null, label: "CPU (aarch64)" },
+    ],
+};
 // Directory names carry an instruction-set segment before the version
 // (…-cuda12-avx2-2.24.0), so take the trailing dotted number, not the remainder.
 const VERSION_SUFFIX = /(\d+(?:\.\d+)+)$/;
@@ -46,40 +86,87 @@ export function compareVersionsDesc(a, b) {
     }
     return 0;
 }
-export function listRuntimes(backendsDir = BACKENDS_DIR) {
+/** A readable label for a directory discovered outside the preference table. */
+function labelFromDirName(dirName) {
+    const lower = dirName.toLowerCase();
+    if (lower.includes("cuda12"))
+        return "CUDA 12";
+    if (lower.includes("cuda"))
+        return "CUDA";
+    if (lower.includes("metal"))
+        return "Metal";
+    if (lower.includes("vulkan"))
+        return "Vulkan";
+    if (lower.includes("rocm") || lower.includes("hip"))
+        return "ROCm";
+    if (lower.includes("avx2"))
+        return "CPU (AVX2)";
+    return "LM Studio runtime";
+}
+export function listRuntimes(backendsDir = BACKENDS_DIR, platform = process.platform) {
     if (!fs.existsSync(backendsDir))
         return [];
+    const exeName = serverExeName(platform);
     const entries = fs
         .readdirSync(backendsDir, { withFileTypes: true })
         .filter((e) => e.isDirectory())
         .map((e) => e.name);
     const found = [];
-    for (const pref of RUNTIME_PREFERENCE) {
+    const claimed = new Set();
+    for (const pref of PREFERENCES[platform] ?? []) {
         const matches = entries
-            .filter((name) => name.startsWith(pref.prefix))
+            .filter((name) => name.startsWith(pref.prefix) && !claimed.has(name))
             .map((name) => ({ name, version: extractVersion(name) }))
-            .filter(({ name }) => fs.existsSync(path.join(backendsDir, name, "llama-server.exe")))
+            .filter(({ name }) => fs.existsSync(path.join(backendsDir, name, exeName)))
             .sort((a, b) => compareVersionsDesc(a.version, b.version));
         for (const match of matches) {
             const vendorDir = pref.vendor ? path.join(backendsDir, "vendor", pref.vendor) : null;
             // A runtime whose vendor DLLs are missing cannot launch; skip it.
             if (vendorDir && !fs.existsSync(vendorDir))
                 continue;
+            claimed.add(match.name);
             found.push({
                 label: pref.label,
                 version: match.version,
                 dir: path.join(backendsDir, match.name),
-                exe: path.join(backendsDir, match.name, "llama-server.exe"),
+                exe: path.join(backendsDir, match.name, exeName),
                 vendorDir,
                 source: "lmstudio",
             });
         }
     }
+    // Shape fallback: anything that holds a llama-server binary is usable on the
+    // self-contained platforms, whatever LM Studio decided to call the directory.
+    // Not applied on Windows, where an unpaired stub launches and dies silently.
+    if (platform !== "win32") {
+        const extra = entries
+            .filter((name) => !claimed.has(name) && name !== "vendor")
+            .filter((name) => fs.existsSync(path.join(backendsDir, name, exeName)))
+            .map((name) => ({ name, version: extractVersion(name) }))
+            .sort((a, b) => compareVersionsDesc(a.version, b.version));
+        for (const match of extra) {
+            found.push({
+                label: labelFromDirName(match.name),
+                version: match.version,
+                dir: path.join(backendsDir, match.name),
+                exe: path.join(backendsDir, match.name, exeName),
+                vendorDir: null,
+                source: "lmstudio",
+            });
+        }
+    }
     return found;
 }
 /** Resolve an explicit runtime directory or exe override into a Runtime. */
-export function resolveOverride(override) {
-    const exe = override.endsWith(".exe") ? override : path.join(override, "llama-server.exe");
+export function resolveOverride(override, platform = process.platform) {
+    const exeName = serverExeName(platform);
+    // An override may name the binary directly or the directory holding it. On
+    // non-Windows the binary has no extension, so "is it a file?" is the only
+    // reliable test - a bare `.../llama-server` path looks exactly like a dir.
+    const looksLikeExe = path.basename(override).toLowerCase() === exeName.toLowerCase() ||
+        (platform === "win32" && override.toLowerCase().endsWith(".exe")) ||
+        (fs.existsSync(override) && fs.statSync(override).isFile());
+    const exe = looksLikeExe ? override : path.join(override, exeName);
     if (!fs.existsSync(exe))
         throw new Error(`llama-server not found at ${exe}`);
     const dir = path.dirname(exe);

package/dist/runtime/managed.d.ts

@@ -1,9 +1,23 @@
 import type { Runtime } from "../types.js";
+/** The accelerator a managed runtime is built against. */
+export type RuntimeVariant = "cuda" | "metal" | "vulkan" | "cpu";
 export interface RuntimeSpec {
     label: string;
     version: string;
     /** One or more archive URLs, extracted in order into the same target dir. */
     assets: string[];
+    /** Platform the assets are built for; drives exe name and extraction. */
+    platform: NodeJS.Platform;
+    variant: RuntimeVariant;
+}
+/** What to install for. Any field left out is read from the current process. */
+export interface RuntimeTarget {
+    platform?: NodeJS.Platform;
+    arch?: string;
+    /** Explicit accelerator, or "auto" to pick from platform + GPU presence. */
+    variant?: RuntimeVariant | "auto";
+    /** Whether an NVIDIA GPU was detected; only consulted by "auto". */
+    hasNvidiaGpu?: boolean;
 }
 export interface InstallProgress {
     phase: "downloading" | "extracting" | "done";
@@ -12,15 +26,65 @@ export interface InstallProgress {
     totalBytes?: number;
 }
 /**
- * The default runtime build. The llama.cpp release tag and CUDA asset names must
- * be pinned per platform; verify the URLs against the current release before
- * shipping. Overridable via config (`runtime.path`) or an explicit spec.
+ * The default runtime build. Bumping this requires re-reading the tag's asset
+ * names (see the module header) - the naming scheme is not stable across tags.
+ */
+export declare const DEFAULT_LLAMA_BUILD = "b10265";
+/** The binary name llama.cpp ships for a platform. */
+export declare function serverExeName(platform?: NodeJS.Platform): string;
+/**
+ * Pick the accelerator for a target. Deliberately conservative: it never
+ * chooses an accelerator whose asset does not exist for that platform/arch.
+ */
+export declare function resolveRuntimeVariant(target?: RuntimeTarget): RuntimeVariant;
+/**
+ * Build the runtime spec for a target. Throws when upstream publishes nothing
+ * for the combination, naming what it tried so the message is actionable.
+ */
+export declare function defaultRuntimeSpec(build?: string | null | undefined, target?: RuntimeTarget): RuntimeSpec;
+/** Variants with a published asset for a platform/arch, best first. */
+export declare function supportedVariants(platform?: NodeJS.Platform, arch?: string): RuntimeVariant[];
+/**
+ * A managed runtime is any dir under runtimesDir that contains llama-server,
+ * best accelerator first and newest build first within an accelerator.
+ */
+export declare function listManagedRuntimes(runtimesDir: string, platform?: NodeJS.Platform): Runtime[];
+/**
+ * The actionable message for a dynamic-loader failure, or null when the output
+ * is not one. Pure, so the classification is testable without spawning.
+ *
+ * Returning null for an unrecognised failure is deliberate: a future llama.cpp
+ * that exits non-zero from `--version` must not turn a perfectly usable install
+ * into a hard failure. Only a positively identified missing library throws.
+ */
+export declare function missingLibraryFrom(stderr: string): string | null;
+export declare function describeLoaderFailure(stderr: string, runtimeDir: string, platform?: NodeJS.Platform): string | null;
+/**
+ * Run the freshly installed binary once, so a missing *system* library surfaces
+ * at install time naming the library, instead of hours later as an opaque
+ * supervisor crash.
+ *
+ * This is not hypothetical: no upstream Linux asset ships `libgomp.so.1`, which
+ * `llama-server` hard-links, so on a host without `libgomp1` the download and
+ * extract both succeed and the binary then dies with exit 127. `buildEnv` cannot
+ * fix that - the library is not in the runtime dir LD_LIBRARY_PATH points at.
+ */
+export declare function verifyRuntimeExecutable(runtime: Runtime, platform?: NodeJS.Platform, arch?: string): Promise<void>;
+/**
+ * Device lines out of `--list-devices` stdout, which is a header followed by one
+ * indented line per device, or the literal `(none)`. Pure half of
+ * `listRuntimeDevices`.
+ */
+export declare function parseDeviceList(stdout: string): string[];
+/**
+ * Devices the runtime's backends actually found, one line each. Empty means the
+ * accelerator resolved to nothing and inference would silently fall back to CPU,
+ * which is a real configuration: on WSL2 there is no NVIDIA Vulkan ICD, so a
+ * Vulkan runtime on an NVIDIA machine reports no device and runs ~41x slower at
+ * prefill without saying so. Never throws; a probe failure reads as "unknown".
  */
-export declare const DEFAULT_LLAMA_BUILD = "b4600";
-/** Build the default Windows CUDA 12 spec for a given llama.cpp build tag. */
-export declare function defaultRuntimeSpec(build?: string): RuntimeSpec;
-/** A managed runtime is any dir under runtimesDir that contains llama-server.exe. */
-export declare function listManagedRuntimes(runtimesDir: string): Runtime[];
+export declare function listRuntimeDevices(runtime: Runtime, platform?: NodeJS.Platform): Promise<string[]>;
+export declare function extractArchive(archivePath: string, destDir: string, platform?: NodeJS.Platform): Promise<void>;
 /** Download + extract a runtime spec into runtimesDir and return the Runtime. */
 export declare function installManagedRuntime(spec: RuntimeSpec, runtimesDir: string, onProgress?: (progress: InstallProgress) => void): Promise<Runtime>;
 //# sourceMappingURL=managed.d.ts.map