@otto-code/brain 0.8.7 → 0.8.9

package/dist/service/host-api.js

@@ -1,11 +1,24 @@
+import { randomUUID } from "node:crypto";
 import { calibrationInfo, profileFieldDescriptors, profileWarnings, sanitizeProfilePatch, } from "../config/profile-edit.js";
+import { familyHostingProfileId, hostingFamily, removeHostingProfileMaterialization, } from "../config/hosting-profiles.js";
 import { forModel, getCalibration, put } from "../config/profiles.js";
-import { deleteModelFiles, diskUsage, planDelete, totalModelBytes } from "../models/manage.js";
+import { HostingProfileSchema, } from "../config/schema.js";
+import { deleteComponentFile, deleteModelFiles, diskUsage, planDelete, totalModelBytes, } from "../models/manage.js";
 import { deleteDisplayName, updateDisplayName } from "../models/rename-map.js";
+import { runtimeBuild } from "../runtime/index.js";
 import * as vram from "../vram.js";
 import { errorMessage, readJsonBody, sendError, sendJson } from "./http-util.js";
 const MAX_PATCH_BYTES = 256 * 1024;
 const MAX_DISPLAY_NAME = 200;
+const MAX_HOSTING_PROFILE_NAME = 80;
+const MAX_HOSTING_PROFILE_TEXT = 128 * 1024;
+const MAX_HOSTING_PROFILES = 100;
+const MAX_HOSTING_PROFILE_ID = 80;
+const HOSTING_PROFILE_ID = /^[a-zA-Z0-9_-]+$/u;
+// Keep product-owned records immutable through this API. Their source lives in
+// builtin-hosting-profiles.ts, so an update would otherwise look successful but
+// be replaced at the next Brain start with no user-facing restore action.
+const BUILTIN_HOSTING_PROFILE_IDS = new Set(["qwen-sharp-v21.3"]);
 const DEFAULT_LOG_LINES = 200;
 /**
  * The management API's own version, additive to the capability flags.
@@ -24,6 +37,139 @@ export const HOST_API_VERSION = 3;
  * fine. Comments are ignored by every SSE parser, so no reader sees them.
  */
 const SSE_KEEPALIVE_MS = 20000;
+/**
+ * Apply the hosting-profile half of a profile patch, mutating both `profile`
+ * (this model's selection) and `store` (the shared library and family default).
+ *
+ * Separate from `sanitizeProfilePatch` because these keys are not profile
+ * fields: three of the five write to the store rather than the profile.
+ * Exported for testing - the ordering and the cross-profile cleanup are the
+ * parts worth pinning down, and they are unreachable through the HTTP surface
+ * without standing up a service.
+ *
+ * Throws on any invalid input; the caller turns that into a 400.
+ */
+export function applyHostingProfilePatch(store, model, profile, patch, onDelete = undefined) {
+    const family = hostingFamily(model.family);
+    if ("hostingProfileId" in patch) {
+        const selected = patch.hostingProfileId;
+        if (selected !== null && typeof selected !== "string") {
+            throw new Error("hostingProfileId must be a string or null");
+        }
+        if (selected && !store.hostingProfiles[selected]) {
+            throw new Error("selected hosting profile does not exist");
+        }
+        profile.hostingProfileId = selected || null;
+        profile.hostingProfileMode = selected ? "custom" : "off";
+    }
+    // After the id, so a client can send both and have the explicit mode win.
+    if ("hostingProfileMode" in patch) {
+        const mode = patch.hostingProfileMode;
+        if (mode !== "inherit" && mode !== "off" && mode !== "custom") {
+            throw new Error("hostingProfileMode must be inherit, off, or custom");
+        }
+        if (mode === "custom" && !profile.hostingProfileId) {
+            throw new Error("select a custom profile before using custom mode");
+        }
+        profile.hostingProfileMode = mode;
+    }
+    if ("familyHostingProfileId" in patch) {
+        const selected = patch.familyHostingProfileId;
+        if (selected !== null && typeof selected !== "string") {
+            throw new Error("familyHostingProfileId must be a string or null");
+        }
+        if (selected && !store.hostingProfiles[selected]) {
+            throw new Error("selected family hosting profile does not exist");
+        }
+        if (selected && store.hostingProfiles[selected].family !== family) {
+            throw new Error("selected family hosting profile must match the selected model");
+        }
+        // Null is a real instruction: it is the only way off a family default.
+        store.familyHostingProfileIds[family] = selected || null;
+    }
+    if ("hostingProfile" in patch) {
+        const candidate = HostingProfileSchema.safeParse(patch.hostingProfile);
+        if (!candidate.success)
+            throw new Error("hosting profile is invalid");
+        const item = candidate.data;
+        // Name the field that is wrong. One shared "name or text is too long" for an
+        // empty name, a missing template and an oversized addendum told a remote or
+        // CLI caller nothing about what to change.
+        if (item.name.trim().length === 0)
+            throw new Error("hosting profile needs a name");
+        if (item.name.length > MAX_HOSTING_PROFILE_NAME) {
+            throw new Error(`hosting profile name must be ${MAX_HOSTING_PROFILE_NAME} characters or fewer`);
+        }
+        if (!item.template?.trim())
+            throw new Error("hosting profile needs a Jinja chat template");
+        if (item.template.length > MAX_HOSTING_PROFILE_TEXT) {
+            throw new Error("hosting profile chat template is too long");
+        }
+        if ((item.systemPromptAddendum?.length ?? 0) > MAX_HOSTING_PROFILE_TEXT) {
+            throw new Error("hosting profile system prompt is too long");
+        }
+        if (item.family !== family) {
+            throw new Error("hosting profile family must match the selected model");
+        }
+        const isNew = item.id.length === 0;
+        const id = isNew ? `hosting_${randomUUID()}` : item.id;
+        if (!isNew && BUILTIN_HOSTING_PROFILE_IDS.has(id)) {
+            throw new Error("built-in hosting profiles cannot be edited");
+        }
+        if (!isNew && (id.length > MAX_HOSTING_PROFILE_ID || !HOSTING_PROFILE_ID.test(id))) {
+            throw new Error(`hosting profile id must use only letters, numbers, underscores, or hyphens and be ${MAX_HOSTING_PROFILE_ID} characters or fewer`);
+        }
+        if (!isNew && !store.hostingProfiles[id]) {
+            throw new Error("hosting profile does not exist; create profiles without an id");
+        }
+        if (isNew && Object.keys(store.hostingProfiles).length >= MAX_HOSTING_PROFILES) {
+            throw new Error(`hosting profile limit of ${MAX_HOSTING_PROFILES} reached`);
+        }
+        store.hostingProfiles[id] = { ...item, id, name: item.name.trim() };
+        // Only a freshly created profile is auto-selected. Editing the text of an
+        // existing one must not silently convert a model that was on System default
+        // into a custom override of it.
+        if (isNew) {
+            profile.hostingProfileId = id;
+            profile.hostingProfileMode = "custom";
+        }
+    }
+    if (typeof patch.deleteHostingProfileId === "string") {
+        const id = patch.deleteHostingProfileId;
+        if (BUILTIN_HOSTING_PROFILE_IDS.has(id)) {
+            throw new Error("built-in hosting profiles cannot be deleted");
+        }
+        delete store.hostingProfiles[id];
+        onDelete?.(id);
+        if (profile.hostingProfileId === id) {
+            profile.hostingProfileId = null;
+            profile.hostingProfileMode = "off";
+        }
+        // Clear the mode alongside the id on every other model. Leaving `custom`
+        // behind with no id left those models unsavable: the mode guard above
+        // rejects the next write each of them makes.
+        for (const saved of Object.values(store.profiles)) {
+            if (saved.hostingProfileId !== id)
+                continue;
+            saved.hostingProfileId = null;
+            saved.hostingProfileMode = "off";
+        }
+        for (const [key, selected] of Object.entries(store.familyHostingProfileIds)) {
+            if (selected === id)
+                store.familyHostingProfileIds[key] = null;
+        }
+    }
+    // One invariant, enforced after every branch: an id belongs only to `custom`.
+    // It is what lets `forModel`'s legacy migration read a stored id as an
+    // unambiguous "this profile predates hostingProfileMode".
+    if (profile.hostingProfileMode !== "custom")
+        profile.hostingProfileId = null;
+}
+/** The hosting profiles a model may choose from: its family's bucket, nothing else. */
+function hostingProfilesFor(store, model) {
+    const family = hostingFamily(model.family);
+    return Object.values(store.hostingProfiles).filter((candidate) => candidate.family === family);
+}
 function stateOf(supervisor, model) {
     if (!supervisor.model || supervisor.model.id !== model.id)
         return "not-loaded";
@@ -41,9 +187,9 @@ function stateOf(supervisor, model) {
  * client would otherwise have to correlate three unrelated lists by display name.
  */
 export function buildInventoryRow(params) {
-    const { model, store, defaults, gpu, ranking, supervisor } = params;
+    const { model, store, defaults, gpu, ranking, supervisor, runtimeBuild: activeRuntimeBuild = null, } = params;
     const profile = forModel(store, model, defaults);
-    const calibration = getCalibration(store, model, profile);
+    const calibration = profile.calibrationRequired ? null : getCalibration(store, model, profile);
     const budgetOptions = gpu
         ? { model, profile, calibration, totalVramBytes: gpu.totalBytes }
         : null;
@@ -51,6 +197,7 @@ export function buildInventoryRow(params) {
     return {
         id: model.id,
         displayName: model.displayName,
+        family: model.family ?? null,
         publisher: model.publisher ?? null,
         quant: model.quant,
         sizeBytes: model.sizeBytes,
@@ -60,7 +207,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 +224,36 @@ export function buildInventoryRow(params) {
         score: ranked,
         state: stateOf(supervisor, model),
         warnings: profileWarnings(profile, model, store),
+        components: model.components?.map((component) => {
+            if (component.minRuntimeBuild === undefined ||
+                (activeRuntimeBuild !== null && activeRuntimeBuild >= component.minRuntimeBuild)) {
+                return component;
+            }
+            const active = activeRuntimeBuild === null ? "unknown" : `b${activeRuntimeBuild}`;
+            return {
+                ...component,
+                available: false,
+                unavailableReason: `Requires llama.cpp build b${component.minRuntimeBuild} or newer ` +
+                    `(active build: ${active})`,
+            };
+        }) ?? 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)
@@ -106,7 +285,7 @@ function profileFromQuery(base, params, model) {
     }
     if (Object.keys(patch).length === 0)
         return base;
-    return sanitizeProfilePatch(base, patch, model).profile;
+    return sanitizeProfilePatch(base, patch, model, runtimeBuild(null)).profile;
 }
 /**
  * Build the `/__host/*` management handler.
@@ -142,9 +321,15 @@ export function createHostApi(deps) {
         const [gpu, store] = [await deps.queryGpuInfo(), deps.getProfilesStore()];
         const defaults = deps.getProfileDefaults();
         const ranking = deps.getRanking();
-        return deps
-            .getCatalog()
-            .map((model) => buildInventoryRow({ model, store, defaults, gpu, ranking, supervisor: deps.supervisor }));
+        return deps.getCatalog().map((model) => buildInventoryRow({
+            model,
+            store,
+            defaults,
+            gpu,
+            ranking,
+            supervisor: deps.supervisor,
+            runtimeBuild: runtimeBuild(deps.supervisor.runtime),
+        }));
     };
     const handleModelsList = (res) => {
         void (async () => {
@@ -167,9 +352,12 @@ export function createHostApi(deps) {
         const profile = forModel(store, model, deps.getProfileDefaults());
         sendJson(res, {
             profile,
-            fields: profileFieldDescriptors(model),
+            fields: profileFieldDescriptors(model, profile),
             warnings: profileWarnings(profile, model, store),
             calibration: calibrationInfo(store, model, profile),
+            requiresRestart: store.pendingReloadModelIds[model.id] === true,
+            hostingProfiles: hostingProfilesFor(store, model),
+            familyHostingProfileId: familyHostingProfileId(store, model.family),
         });
     };
     const handleProfileSet = (req, res, model) => {
@@ -182,24 +370,38 @@ export function createHostApi(deps) {
                 try {
                     const store = deps.getProfilesStore();
                     const current = forModel(store, model, deps.getProfileDefaults());
-                    const { profile, adjustments } = sanitizeProfilePatch(current, result.body, model);
-                    deps.saveProfiles(put(store, model, profile));
+                    const activeRuntimeBuild = runtimeBuild(deps.supervisor.runtime);
+                    const { profile, adjustments } = sanitizeProfilePatch(current, result.body, model, activeRuntimeBuild);
+                    applyHostingProfilePatch(store, model, profile, result.body, (id) => removeHostingProfileMaterialization(deps.supervisor.paths, id));
+                    put(store, model, profile);
+                    // A setting is only unapplied when it was changed on the currently
+                    // resident model. Edits to an unloaded model take effect naturally
+                    // when it is next loaded and do not earn a misleading reload badge.
+                    const requiresRestart = deps.supervisor.model?.id === model.id;
+                    if (requiresRestart)
+                        store.pendingReloadModelIds[model.id] = true;
+                    deps.saveProfiles(store);
                     // Return the recomputed budget so an edit costs one round trip rather
                     // than a write followed by a read the UI has to sequence.
                     const gpu = await deps.queryGpuInfo();
-                    const calibration = getCalibration(store, model, profile);
+                    const calibration = profile.calibrationRequired
+                        ? null
+                        : getCalibration(store, model, profile);
                     const options = gpu
                         ? { model, profile, calibration, totalVramBytes: gpu.totalBytes }
                         : null;
                     sendJson(res, {
                         profile,
+                        fields: profileFieldDescriptors(model, profile),
                         adjustments,
                         warnings: profileWarnings(profile, model, store),
                         calibration: calibrationInfo(store, model, profile),
                         budget: options ? vram.budget(options) : null,
                         maxContextThatFits: options ? vram.maxContextThatFits(options) : null,
                         /** True when the running model is the one just edited: a restart applies it. */
-                        requiresRestart: deps.supervisor.model?.id === model.id,
+                        requiresRestart,
+                        hostingProfiles: hostingProfilesFor(store, model),
+                        familyHostingProfileId: familyHostingProfileId(store, model.family),
                     });
                 }
                 catch (error) {
@@ -281,7 +483,7 @@ export function createHostApi(deps) {
                 const options = {
                     model,
                     profile,
-                    calibration: getCalibration(store, model, profile),
+                    calibration: profile.calibrationRequired ? null : getCalibration(store, model, profile),
                     totalVramBytes: gpu.totalBytes,
                 };
                 sendJson(res, {
@@ -352,6 +554,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 +702,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 +719,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 +745,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 +778,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 +816,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 +908,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 +931,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 +983,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 () => {
@@ -714,6 +1006,7 @@ export function createHostApi(deps) {
                         gpu,
                         ranking: deps.getRanking(),
                         supervisor: deps.supervisor,
+                        runtimeBuild: runtimeBuild(deps.supervisor.runtime),
                     }));
                 }
                 catch (error) {

package/dist/service/router.d.ts

@@ -73,6 +73,7 @@ export interface ModelEntry {
     id: string;
     /** Brain's editable human-facing name; `id` remains the stable model key. */
     name: string;
+    family?: string;
     object: "model";
     created: number;
     owned_by: string;
@@ -104,6 +105,23 @@ export declare function describeModel(model: Model | null, options?: DescribeOpt
  * model when no catalog provider is wired in.
  */
 export declare function buildModelList(supervisor: Supervisor, getCatalog: GetCatalog): ModelEntry[];
+/** Which shape a completion path uses to carry its system turn. */
+export type CompletionShape = "anthropic" | "openai";
+export declare function completionShape(url: string | null | undefined): CompletionShape;
+/**
+ * Append the active hosting profile's system-prompt addendum to a buffered
+ * completion body.
+ *
+ * Appending rather than prepending or replacing is the whole point: the agent's
+ * own system prompt still leads, and the profile's instructions are read last.
+ * A body this cannot understand is forwarded untouched - a malformed or
+ * unfamiliar request must still reach llama-server and get llama-server's own
+ * error, not a 400 invented here.
+ *
+ * Cost is one extra parse/serialize per request, paid only by models whose
+ * profile actually sets an addendum.
+ */
+export declare function injectSystemAddendum(body: Buffer, addendum: string | null, shape: CompletionShape): Buffer;
 export type ModelGateResult = {
     ok: true;
     model: Model;