@otto-code/brain 0.8.7 → 0.8.8

package/dist/runtime/managed.js

@@ -63,8 +63,75 @@ import { buildEnv } from "./args.js";
  */
 export const DEFAULT_LLAMA_BUILD = "b10265";
 const LLAMA_RELEASE_BASE = "https://github.com/ggml-org/llama.cpp/releases/download";
+const LLAMA_RELEASE_API = "https://api.github.com/repos/ggml-org/llama.cpp/releases";
+/**
+ * How many releases to read when resolving "latest".
+ *
+ * Not 1: the newest release is not necessarily a numbered build (upstream also
+ * publishes differently tagged and pre-release entries), and a single
+ * non-matching entry would otherwise read as "llama.cpp published no release
+ * builds" while the very next one qualified.
+ */
+const LATEST_BUILD_SCAN_PAGE = 30;
+/** Official llama.cpp builds, newest first. Only numbered build releases are actionable. */
+export async function listRuntimeReleases(limit = 100) {
+    const response = await fetch(`${LLAMA_RELEASE_API}?per_page=${Math.min(Math.max(limit, 1), 100)}`, {
+        headers: { Accept: "application/vnd.github+json" },
+    });
+    if (!response.ok)
+        throw new Error(`could not fetch llama.cpp releases (${response.status})`);
+    const releases = await response.json();
+    if (!Array.isArray(releases))
+        throw new Error("llama.cpp releases response was invalid");
+    return releases.flatMap((release) => {
+        if (!release || typeof release !== "object")
+            return [];
+        const value = release;
+        const build = typeof value.tag_name === "string" ? value.tag_name : "";
+        return /^b\d+$/.test(build)
+            ? [{ build, publishedAt: typeof value.published_at === "string" ? value.published_at : null }]
+            : [];
+    });
+}
+/** Resolve the latest official build at the last responsible moment. */
+export async function latestRuntimeBuild() {
+    const [latest] = await listRuntimeReleases(LATEST_BUILD_SCAN_PAGE);
+    if (!latest)
+        throw new Error("llama.cpp published no release builds");
+    return latest.build;
+}
+/**
+ * The build to install for a "latest" request, with the pin as the safety net.
+ *
+ * Asking upstream is a best effort, never a precondition. `listRuntimeReleases`
+ * hits api.github.com unauthenticated, which is rate limited to 60 requests per
+ * hour per IP: behind NAT, on a corporate egress or on a CI runner that is a 403
+ * on an address that has spent its budget on something else entirely. An install
+ * the pinned build can serve must not fail because a version lookup did.
+ *
+ * The warning is deliberately one line. The daemon's BrainOpsManager keeps the
+ * *last* stderr line as the job's message, so a wrapped warning would surface in
+ * the GUI as a dangling fragment.
+ */
+export async function resolveLatestBuildOrPin() {
+    try {
+        return { build: await latestRuntimeBuild(), warning: null };
+    }
+    catch (error) {
+        return {
+            build: DEFAULT_LLAMA_BUILD,
+            warning: `could not look up the latest llama.cpp build (${oneLine(error)}), so Otto installed` +
+                ` the pinned build ${DEFAULT_LLAMA_BUILD} instead.`,
+        };
+    }
+}
+/** Flatten a message to one line, so a warning survives the last-line rule. */
+function oneLine(error) {
+    return (error instanceof Error ? error.message : String(error)).replace(/\s+/gu, " ").trim();
+}
 /** The CUDA toolkit version whose Windows assets we pin. */
 const WINDOWS_CUDA = "12.4";
+const MANAGED_RUNTIME_METADATA_FILE = ".otto-runtime.json";
 /** The binary name llama.cpp ships for a platform. */
 export function serverExeName(platform = process.platform) {
     return platform === "win32" ? "llama-server.exe" : "llama-server";
@@ -181,6 +248,34 @@ function slug(spec) {
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/(^-|-$)/g, "");
 }
+function displayNameForManagedRuntime(label, version) {
+    return `${label.replace(/\s*\(managed\)$/iu, "")} · ${version} (Otto managed)`;
+}
+function legacyManagedDisplayName(dirName, version) {
+    const cuda = /^cuda-(\d+)-(\d+)-managed(?:-|$)/iu.exec(dirName);
+    if (cuda)
+        return `CUDA ${cuda[1]}.${cuda[2]} · ${version} (Otto managed)`;
+    if (/^vulkan-managed(?:-|$)/iu.test(dirName))
+        return `Vulkan · ${version} (Otto managed)`;
+    if (/^metal-managed(?:-|$)/iu.test(dirName))
+        return `Metal · ${version} (Otto managed)`;
+    if (/^cpu-managed(?:-|$)/iu.test(dirName))
+        return `CPU · ${version} (Otto managed)`;
+    return `${version} (Otto managed)`;
+}
+function readManagedRuntimeDisplayName(root, dirName, version) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(root, MANAGED_RUNTIME_METADATA_FILE), "utf8"));
+        if (typeof parsed.displayName === "string" && parsed.displayName.trim()) {
+            return parsed.displayName;
+        }
+    }
+    catch {
+        // Existing installations predate metadata; their directory name remains a
+        // backend-only migration source, never a UI presentation contract.
+    }
+    return legacyManagedDisplayName(dirName, version);
+}
 /** Recursively find the first file named `name` under `dir`. */
 function findFile(dir, name) {
     const entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -230,9 +325,11 @@ export function listManagedRuntimes(runtimesDir, platform = process.platform) {
         const exe = findFile(root, exeName);
         if (!exe)
             continue;
+        const version = entry.name.replace(/^.*-/, "");
         found.push({
             label: entry.name,
-            version: entry.name.replace(/^.*-/, ""),
+            displayName: readManagedRuntimeDisplayName(root, entry.name, version),
+            version,
             dir: path.dirname(exe),
             exe,
             vendorDir: null,
@@ -242,8 +339,24 @@ export function listManagedRuntimes(runtimesDir, platform = process.platform) {
     return found.sort((a, b) => managedVariantRank(a.label) - managedVariantRank(b.label) ||
         buildNumber(b.version) - buildNumber(a.version));
 }
+/**
+ * An asset upstream does not serve at all, which is what a renamed asset or a
+ * tag without the expected build looks like from here. Distinguished from every
+ * other download failure because it is the one a caller can answer by retrying
+ * a build whose asset names are pinned and tested, rather than by retrying the
+ * same URL later.
+ */
+export class MissingAssetError extends Error {
+    constructor(url) {
+        super(`download failed (404) for ${url}`);
+        this.url = url;
+        this.name = "MissingAssetError";
+    }
+}
 async function downloadFile(url, dest, onProgress) {
     const response = await fetch(url);
+    if (response.status === 404)
+        throw new MissingAssetError(url);
     if (!response.ok || !response.body) {
         throw new Error(`download failed (${response.status}) for ${url}`);
     }
@@ -480,13 +593,26 @@ export async function extractArchive(archivePath, destDir, platform = process.pl
 export async function installManagedRuntime(spec, runtimesDir, onProgress) {
     const platform = spec.platform ?? process.platform;
     const targetDir = path.join(runtimesDir, slug(spec));
+    const preexisting = fs.existsSync(targetDir);
     fs.mkdirSync(targetDir, { recursive: true });
-    for (const url of spec.assets) {
-        const archivePath = path.join(targetDir, path.basename(new URL(url).pathname));
-        await downloadFile(url, archivePath, onProgress);
-        onProgress?.({ phase: "extracting", asset: url });
-        await extractArchive(archivePath, targetDir, platform);
-        fs.rmSync(archivePath, { force: true });
+    try {
+        for (const url of spec.assets) {
+            const archivePath = path.join(targetDir, path.basename(new URL(url).pathname));
+            await downloadFile(url, archivePath, onProgress);
+            onProgress?.({ phase: "extracting", asset: url });
+            await extractArchive(archivePath, targetDir, platform);
+            fs.rmSync(archivePath, { force: true });
+        }
+    }
+    catch (error) {
+        // A half-installed directory is worse than no directory: Windows CUDA needs
+        // two archives, so a 404 on the companion leaves a llama-server with no CUDA
+        // runtime beside it, and `listManagedRuntimes` ranks by build number - that
+        // newer, broken build would then outrank the working runtime it replaced.
+        // Only a directory this call created is removed; an existing install stands.
+        if (!preexisting)
+            fs.rmSync(targetDir, { recursive: true, force: true });
+        throw error;
     }
     const exeName = serverExeName(platform);
     const exe = findFile(targetDir, exeName);
@@ -499,6 +625,7 @@ export async function installManagedRuntime(spec, runtimesDir, onProgress) {
     }
     const runtime = {
         label: spec.label,
+        displayName: displayNameForManagedRuntime(spec.label, spec.version),
         version: spec.version,
         dir: path.dirname(exe),
         exe,
@@ -508,7 +635,19 @@ export async function installManagedRuntime(spec, runtimesDir, onProgress) {
     // Before reporting success. An install that cannot exec is not an install, and
     // the loader error names the cause far better than the later spawn failure does.
     await verifyRuntimeExecutable(runtime, platform);
+    fs.writeFileSync(path.join(targetDir, MANAGED_RUNTIME_METADATA_FILE), `${JSON.stringify({ displayName: runtime.displayName })}\n`);
     onProgress?.({ phase: "done" });
     return runtime;
 }
+/** Remove one Otto-managed runtime. LM Studio files are outside this root. */
+export function removeManagedRuntime(runtimesDir, name) {
+    if (!/^[a-z0-9][a-z0-9-]*$/i.test(name))
+        throw new Error("invalid runtime name");
+    const root = path.resolve(runtimesDir);
+    const target = path.resolve(root, name);
+    if (path.dirname(target) !== root || !fs.existsSync(target)) {
+        throw new Error(`managed runtime not found: ${name}`);
+    }
+    fs.rmSync(target, { recursive: true, force: false });
+}
 //# sourceMappingURL=managed.js.map

package/dist/service/host-api.d.ts

@@ -82,11 +82,11 @@ export interface HostCapabilities {
 /** A long-running operation owned by this brain host, not its caller. */
 export interface HostJob {
     id: string;
-    kind: "pull" | "runtime-install" | "calibrate" | "sweep" | "bench";
+    kind: "pull" | "runtime-install" | "runtime-remove" | "calibrate" | "sweep" | "bench";
     label: string;
     target: string | null;
     status: "running" | "succeeded" | "failed" | "canceled";
-    percent: null;
+    percent: number | null;
     message: string | null;
     error: string | null;
     startedAt: string;
@@ -153,6 +153,7 @@ export interface InventoryRow {
     score: RankedModel | null;
     state: "loaded" | "loading" | "not-loaded";
     warnings: ReturnType<typeof profileWarnings>;
+    components: NonNullable<Model["components"]> | null;
 }
 /**
  * Join one model's scan row, GGUF metadata, saved profile, calibration, VRAM

package/dist/service/host-api.js

@@ -1,6 +1,6 @@
 import { calibrationInfo, profileFieldDescriptors, profileWarnings, sanitizeProfilePatch, } from "../config/profile-edit.js";
 import { forModel, getCalibration, put } from "../config/profiles.js";
-import { deleteModelFiles, diskUsage, planDelete, totalModelBytes } from "../models/manage.js";
+import { deleteComponentFile, deleteModelFiles, diskUsage, planDelete, totalModelBytes, } from "../models/manage.js";
 import { deleteDisplayName, updateDisplayName } from "../models/rename-map.js";
 import * as vram from "../vram.js";
 import { errorMessage, readJsonBody, sendError, sendJson } from "./http-util.js";
@@ -60,7 +60,11 @@ export function buildInventoryRow(params) {
         contextLength: model.metadata?.contextLength ?? null,
         blockCount: model.metadata?.blockCount ?? null,
         headCountKv: model.metadata?.headCountKv ?? null,
-        hasProjector: Boolean(model.mmprojPath),
+        // A bundle declares vision capability even before its projector is
+        // downloaded. The badge describes what the model supports, while the
+        // profile's component row describes whether that artifact is ready.
+        hasProjector: Boolean(model.mmprojPath) ||
+            Boolean(model.components?.some((component) => component.role === "vision_projector")),
         reasoning: Boolean(model.metadata?.reasoning ?? model.thinking),
         mtp: Boolean(model.features?.mtp),
         distilled: Boolean(model.features?.distilled),
@@ -73,8 +77,24 @@ export function buildInventoryRow(params) {
         score: ranked,
         state: stateOf(supervisor, model),
         warnings: profileWarnings(profile, model, store),
+        components: model.components ?? null,
     };
 }
+/**
+ * Reject a request value that the CLI would read as a flag rather than as a
+ * value.
+ *
+ * An option value has to sit before the `--` separator by construction - the
+ * separator only ends *positional* parsing - so unlike `model` and `repo` these
+ * cannot be moved out of harm's way, and the argv is unambiguous only if the
+ * value itself is. The throw surfaces as the route's 400, next to the type
+ * checks in each `makeArgs`.
+ */
+function optionValue(label, value) {
+    if (value.startsWith("-"))
+        throw new Error(`${label} must not start with "-"`);
+    return value;
+}
 /** Resolve a model by id or display name, the same way the completion path does. */
 function resolveModel(catalog, needle) {
     if (!needle)
@@ -352,6 +372,24 @@ export function createHostApi(deps) {
             sendError(res, 500, `could not delete ${model.displayName}: ${errorMessage(error)}`);
         }
     };
+    const handleComponentDelete = (res, model, componentId) => {
+        if (deps.supervisor.model?.id === model.id && deps.supervisor.state !== "stopped") {
+            sendError(res, 409, "stop the model before removing a bundle component");
+            return;
+        }
+        try {
+            const plan = deleteComponentFile(model, componentId);
+            deps.rescan();
+            sendJson(res, {
+                deleted: plan.files,
+                freedBytes: plan.bytes,
+                componentIds: plan.componentIds,
+            });
+        }
+        catch (error) {
+            sendError(res, 409, errorMessage(error));
+        }
+    };
     const handleLogs = (res, params) => {
         const raw = Number(params.get("limit"));
         const limit = Number.isFinite(raw) && raw > 0 ? Math.min(Math.round(raw), 1000) : DEFAULT_LOG_LINES;
@@ -482,7 +520,7 @@ export function createHostApi(deps) {
                     sendJson(res, {
                         job: deps.jobs?.start("bench", model ?? null, [
                             "bench",
-                            ...(model ? ["--model", model] : []),
+                            ...(model ? ["--model", optionValue("model", model)] : []),
                         ]) ?? null,
                     });
                 }
@@ -499,7 +537,25 @@ export function createHostApi(deps) {
                     const model = body.model;
                     if (typeof model !== "string" || !model)
                         throw new Error("model is required");
-                    return { target: model, args: ["pull", "--json", "--", model] };
+                    const components = body.components;
+                    const quant = body.quant;
+                    if (components !== undefined &&
+                        (!Array.isArray(components) || !components.every((id) => typeof id === "string"))) {
+                        throw new Error("components must be component ids");
+                    }
+                    if (quant !== undefined && typeof quant !== "string")
+                        throw new Error("quant must be a string");
+                    return {
+                        target: model,
+                        args: [
+                            "pull",
+                            ...(typeof quant === "string" ? ["--quant", optionValue("quant", quant)] : []),
+                            ...(components ?? []).flatMap((id) => ["--component", optionValue("component", id)]),
+                            "--json",
+                            "--",
+                            model,
+                        ],
+                    };
                 },
             },
             "/__host/jobs/add": {
@@ -507,11 +563,24 @@ export function createHostApi(deps) {
                 makeArgs: (body) => {
                     const repo = body.repo;
                     const quant = body.quant;
+                    const components = body.components;
                     if (typeof repo !== "string" || !repo || typeof quant !== "string" || !quant)
                         throw new Error("repo and quant are required");
+                    if (components !== undefined &&
+                        (!Array.isArray(components) || !components.every((id) => typeof id === "string")))
+                        throw new Error("components must be component ids");
                     return {
                         target: `${repo}#${quant}`,
-                        args: ["add", "--quant", quant, "--json", "--", repo],
+                        args: [
+                            "add",
+                            "--quant",
+                            optionValue("quant", quant),
+                            ...(components === undefined ? [] : ["--primary-only"]),
+                            ...(components ?? []).flatMap((id) => ["--component", optionValue("component", id)]),
+                            "--json",
+                            "--",
+                            repo,
+                        ],
                     };
                 },
             },
@@ -527,18 +596,36 @@ export function createHostApi(deps) {
                             "runtime",
                             "install",
                             "--json",
-                            ...(typeof build === "string" ? ["--build", build] : []),
+                            ...(typeof build === "string" ? ["--build", optionValue("build", build)] : []),
                         ],
                     };
                 },
             },
+            // Removal is host-owned for the same reason installation is: the runtimes
+            // directory belongs to this machine. A daemon in brain.mode=remote that ran
+            // this locally would delete a same-named runtime out of its own OTTO_HOME.
+            "/__host/jobs/runtime-remove": {
+                kind: "runtime-remove",
+                makeArgs: (body) => {
+                    const name = body.name;
+                    if (typeof name !== "string" || !name)
+                        throw new Error("name is required");
+                    // Pass the name as an operand, not as a flag candidate. The CLI still
+                    // owns the real safety check (the name regex plus the parent-dir
+                    // assertion in removeManagedRuntime).
+                    return { target: name, args: ["runtime", "remove", "--json", "--", name] };
+                },
+            },
             "/__host/jobs/calibrate": {
                 kind: "calibrate",
                 makeArgs: (body) => {
                     const model = body.model;
                     if (typeof model !== "string" || !model)
                         throw new Error("model is required");
-                    return { target: model, args: ["calibrate", "--model", model, "--json"] };
+                    return {
+                        target: model,
+                        args: ["calibrate", "--model", optionValue("model", model), "--json"],
+                    };
                 },
             },
             "/__host/jobs/sweep": {
@@ -547,7 +634,10 @@ export function createHostApi(deps) {
                     const model = body.model;
                     if (typeof model !== "string" || !model)
                         throw new Error("model is required");
-                    return { target: model, args: ["sweep", "--model", model, "--json"] };
+                    return {
+                        target: model,
+                        args: ["sweep", "--model", optionValue("model", model), "--json"],
+                    };
                 },
             },
         };
@@ -636,6 +726,14 @@ export function createHostApi(deps) {
             handleModelsList(res);
             return true;
         }
+        // A local daemon may run downloads in its own tracked job process while
+        // this service owns the in-memory inventory. Reconcile that disk mutation
+        // without restarting the host or unloading its resident model.
+        if (route === "/__host/models/rescan" && method === "POST") {
+            const models = deps.rescan();
+            sendJson(res, { models: models.length });
+            return true;
+        }
         if (route === "/__host/model/unload" && method === "POST") {
             if (!guardWrite(res))
                 return true;
@@ -651,6 +749,7 @@ export function createHostApi(deps) {
             "/__host/model/fields",
             "/__host/model/rename",
             "/__host/model/rename/reset",
+            "/__host/model/component",
         ]);
         if (!modelRoutes.has(route))
             return false;
@@ -702,6 +801,17 @@ export function createHostApi(deps) {
             handleDelete(res, model);
             return true;
         }
+        if (route === "/__host/model/component" && method === "DELETE") {
+            if (!guardWrite(res))
+                return true;
+            const componentId = params.get("component");
+            if (!componentId) {
+                sendError(res, 400, "a component query parameter is required");
+                return true;
+            }
+            handleComponentDelete(res, model, componentId);
+            return true;
+        }
         if (route === "/__host/model" && method === "GET") {
             // A single inventory row, for a detail pane that does not want the whole list.
             void (async () => {

package/dist/service/serve.js

@@ -24,6 +24,7 @@ import { resolveVersion } from "../version.js";
 import * as results from "../ops/results.js";
 import { createCpuSampler, sample as sampleSystem } from "../sysmon.js";
 import { createHostApi } from "./host-api.js";
+import { errorMessage } from "./http-util.js";
 import { createRouter, Telemetry } from "./router.js";
 import { BrainStatusPublisher } from "./status-events.js";
 import { Supervisor } from "./supervisor.js";
@@ -63,7 +64,8 @@ const REMOTE_JOB_RETENTION_MS = 5 * 60000;
  * directory and GPU all belong to the host that is being benchmarked.
  */
 class ServiceJobRunner {
-    constructor() {
+    constructor(onPullCompleted) {
+        this.onPullCompleted = onPullCompleted;
         this.jobs = new Map();
     }
     start(kind, target, args) {
@@ -101,16 +103,24 @@ class ServiceJobRunner {
         job.child = child;
         this.jobs.set(job.id, job);
         child.stderr?.setEncoding("utf8");
-        child.stderr?.on("data", (chunk) => {
-            const last = chunk.trim().split(/\r?\n/).at(-1)?.trim();
-            if (last)
-                job.message = last.slice(-1000);
-        });
+        child.stderr?.on("data", (chunk) => this.ingestOutput(job, chunk));
         child.once("error", (error) => this.finish(job, "failed", error.message));
         child.once("close", (code) => {
             if (job.status !== "running")
                 return;
-            this.finish(job, code === 0 ? "succeeded" : "failed", code === 0 ? null : `Exited with code ${code}.`);
+            if (code === 0 && kind === "pull") {
+                try {
+                    // Downloads happen in a child process, but inventory is served from
+                    // this process's in-memory scan. Reconcile before reporting success
+                    // so a newly downloaded bundle component is immediately available.
+                    this.onPullCompleted();
+                }
+                catch (error) {
+                    this.finish(job, "failed", `Downloaded files, but could not refresh inventory: ${errorMessage(error)}`);
+                    return;
+                }
+            }
+            this.finish(job, code === 0 ? "succeeded" : "failed", code === 0 ? null : (job.message ?? `Exited with code ${code}.`));
         });
         return this.publicJob(job);
     }
@@ -168,6 +178,20 @@ class ServiceJobRunner {
         this.finish(job, "canceled", "Canceled.");
         return this.list();
     }
+    ingestOutput(job, chunk) {
+        for (const line of chunk
+            .split(/[\r\n]+/u)
+            .map((value) => value.trim())
+            .filter(Boolean)) {
+            const progress = /(\d{1,3})\s*%/u.exec(line);
+            if (progress)
+                job.percent = Math.max(0, Math.min(100, Number(progress[1])));
+            // The final JSON result is not a useful status label. Keep progress and
+            // actionable text instead, so a failed bundle pull tells the user why.
+            if (line !== "[" && !/^[\]{}",]+$/u.test(line))
+                job.message = line.slice(-1000);
+        }
+    }
     finish(job, status, error) {
         if (job.status !== "running")
             return;
@@ -175,6 +199,8 @@ class ServiceJobRunner {
         job.status = status;
         job.error = error;
         job.finishedAt = new Date().toISOString();
+        if (status === "succeeded")
+            job.percent = 100;
     }
     publicJob({ child: _child, ...job }) {
         return job;
@@ -266,6 +292,10 @@ export async function startService({ config, modelNeedle, env = process.env, onL
     // Not const: deleting a model through the management API re-scans and replaces
     // this, and every reader goes through a getter so nobody holds a stale array.
     let catalog = scanModels(config, env);
+    const rescanCatalog = () => {
+        catalog = scanModels(config, env);
+        return catalog;
+    };
     const needle = modelNeedle ?? config.defaultModel ?? store.lastModelId ?? undefined;
     let model = null;
     if (catalog.length > 0) {
@@ -389,17 +419,14 @@ export async function startService({ config, modelNeedle, env = process.env, onL
     // /__host/events. One instance, so `capabilities.events` and the stream can
     // never disagree about whether this brain publishes.
     const statusEvents = new BrainStatusPublisher();
-    const jobs = new ServiceJobRunner();
+    const jobs = new ServiceJobRunner(rescanCatalog);
     // Assigned once `stop` exists below. This indirection lets the management API
     // answer a remote restart request before closing its own socket.
     let requestRestart = () => { };
     const hostApi = createHostApi({
         supervisor,
         getCatalog: () => catalog,
-        rescan: () => {
-            catalog = scanModels(config, env);
-            return catalog;
-        },
+        rescan: rescanCatalog,
         getProfilesStore: () => store,
         saveProfiles: (next) => saveProfilesStore(next, paths),
         getProfileDefaults: () => config.defaults,

package/dist/types.d.ts

@@ -26,6 +26,22 @@ export interface ModelFeatures {
     imatrix: boolean;
     distilled: boolean;
 }
+export type ModelComponentRole = "vision_projector" | "speculative_drafter";
+/** A catalog-declared companion artifact resolved against local disk. */
+export interface ModelComponent {
+    id: string;
+    label: string;
+    description: string;
+    role: ModelComponentRole;
+    path: string | null;
+    bytes: number;
+    required: boolean;
+    defaultDownload: boolean;
+    defaultLoad: boolean;
+    available: boolean;
+    unavailableReason?: string;
+    minRuntimeBuild?: number;
+}
 /** A GGUF model discovered on disk (or resolvable from the download catalog). */
 export interface Model {
     id: string;
@@ -57,10 +73,14 @@ export interface Model {
     catalogId?: string;
     /** Back-reference: the hfRepo of the reconciled catalog entry, if matched. */
     catalogHfRepo?: string;
+    /** Present only when this catalog entry declares a component manifest. */
+    components?: ModelComponent[];
 }
 /** A resolved llama.cpp runtime: an executable paired with its vendor DLL dir. */
 export interface Runtime {
     label: string;
+    /** Human-readable runtime identity, separate from the filesystem-safe label. */
+    displayName?: string;
     version: string;
     dir: string;
     exe: string;

package/dist/vram.d.ts

@@ -21,6 +21,9 @@ export type BudgetSource = "measured" | "theoretical" | "unknown";
 export interface Budget {
     weightsBytes: number;
     mmprojBytes: number;
+    componentBytes: number;
+    drafterKvBytes: number;
+    imageProcessingBytes: number;
     kvBytes: number;
     overheadBytes: number;
     totalBytes: number;

package/dist/vram.js

@@ -35,7 +35,17 @@ export function theoreticalKvBytesPerToken(metadata, cacheTypeK, cacheTypeV) {
 /** Compute a VRAM budget for a profile. */
 export function budget({ model, profile, calibration = null, totalVramBytes, reserveBytes = 1.5 * GIB, }) {
     const weights = model.sizeBytes;
-    const mmproj = profile.vision && model.mmprojPath ? model.mmprojBytes : 0;
+    const enabled = new Set(profile.enabledComponents ?? []);
+    const components = model.components ?? [];
+    const projector = components.filter((component) => component.role === "vision_projector" && enabled.has(component.id) && component.available);
+    const drafters = components.filter((component) => component.role === "speculative_drafter" && enabled.has(component.id) && component.available);
+    const componentBytes = components.length
+        ? [...projector, ...drafters].reduce((total, component) => total + component.bytes, 0)
+        : profile.vision && model.mmprojPath
+            ? model.mmprojBytes
+            : 0;
+    const mmproj = projector.reduce((total, component) => total + component.bytes, 0) ||
+        (components.length ? 0 : componentBytes);
     const theoretical = theoreticalKvBytesPerToken(model.metadata, profile.cacheTypeK, profile.cacheTypeV);
     let kvBytesPerToken;
     let source;
@@ -52,14 +62,22 @@ export function budget({ model, profile, calibration = null, totalVramBytes, res
         source = "unknown";
     }
     const kv = kvBytesPerToken * profile.contextSize;
+    // The speculative decoder keeps its own KV cache. Until component-specific
+    // calibration exists, reserve the same conservative per-token cost.
+    const drafterKv = drafters.length * kv;
+    // Vision preprocessing needs transient GPU buffers in addition to weights.
+    const imageProcessing = projector.length * 256 * 1024 * 1024;
     // Compute buffers and the CUDA context; measured at ~0.6 GB for a 27B and
     // superseded by the calibrated value when available.
     const overhead = calibration && calibration.baseOverheadBytes > 0 ? calibration.baseOverheadBytes : 0.6 * GIB;
-    const total = weights + mmproj + kv + overhead;
+    const total = weights + componentBytes + kv + drafterKv + imageProcessing + overhead;
     const usable = totalVramBytes - reserveBytes;
     return {
         weightsBytes: weights,
         mmprojBytes: mmproj,
+        componentBytes,
+        drafterKvBytes: drafterKv,
+        imageProcessingBytes: imageProcessing,
         kvBytes: kv,
         overheadBytes: overhead,
         totalBytes: total,
@@ -85,7 +103,7 @@ export function maxContextThatFits({ model, profile, calibration, totalVramBytes
     });
     if (probe.kvBytesPerToken <= 0)
         return null;
-    const fixed = probe.weightsBytes + probe.mmprojBytes + probe.overheadBytes;
+    const fixed = probe.weightsBytes + probe.componentBytes + probe.imageProcessingBytes + probe.overheadBytes;
     const room = probe.usableBytes - fixed;
     if (room <= 0)
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@otto-code/brain",
-  "version": "0.8.7",
+  "version": "0.8.8",
   "description": "Otto Brain - self-contained host for local GGUF models, with measured VRAM budgeting and reasoning-budget control",
   "license": "AGPL-3.0-or-later",
   "bin": {