@otto-code/brain 0.8.6 → 0.8.8

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"),
@@ -162,6 +166,8 @@ 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(),
     publisher: z.string().optional(),
     hfRepo: z.string(),
@@ -178,6 +184,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

@@ -43,23 +43,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/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,184 @@ 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);
         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,22 +1,3 @@
-/**
- * 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";
 /**

package/dist/models/enrich.js

@@ -1,6 +1,32 @@
+/**
+ * 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";
 /** Normalize a repo/id path: forward slashes, lowercased, trailing slashes trimmed. */
 function normalizePath(value) {
-    return value.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+    const normalized = value.replaceAll("\\", "/");
+    let end = normalized.length;
+    while (end > 0 && normalized.charCodeAt(end - 1) === 47) {
+        end -= 1;
+    }
+    return normalized.slice(0, end).toLowerCase();
 }
 /** The final path segment (file name) of a scanned model's id. */
 function basenameOf(id) {
@@ -48,16 +74,21 @@ 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;
+            return enrichDiscoveredProjector(model);
+        const components = resolveComponents(model, entry);
+        const projector = components?.find((component) => component.role === "vision_projector");
         return {
             ...model,
             catalogId: entry.id,
             catalogHfRepo: entry.hfRepo,
+            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,
@@ -66,4 +97,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.