@otto-code/brain 0.8.7 → 0.8.9

package/dist/config/schema.js

@@ -12,6 +12,10 @@ export const ProfileSchema = z
     modelId: z.string().nullable().default(null),
     modelPath: z.string().nullable().default(null),
     mmprojPath: z.string().nullable().default(null),
+    /** Stable bundle component ids enabled for this load. Paths are re-derived. */
+    enabledComponents: z.array(z.string()).default([]),
+    /** Derived component paths for the launcher; never accepted from clients. */
+    componentPaths: z.record(z.string()).default({}),
     contextSize: z.number(),
     cacheTypeK: z.string().default("q8_0"),
     cacheTypeV: z.string().default("q8_0"),
@@ -21,11 +25,54 @@ export const ProfileSchema = z
     reasoningBudget: z.number().default(1536),
     reasoningBudgetMessage: z.string().default(DEFAULT_REASONING_MESSAGE),
     parallelSlots: z.number().default(1),
+    /** RoPE extension factor; 1 keeps the GGUF-native context window. */
+    contextMultiplier: z.number().default(1),
+    /** Cleared only by a successful calibration of this saved model profile. */
+    calibrationRequired: z.boolean().default(true),
     batchSize: z.number().nullable().default(null),
     ubatchSize: z.number().nullable().default(null),
     extraArgs: z.array(z.string()).default([]),
+    /** The selected profile id when `hostingProfileMode` is `custom`. */
+    hostingProfileId: z.string().nullable().default(null),
+    /**
+     * Whether this model inherits its family's profile, disables profiles, or
+     * selects one itself. `inherit` is the default because it is what a profile
+     * stored before this field existed meant: the family default applied to
+     * every model in the family that had not overridden it. Defaulting to `off`
+     * would silently drop that default on every profile written by an older
+     * Brain. With no family default set, `inherit` resolves to nothing, which
+     * is exactly what `off` does, so the safe default costs nothing.
+     */
+    hostingProfileMode: z.enum(["inherit", "off", "custom"]).default("inherit"),
+    /** Derived at load time from the selected Brain-owned hosting profile. */
+    chatTemplateFile: z.string().nullable().default(null),
+    /** Derived at load time; passed directly to llama-server's Jinja engine. */
+    chatTemplateKwargs: z.record(z.unknown()).default({}),
+    /**
+     * Derived at load time from the selected hosting profile's system-prompt
+     * addendum. The router injects it per request rather than the launcher
+     * baking it into a CLI flag; see `hosting-profiles.ts` for why.
+     */
+    chatSystemAddendum: z.string().nullable().default(null),
 })
     .passthrough();
+/**
+ * A named, Brain-owned inference composition. The template is intentionally
+ * text, rather than a user-owned path: remote Brains must be able to apply the
+ * same profile and no client is allowed to make llama-server read arbitrary
+ * files from its host.
+ */
+export const HostingProfileSchema = z
+    .object({
+    id: z.string(),
+    name: z.string(),
+    family: z.string(),
+    description: z.string().default(""),
+    template: z.string().nullable().default(null),
+    systemPromptAddendum: z.string().nullable().default(null),
+    templateKwargs: z.record(z.unknown()).default({}),
+})
+    .strict();
 export const CalibrationSampleSchema = z
     .object({
     contextSize: z.number(),
@@ -63,6 +110,16 @@ export const ProfilesStoreSchema = z
     profiles: z.record(ProfileSchema).default({}),
     calibrations: z.record(z.record(CalibrationSchema)).default({}),
     geometryCalibrations: z.record(GeometryCalibrationSchema).default({}),
+    /** Named reusable profiles, scoped to this Brain rather than any client. */
+    hostingProfiles: z.record(HostingProfileSchema).default({}),
+    /** Optional family default; individual model profiles may override it. */
+    familyHostingProfileIds: z.record(z.string().nullable()).default({}),
+    /**
+     * A saved edit made while that model was resident. It stays visible when
+     * the user leaves and revisits the model settings, and clears only after a
+     * successful fresh llama-server load of that model.
+     */
+    pendingReloadModelIds: z.record(z.boolean()).default({}),
     lastModelId: z.string().nullable().default(null),
 })
     .passthrough();
@@ -162,7 +219,11 @@ export const DEFAULT_BRAIN_CONFIG = BrainConfigSchema.parse({});
 export const CatalogModelSchema = z
     .object({
     id: z.string(),
+    /** Retired Otto-curated ids this canonical catalog entry replaces. */
+    replaces: z.array(z.string()).optional(),
     name: z.string(),
+    /** Stable UI family identity. Otto clients resolve this to a monochrome glyph. */
+    family: z.string().optional(),
     publisher: z.string().optional(),
     hfRepo: z.string(),
     quant: z.string(),
@@ -178,6 +239,24 @@ export const CatalogModelSchema = z
     tier: z.string().optional(),
     why: z.string().optional(),
     status: z.string().optional(),
+    /** Declared only for multi-artifact model bundles. Plain models omit it. */
+    components: z
+        .array(z
+        .object({
+        id: z.string(),
+        label: z.string(),
+        description: z.string(),
+        role: z.enum(["vision_projector", "speculative_drafter"]),
+        hfRepo: z.string().optional(),
+        file: z.string(),
+        bytes: z.number().nullable().optional(),
+        required: z.boolean().default(false),
+        defaultDownload: z.boolean().default(false),
+        defaultLoad: z.boolean().default(false),
+        minRuntimeBuild: z.number().optional(),
+    })
+        .strict())
+        .optional(),
 })
     .passthrough();
 export const CatalogSchema = z

package/dist/config/store.js

@@ -10,6 +10,7 @@ import { writePrivateFileAtomicSync } from "./private-files.js";
 import { packageRoot, resolveBrainPaths } from "./paths.js";
 import { BrainConfigSchema, CatalogSchema, ProfilesStoreSchema, } from "./schema.js";
 import { applyEnvOverrides } from "./env.js";
+import { seedBuiltinHostingProfiles } from "./builtin-hosting-profiles.js";
 function readJson(file, schema) {
     if (!existsSync(file))
         return null;
@@ -26,15 +27,24 @@ function writeJson(file, data) {
 // ------------------------------------------------------------------- profiles
 export function loadProfilesStore(paths = resolveBrainPaths()) {
     const current = readJson(paths.profilesFile, ProfilesStoreSchema);
-    if (current)
+    if (current) {
+        if (seedBuiltinHostingProfiles(current))
+            writeJson(paths.profilesFile, current);
         return current;
+    }
     const legacy = path.join(packageRoot(), "config", "profiles.json");
     const migrated = readJson(legacy, ProfilesStoreSchema);
     if (migrated) {
+        seedBuiltinHostingProfiles(migrated);
         writeJson(paths.profilesFile, migrated);
         return migrated;
     }
-    return ProfilesStoreSchema.parse({});
+    const seeded = ProfilesStoreSchema.parse({});
+    seedBuiltinHostingProfiles(seeded);
+    // A read-only command must not create profiles.json. In-memory seeding keeps
+    // built-ins available; the first real profile save persists the whole store.
+    // This avoids racing a running service that later writes its startup snapshot.
+    return seeded;
 }
 export function saveProfilesStore(store, paths = resolveBrainPaths()) {
     writeJson(paths.profilesFile, store);
@@ -43,23 +53,25 @@ export function saveProfilesStore(store, paths = resolveBrainPaths()) {
 export function loadCatalog(paths = resolveBrainPaths()) {
     const current = readJson(paths.catalogFile, CatalogSchema);
     if (current) {
-        // The catalog is intentionally persisted so local Brain homes survive
-        // package updates, but additive metadata still needs to reach existing
-        // homes. Backfill only fields introduced by the seed catalog; user-owned
-        // catalog values remain authoritative.
+        // Curated entries are Otto-owned product copy. Replace every entry whose
+        // stable download id ships in the seed so catalog corrections reach every
+        // existing Brain home after an upgrade. Keep entries with unknown ids: they
+        // are the only user-owned catalog records and must survive product updates.
+        //
+        // Do not merge field-by-field. A partial merge leaves old names or stale
+        // descriptions behind indefinitely, which is precisely what a catalog
+        // migration is meant to prevent.
         const legacy = readJson(path.join(packageRoot(), "config", "downloads.json"), CatalogSchema);
         if (!legacy)
             return current;
-        const seedById = new Map(legacy.models.map((model) => [model.id, model]));
-        let changed = false;
-        const models = current.models.map((model) => {
-            const seed = seedById.get(model.id);
-            if (model.reasoningEfforts === undefined && seed?.reasoningEfforts !== undefined) {
-                changed = true;
-                return { ...model, reasoningEfforts: seed.reasoningEfforts };
-            }
-            return model;
-        });
+        const seedIds = new Set(legacy.models.map((model) => model.id));
+        // A source repository can change while the underlying curated model stays
+        // the same. Those retired ids are product-owned too: drop them rather than
+        // displaying an obsolete duplicate beside its canonical replacement.
+        const retiredSeedIds = new Set(legacy.models.flatMap((model) => model.replaces ?? []));
+        const userModels = current.models.filter((model) => !seedIds.has(model.id) && !retiredSeedIds.has(model.id));
+        const models = [...legacy.models, ...userModels];
+        const changed = JSON.stringify(models) !== JSON.stringify(current.models);
         if (!changed)
             return current;
         const merged = { ...current, models };

package/dist/gguf.d.ts

@@ -35,6 +35,7 @@ interface GgufSummary {
     tensorCount: number;
     arch: string;
     name: string | null;
+    basename: string | null;
     sizeLabel: string | null;
     fileType: number | null;
     contextLength: number | null;

package/dist/gguf.js

@@ -210,6 +210,7 @@ export function summarize(file) {
         tensorCount,
         arch,
         name: meta["general.name"] || null,
+        basename: meta["general.basename"] || null,
         sizeLabel: meta["general.size_label"] || null,
         fileType: (meta["general.file_type"] ?? null),
         contextLength: (get("context_length") ?? null),

package/dist/models/download.d.ts

@@ -11,6 +11,13 @@ export interface PullOptions {
     token?: string | null;
     onProgress?: (progress: PullProgress) => void;
 }
+/** Exact, manifest-driven files for a bundle selection. No quant discovery is
+ * involved, so a component pull can never select an arbitrary projector. */
+export declare function bundleDownloadPlan(model: CatalogModel, componentIds?: string[], primaryFiles?: string[], primaryBytes?: number): {
+    repo: string;
+    files: string[];
+    totalBytes: number | null;
+};
 /** Download the model file; returns the local path it was written to. */
 export declare function pullModel({ model, destRoot, file, token, onProgress, }: PullOptions): Promise<string>;
 export interface DownloadFilesOptions {

package/dist/models/download.js

@@ -4,7 +4,7 @@
  * `<managedModelsDir>/<publisher>/<repo>/<file>` to mirror the LM Studio layout
  * the scanner already understands.
  */
-import { createWriteStream, existsSync, mkdirSync, rmSync } from "node:fs";
+import { createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import path from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
@@ -35,41 +35,189 @@ function deriveFileFromId(id) {
 function authHeaders(token) {
     return token ? { authorization: `Bearer ${token}` } : {};
 }
+function partialMetadataPath(tmp) {
+    return `${tmp}.json`;
+}
+function clearPartial(tmp) {
+    rmSync(tmp, { force: true });
+    rmSync(partialMetadataPath(tmp), { force: true });
+}
+/** Read only a partial whose source identity and total length were recorded. */
+function resumablePartial(tmp) {
+    try {
+        const bytes = statSync(tmp).size;
+        const metadata = JSON.parse(readFileSync(partialMetadataPath(tmp), "utf8"));
+        if (bytes <= 0 ||
+            !metadata.etag ||
+            !Number.isSafeInteger(metadata.totalBytes) ||
+            metadata.totalBytes <= bytes) {
+            return null;
+        }
+        return { bytes, metadata };
+    }
+    catch {
+        return null;
+    }
+}
+function contentLength(response) {
+    const length = Number(response.headers.get("content-length"));
+    return Number.isSafeInteger(length) && length >= 0 ? length : null;
+}
+function isMatchingRangeResponse(response, partial) {
+    if (response.status !== 206)
+        return false;
+    const match = /^bytes (\d+)-(\d+)\/(\d+)$/.exec(response.headers.get("content-range") ?? "");
+    if (!match)
+        return false;
+    const start = Number(match[1]);
+    const end = Number(match[2]);
+    const totalBytes = Number(match[3]);
+    const length = contentLength(response);
+    const etag = response.headers.get("etag");
+    return (start === partial.bytes &&
+        end >= start &&
+        totalBytes === partial.metadata.totalBytes &&
+        length === end - start + 1 &&
+        (!etag || etag === partial.metadata.etag));
+}
+function writePartialMetadata(tmp, metadata) {
+    writeFileSync(partialMetadataPath(tmp), JSON.stringify(metadata), {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+}
 /**
  * Stream one HF file to `destPath`, reporting bytes received. Skips (returns
- * false) if the file already exists. Writes to a `.part` then renames so a
- * killed download never leaves a truncated file that looks complete.
+ * false) if the file already exists. Interrupted downloads keep a `.part` only
+ * when its ETag and complete length were recorded. A later attempt resumes it
+ * only after Hugging Face confirms the exact byte range belongs to that same
+ * representation; otherwise it restarts cleanly.
  */
 async function streamRepoFile(url, destPath, label, token, onProgress, received) {
     const tmp = `${destPath}.part`;
-    // Remove leftovers from an earlier interrupted attempt before starting a
-    // fresh request, including when this request fails before opening a stream.
-    rmSync(tmp, { force: true });
     mkdirSync(path.dirname(destPath), { recursive: true });
-    if (existsSync(destPath))
+    if (existsSync(destPath)) {
+        clearPartial(tmp);
+        // A bundle plan counts every selected artifact. An artifact that is
+        // already present is complete work, not zero work, otherwise the progress
+        // denominator includes it while the numerator never can.
+        received.bytes += statSync(destPath).size;
+        onProgress?.({ file: label, receivedBytes: received.bytes });
         return false;
-    const response = await fetch(url, { headers: authHeaders(token) });
-    if (!response.ok || !response.body) {
+    }
+    let partial = resumablePartial(tmp);
+    if (!partial && existsSync(tmp))
+        clearPartial(tmp);
+    let response;
+    if (partial) {
+        response = await fetch(url, {
+            headers: {
+                ...authHeaders(token),
+                range: `bytes=${partial.bytes}-`,
+                "if-range": partial.metadata.etag,
+            },
+        });
+        // A 200 is the defined If-Range response when the remote representation
+        // changed (or the server cannot range). The saved bytes are no longer safe
+        // to append, so start over with the complete response it supplied.
+        if (response.status === 200) {
+            clearPartial(tmp);
+            partial = null;
+        }
+        else if (!isMatchingRangeResponse(response, partial)) {
+            // Discard the partial before failing. A persistent non-200/non-206 answer
+            // to the ranged request (an expired signed CDN redirect returning 403, an
+            // upstream 5xx, a proxy that strips Range) would otherwise wedge this file
+            // forever: the partial stays valid, so every later attempt replays the
+            // same ranged request and gets the same answer, and only a 200 ever clears
+            // it. Dropping it here costs the resume but lets the next attempt restart
+            // cleanly from byte zero.
+            clearPartial(tmp);
+            throw new Error(`download resume failed (${response.status}) for ${url}`);
+        }
+    }
+    else {
+        response = await fetch(url, { headers: authHeaders(token) });
+    }
+    if ((response.status !== 200 && response.status !== 206) || !response.body) {
         throw new Error(`download failed (${response.status}) for ${url}`);
     }
-    const totalBytes = Number(response.headers.get("content-length")) || undefined;
+    const append = partial !== null;
+    const resumedBytes = partial?.bytes ?? 0;
+    const totalBytes = partial?.metadata.totalBytes ?? contentLength(response);
+    if (!append) {
+        const etag = response.headers.get("etag");
+        if (etag && totalBytes !== null && totalBytes > 0) {
+            writePartialMetadata(tmp, { etag, totalBytes });
+        }
+        else {
+            // An unidentifiable partial can never be proved safe to resume.
+            clearPartial(tmp);
+        }
+    }
     const body = Readable.fromWeb(response.body);
+    if (append)
+        received.bytes += resumedBytes;
     body.on("data", (chunk) => {
         received.bytes += chunk.length;
-        onProgress?.({ file: label, receivedBytes: received.bytes, totalBytes });
+        onProgress?.({
+            file: label,
+            receivedBytes: received.bytes,
+            totalBytes: totalBytes ?? undefined,
+        });
     });
     try {
-        await pipeline(body, createWriteStream(tmp));
-        const { renameSync } = await import("node:fs");
+        await pipeline(body, createWriteStream(tmp, { flags: append ? "a" : "w" }));
+        // Undici rejects the body stream on a premature close (measured: a short
+        // Content-Length body, with either a destroyed socket or a clean FIN, and a
+        // truncated chunked body all reject), so a cut transfer never reaches this
+        // line. A short but *valid* 206 does: a server may answer an open-ended
+        // `bytes=N-` with any narrower range, and isMatchingRangeResponse accepts
+        // that because it requires end >= start, not end === totalBytes - 1.
+        // Renaming then would publish a truncated model as a complete one. The
+        // partial survives the throw below, so the next attempt resumes from the
+        // bytes this one did add.
+        const writtenBytes = statSync(tmp).size;
+        if (totalBytes !== null && totalBytes > 0 && writtenBytes !== totalBytes) {
+            throw new Error(`download incomplete for ${url}: wrote ${writtenBytes} of ${totalBytes} bytes`);
+        }
         renameSync(tmp, destPath);
+        rmSync(partialMetadataPath(tmp), { force: true });
     }
-    finally {
-        // Cancellation kills the CLI child while the stream is still writing. Do
-        // not leave a truncated `.part` behind for the next quant attempt.
-        rmSync(tmp, { force: true });
+    catch (error) {
+        // Keep only a partial that has a recorded immutable identity and full
+        // length. Everything else is deliberately discarded on the next attempt.
+        if (!resumablePartial(tmp))
+            clearPartial(tmp);
+        throw error;
     }
     return true;
 }
+/** Exact, manifest-driven files for a bundle selection. No quant discovery is
+ * involved, so a component pull can never select an arbitrary projector. */
+export function bundleDownloadPlan(model, componentIds = [], primaryFiles, primaryBytes) {
+    const selected = new Set(componentIds);
+    const known = new Set((model.components ?? []).map((component) => component.id));
+    const unknown = componentIds.filter((id) => !known.has(id));
+    if (unknown.length)
+        throw new Error(`unknown bundle components: ${unknown.join(", ")}`);
+    const components = (model.components ?? []).filter((component) => component.required || selected.has(component.id));
+    const foreign = components.find((component) => (component.hfRepo ?? model.hfRepo) !== model.hfRepo);
+    if (foreign)
+        throw new Error(`component ${foreign.id} uses a separate repository and needs its own plan`);
+    return {
+        repo: model.hfRepo,
+        files: [
+            ...(primaryFiles ?? [resolveFileName(model)]),
+            ...components.map((component) => component.file),
+        ],
+        totalBytes: (primaryBytes ?? model.approxWeightsBytes) === undefined ||
+            components.some((component) => component.bytes == null)
+            ? null
+            : (primaryBytes ?? model.approxWeightsBytes) +
+                components.reduce((sum, component) => sum + (component.bytes ?? 0), 0),
+    };
+}
 /** Download the model file; returns the local path it was written to. */
 export async function pullModel({ model, destRoot, file, token, onProgress, }) {
     const fileName = resolveFileName(model, file);

package/dist/models/enrich.d.ts

@@ -1,24 +1,11 @@
-/**
- * Reconciles scanned models back to their download-catalog entries so a model's
- * coding metadata (useCases, tier, thinking, contextMax) survives a `pull`. The
- * catalog carries this per entry, but once files land on disk scan.ts rebuilds a
- * Model from filename + GGUF header alone, dropping it - this is where it is
- * re-attached. Track B1 of the brain coding-capabilities work.
- *
- * The join key is the hfRepo path. download.ts writes each model to
- * `<modelsDir>/<hfRepo>/<file>.gguf` (LM Studio mirrors the same
- * `<publisher>/<repo>/<file>` layout), and scan.ts rebuilds `Model.id` as that
- * same modelsDir-relative path with forward slashes. So a scanned model's id
- * sits under its catalog entry's hfRepo directory, and that containment is the
- * match.
- *
- * Total and best-effort by design: an empty catalog, a model with no match, or a
- * repo carrying several quants all resolve without throwing. Discovery returns
- * things unenriched on absence rather than raising - the caller decides whether
- * absence matters.
- */
 import type { Catalog, CatalogModel } from "../config/schema.js";
 import type { Model } from "../types.js";
+/**
+ * Normalize a GGUF identity into the catalog's hosting-profile vocabulary.
+ * Architecture is a stable structural field; names are only fallbacks for
+ * headers whose architecture is absent or unrecognised.
+ */
+export declare function familyFromGgufMetadata(model: Model): string | undefined;
 /**
  * Find the catalog entry a scanned model belongs to, or null. A model matches
  * when its id path sits directly under the entry's hfRepo directory. When a repo

package/dist/models/enrich.js

@@ -1,3 +1,68 @@
+/**
+ * Reconciles scanned models back to their download-catalog entries so a model's
+ * coding metadata (useCases, tier, thinking, contextMax) survives a `pull`. The
+ * catalog carries this per entry, but once files land on disk scan.ts rebuilds a
+ * Model from filename + GGUF header alone, dropping it - this is where it is
+ * re-attached. Track B1 of the brain coding-capabilities work.
+ *
+ * The join key is the hfRepo path. download.ts writes each model to
+ * `<modelsDir>/<hfRepo>/<file>.gguf` (LM Studio mirrors the same
+ * `<publisher>/<repo>/<file>` layout), and scan.ts rebuilds `Model.id` as that
+ * same modelsDir-relative path with forward slashes. So a scanned model's id
+ * sits under its catalog entry's hfRepo directory, and that containment is the
+ * match.
+ *
+ * Total and best-effort by design: an empty catalog, a model with no match, or a
+ * repo carrying several quants all resolve without throwing. Discovery returns
+ * things unenriched on absence rather than raising - the caller decides whether
+ * absence matters.
+ */
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Hosting-profile families deliberately use a small, curated vocabulary. It is
+ * a mix of publisher and model-line identities, so GGUF architecture names
+ * must be folded into the existing buckets rather than exposed directly.
+ */
+const FAMILY_BY_GGUF_IDENTIFIER = {
+    chatglm: "chatglm",
+    deepseek: "deepseek",
+    gemma: "gemma",
+    gptoss: "openai",
+    llama: "meta",
+    meta: "meta",
+    microsoft: "microsoft",
+    mistral: "mistral",
+    mixtral: "mistral",
+    nemotron: "nvidia",
+    nvidia: "nvidia",
+    openai: "openai",
+    phi: "microsoft",
+    qwen: "qwen",
+};
+/**
+ * Normalize a GGUF identity into the catalog's hosting-profile vocabulary.
+ * Architecture is a stable structural field; names are only fallbacks for
+ * headers whose architecture is absent or unrecognised.
+ */
+export function familyFromGgufMetadata(model) {
+    const metadata = model.metadata;
+    if (!metadata)
+        return undefined;
+    for (const value of [metadata.arch, metadata.basename, metadata.name]) {
+        if (typeof value !== "string")
+            continue;
+        const identifier = value
+            .trim()
+            .toLowerCase()
+            .replace(/[^a-z0-9]/gu, "");
+        for (const [prefix, family] of Object.entries(FAMILY_BY_GGUF_IDENTIFIER)) {
+            if (identifier.startsWith(prefix))
+                return family;
+        }
+    }
+    return undefined;
+}
 /** Normalize a repo/id path: forward slashes, lowercased, trailing slashes trimmed. */
 function normalizePath(value) {
     const normalized = value.replaceAll("\\", "/");
@@ -53,16 +118,25 @@ export function matchCatalogEntry(model, catalog) {
  * through untouched. Never throws.
  */
 export function enrichWithCatalog(models, catalog) {
-    if (catalog.models.length === 0)
-        return models;
     return models.map((model) => {
         const entry = matchCatalogEntry(model, catalog);
-        if (!entry)
-            return model;
+        if (!entry) {
+            const enriched = enrichDiscoveredProjector(model);
+            const family = familyFromGgufMetadata(enriched);
+            return family ? { ...enriched, family } : enriched;
+        }
+        const components = resolveComponents(model, entry);
+        const projector = components?.find((component) => component.role === "vision_projector");
         return {
             ...model,
             catalogId: entry.id,
             catalogHfRepo: entry.hfRepo,
+            family: entry.family,
+            components,
+            // A manifest is authoritative. Do not pair a random same-directory
+            // projector when the catalog declares the exact companion artifact.
+            mmprojPath: projector?.path ?? (components ? null : model.mmprojPath),
+            mmprojBytes: projector?.bytes ?? (components ? 0 : model.mmprojBytes),
             useCases: entry.useCases,
             tier: entry.tier,
             thinking: entry.thinking,
@@ -71,4 +145,64 @@ export function enrichWithCatalog(models, catalog) {
         };
     });
 }
+/** Promote a scanner-paired projector in an arbitrary Hugging Face repository
+ * into the same component inventory shape used by curated bundles. */
+function enrichDiscoveredProjector(model) {
+    if (!model.mmprojPath)
+        return model;
+    return {
+        ...model,
+        components: [
+            {
+                id: "vision-projector",
+                label: "Vision projector",
+                description: "Adds image understanding",
+                role: "vision_projector",
+                path: model.mmprojPath,
+                bytes: model.mmprojBytes,
+                required: false,
+                defaultDownload: false,
+                defaultLoad: true,
+                available: true,
+            },
+        ],
+    };
+}
+function resolveComponents(model, entry) {
+    if (!entry.components)
+        return undefined;
+    const modelDir = path.dirname(model.modelPath);
+    return entry.components.map((component) => {
+        const componentRepo = component.hfRepo ?? entry.hfRepo;
+        // A selected catalog primary and its declared companions share a repo in the
+        // managed layout. For a companion repository, derive its absolute path from
+        // the scanned model's models root rather than accepting a client path.
+        const repoTail = componentRepo.split("/").join(path.sep);
+        const marker = entry.hfRepo.split("/").join(path.sep);
+        const root = modelDir.endsWith(marker) ? modelDir.slice(0, -marker.length) : modelDir;
+        const candidate = path.resolve(root, repoTail, component.file);
+        let bytes = 0;
+        try {
+            bytes = fs.statSync(candidate).size;
+        }
+        catch {
+            bytes = component.bytes ?? 0;
+        }
+        const available = fs.existsSync(candidate);
+        return {
+            id: component.id,
+            label: component.label,
+            description: component.description,
+            role: component.role,
+            path: available ? candidate : null,
+            bytes,
+            required: component.required,
+            defaultDownload: component.defaultDownload,
+            defaultLoad: component.defaultLoad,
+            available,
+            ...(available ? {} : { unavailableReason: "Not downloaded" }),
+            ...(component.minRuntimeBuild ? { minRuntimeBuild: component.minRuntimeBuild } : {}),
+        };
+    });
+}
 //# sourceMappingURL=enrich.js.map

package/dist/models/hf.d.ts

@@ -38,15 +38,28 @@ export interface ModelSearchResult {
     likes: number;
     updatedAt: string | null;
     gated: boolean;
+    summary: string | null;
 }
+/** Drop every cached summary. Exported for tests and for a token change, which
+ * can flip which repos are readable at all. */
+export declare function clearCardSummaryCache(): void;
 /**
  * Search Hugging Face for GGUF model repos, most-downloaded first. Returns a
  * normalized shape both the TUI and the Otto app can render; drill into a result
  * with {@link listRepoQuants} to see and download its quantizations.
+ *
+ * Card summaries are a *bounded* enrichment, never a gate on the result set. Each
+ * one costs one or two extra round trips, so the whole batch shares one budget
+ * (`summaryBudgetMs`, 0 to skip them entirely); rows that miss it come back with
+ * `summary: null`, which every consumer already treats as "not available". When
+ * the budget expires the outstanding fetches are aborted rather than left to run,
+ * so the one-shot `otto brain search --json` the daemon shells out to can exit
+ * immediately instead of lingering on open sockets.
  */
-export declare function searchModels(query: string, { limit, token }?: {
+export declare function searchModels(query: string, { limit, token, summaryBudgetMs, }?: {
     limit?: number;
     token?: string | null;
+    summaryBudgetMs?: number;
 }): Promise<ModelSearchResult[]>;
 /**
  * Quality order for display: higher bits-per-weight is more faithful and larger.