@otto-code/brain 0.7.6 → 0.8.1

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