@otto-code/brain 0.8.7 → 0.8.9

package/dist/models/hf.js

@@ -22,12 +22,229 @@ function authHeaders(token) {
 function entryBytes(entry) {
     return entry.size ?? entry.lfs?.size ?? 0;
 }
+/**
+ * Model-card summaries, and the three traps they set.
+ *
+ * 1. **`base_model` chains can be circular.** A quantizer's card names its base,
+ *    whose card can name the quantization straight back. Two guards, because one
+ *    is not enough: the chain of repos being resolved is carried down the
+ *    recursion and re-entering a repo already on it is refused, and the chain is
+ *    depth-capped. A guard on direct self-reference alone misses A -> B -> A.
+ * 2. **A shared cache of *pending* promises reintroduces the deadlock the chain
+ *    guard just removed.** With three rows resolving concurrently, A -> B -> C -> A
+ *    can have each stack awaiting another stack's in-flight entry, a wait-for
+ *    cycle no per-stack chain can observe. So the cache holds *settled values
+ *    only*, and the in-flight dedupe map is consulted **only at the top level**,
+ *    never inside the recursion. Every in-flight promise therefore resolves
+ *    without ever awaiting another in-flight promise, which makes the wait-for
+ *    graph a forest and a cycle unrepresentable.
+ * 3. **The service is long lived.** The cache is capped and LRU-evicted, and
+ *    entries expire, with a much shorter life for misses so a transient failure
+ *    does not stick for the process lifetime.
+ *
+ * Every fetch also carries a timeout, and the caller's abort signal, so a slow or
+ * hanging remote cannot pin an RPC open.
+ */
+const SUMMARY_CACHE_MAX = 256;
+const SUMMARY_TTL_MS = 30 * 60000;
+/** Misses expire fast: a 404 today is often a card published tomorrow. */
+const SUMMARY_MISS_TTL_MS = 5 * 60000;
+const SUMMARY_FETCH_TIMEOUT_MS = 4000;
+/** Deadline for the search and tree listings, which carry the actual payload. */
+const REQUEST_TIMEOUT_MS = 15000;
+/** How long a whole search may spend on summaries before degrading to null. */
+const DEFAULT_SUMMARY_BUDGET_MS = 2500;
+/** Repos one `base_model` branch may visit before giving up on finding prose. */
+const MAX_BASE_MODEL_DEPTH = 3;
+const cardSummaryCache = new Map();
+const inFlightSummaries = new Map();
+/** A live cache entry, or null when absent or expired. Refreshes LRU recency. */
+function readCachedSummary(key) {
+    const hit = cardSummaryCache.get(key);
+    if (!hit)
+        return null;
+    if (hit.expiresAt <= Date.now()) {
+        cardSummaryCache.delete(key);
+        return null;
+    }
+    // Re-insert so the most recently read key is the youngest in iteration order.
+    cardSummaryCache.delete(key);
+    cardSummaryCache.set(key, hit);
+    return hit;
+}
+function writeCachedSummary(key, value) {
+    cardSummaryCache.delete(key);
+    cardSummaryCache.set(key, {
+        value,
+        expiresAt: Date.now() + (value === null ? SUMMARY_MISS_TTL_MS : SUMMARY_TTL_MS),
+    });
+    // Map iterates in insertion order, so the first key is the least recently used.
+    while (cardSummaryCache.size > SUMMARY_CACHE_MAX) {
+        const oldest = cardSummaryCache.keys().next();
+        if (oldest.done)
+            break;
+        cardSummaryCache.delete(oldest.value);
+    }
+}
+/** Drop every cached summary. Exported for tests and for a token change, which
+ * can flip which repos are readable at all. */
+export function clearCardSummaryCache() {
+    cardSummaryCache.clear();
+    inFlightSummaries.clear();
+}
+function cleanCardSummary(markdown) {
+    const body = markdown.replace(/^---\s*[\s\S]*?---\s*/u, "");
+    const paragraphs = body
+        .split(/\r?\n\s*\r?\n/u)
+        .map((paragraph) => paragraph
+        .replace(/<[^>]+>/gu, " ")
+        .replace(/!?(\[[^\]]*\]\([^)]*\))/gu, "$1")
+        .replace(/[>*#`_]/gu, " ")
+        .replace(/\s+/gu, " ")
+        .trim())
+        .filter((paragraph) => paragraph.length >= 80);
+    const useful = paragraphs.find((paragraph) => !/^(community model|special thanks|disclaimers|model creator|gguf quantization)/iu.test(paragraph) &&
+        !/lm studio community models highlights program|lm studio is not the creator/iu.test(paragraph));
+    if (!useful)
+        return null;
+    const sentences = useful.match(/[^.!?]+[.!?]+(?:\s|$)/gu) ?? [useful];
+    const summary = sentences.slice(0, 2).join(" ").trim();
+    return summary.length >= 80 ? summary.slice(0, 360).trim() : null;
+}
+/**
+ * A request the caller cannot proceed without, so a failure throws rather than
+ * reporting absence. It is still bounded: without a deadline a remote that
+ * accepts the connection and then goes quiet pins the RPC that awaits it open
+ * for as long as the socket lives, which is the whole reason the summary
+ * fetches carry one too.
+ */
+async function fetchHf(url, token, what) {
+    try {
+        return await fetch(url, {
+            headers: authHeaders(token),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (cause) {
+        const timedOut = cause instanceof Error && cause.name === "TimeoutError";
+        throw new Error(timedOut
+            ? `Hugging Face ${what} timed out after ${REQUEST_TIMEOUT_MS}ms`
+            : `Hugging Face ${what} could not reach the server`, { cause });
+    }
+}
+/**
+ * One card fetch, bounded by its own timeout and by the caller's abort. Returns
+ * null on any failure: discovery reports absence rather than throwing, and a
+ * missing card is the overwhelmingly common case (most GGUF repos have none).
+ */
+async function fetchCard(url, token, signal) {
+    const timeout = AbortSignal.timeout(SUMMARY_FETCH_TIMEOUT_MS);
+    try {
+        return await fetch(url, {
+            headers: authHeaders(token),
+            signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve one repo's summary, following `base_model` when the repo has no card
+ * prose of its own. `chain` is every repo already being resolved on this branch,
+ * lowercased; it is both the cycle guard and the depth counter. Never consults
+ * the in-flight map (see the header note): the recursion only ever reads settled
+ * cache entries, so it cannot wait on another row's unfinished work.
+ */
+async function resolveCardSummary(repo, token, chain, signal) {
+    const key = repo.toLowerCase();
+    const cached = readCachedSummary(key);
+    if (cached)
+        return cached.value;
+    const readme = await fetchCard(`${HF_BASE}/${repo}/raw/main/README.md`, token, signal);
+    let summary = null;
+    if (readme?.ok) {
+        summary = cleanCardSummary(await readme.text().catch(() => ""));
+    }
+    // Only a depth cut makes the answer chain-specific: this repo might still
+    // have resolved from a shallower entry point, so that null must not be cached.
+    let truncated = false;
+    // Once the caller has given up, do not spend a second round trip chasing the
+    // base model: the answer can no longer be used.
+    if (summary === null && !signal?.aborted) {
+        if (chain.length >= MAX_BASE_MODEL_DEPTH) {
+            truncated = true;
+        }
+        else {
+            // The repo names no prose of its own, so try the model it was quantized
+            // from. The `${HF_BASE}/` prefix is committed before the interpolation, so
+            // a hostile base_model cannot redirect this off huggingface.co and leak
+            // the token; keep that ordering if you touch these URLs.
+            const detail = await fetchCard(`${HF_BASE}/api/models/${repo}`, token, signal);
+            if (detail?.ok) {
+                const card = (await detail.json().catch(() => null));
+                const declared = card?.cardData?.base_model;
+                const baseModel = Array.isArray(declared) ? declared[0] : declared;
+                // Refusing a repo already on this branch is what breaks A -> B -> A.
+                // Caching the null is still correct here: a cycle carries no prose at
+                // any entry point, so every member resolves to null however it is
+                // reached.
+                const baseKey = baseModel?.toLowerCase();
+                if (baseModel && baseKey && !chain.includes(baseKey)) {
+                    summary = await resolveCardSummary(baseModel, token, [...chain, baseKey], signal);
+                }
+            }
+        }
+    }
+    // An aborted branch resolved nothing because we stopped asking, not because
+    // the repo has no card. Caching that would let one slow search poison the next.
+    if (!truncated && !signal?.aborted)
+        writeCachedSummary(key, summary);
+    return summary;
+}
+/**
+ * Top-level entry: the only place the in-flight map is read, so duplicate repos
+ * in one result set share a fetch without ever forming a wait-for cycle.
+ */
+function modelCardSummary(repo, token, signal) {
+    const key = repo.toLowerCase();
+    const cached = readCachedSummary(key);
+    if (cached)
+        return Promise.resolve(cached.value);
+    const existing = inFlightSummaries.get(key);
+    if (existing)
+        return existing;
+    const pending = resolveCardSummary(repo, token, [key], signal)
+        .catch(() => null)
+        .finally(() => {
+        inFlightSummaries.delete(key);
+    });
+    inFlightSummaries.set(key, pending);
+    return pending;
+}
+async function mapWithConcurrency(values, limit, mapper) {
+    let cursor = 0;
+    await Promise.all(Array.from({ length: Math.min(limit, values.length) }, async () => {
+        while (cursor < values.length) {
+            const index = cursor++;
+            await mapper(values[index], index);
+        }
+    }));
+}
 /**
  * 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 async function searchModels(query, { limit = 25, token = null } = {}) {
+export async function searchModels(query, { limit = 25, token = null, summaryBudgetMs = DEFAULT_SUMMARY_BUDGET_MS, } = {}) {
     const params = new URLSearchParams({
         search: query,
         filter: "gguf",
@@ -35,14 +252,12 @@ export async function searchModels(query, { limit = 25, token = null } = {}) {
         direction: "-1",
         limit: String(limit),
     });
-    const res = await fetch(`${HF_BASE}/api/models?${params.toString()}`, {
-        headers: authHeaders(token),
-    });
+    const res = await fetchHf(`${HF_BASE}/api/models?${params.toString()}`, token, "search");
     if (!res.ok) {
         throw new Error(`Hugging Face search failed (${res.status}) for "${query}"`);
     }
     const entries = (await res.json());
-    return entries.map((entry) => ({
+    const rows = entries.map((entry) => ({
         repo: entry.id,
         author: entry.author ?? entry.id.split("/")[0] ?? "",
         downloads: entry.downloads ?? 0,
@@ -50,6 +265,24 @@ export async function searchModels(query, { limit = 25, token = null } = {}) {
         updatedAt: entry.lastModified ?? null,
         gated: Boolean(entry.gated),
     }));
+    const summaries = rows.map(() => null);
+    if (summaryBudgetMs > 0 && rows.length > 0) {
+        const controller = new AbortController();
+        const gather = mapWithConcurrency(rows, 4, async (row, index) => {
+            summaries[index] = await modelCardSummary(row.repo, token, controller.signal);
+        }).catch(() => undefined);
+        let expire;
+        const deadline = new Promise((resolve) => {
+            expire = setTimeout(resolve, summaryBudgetMs);
+            // Never let the budget timer itself be the reason a CLI run stays alive.
+            expire.unref?.();
+        });
+        await Promise.race([gather, deadline]);
+        if (expire)
+            clearTimeout(expire);
+        controller.abort();
+    }
+    return rows.map((row, index) => ({ ...row, summary: summaries[index] ?? null }));
 }
 /**
  * Quality order for display: higher bits-per-weight is more faithful and larger.
@@ -77,7 +310,7 @@ export function quantRank(quant) {
  */
 export async function listRepoQuants(repo, token = null) {
     const url = `${HF_BASE}/api/models/${repo}/tree/main?recursive=true`;
-    const res = await fetch(url, { headers: authHeaders(token) });
+    const res = await fetchHf(url, token, `listing for ${repo}`);
     if (!res.ok) {
         throw new Error(`Hugging Face listing failed (${res.status}) for ${repo}`);
     }

package/dist/models/index.d.ts

@@ -3,9 +3,9 @@ import type { Model } from "../types.js";
 export * from "./scan.js";
 export { pickModel, pickAutoModel } from "./pick.js";
 export { resolveModelsDirs, managedModelsDir, type ModelsDir } from "./dirs.js";
-export { pullModel, downloadRepoFiles, type PullOptions, type PullProgress, type DownloadFilesOptions, } from "./download.js";
+export { pullModel, bundleDownloadPlan, downloadRepoFiles, type PullOptions, type PullProgress, type DownloadFilesOptions, } from "./download.js";
 export { matchCatalogEntry, enrichWithCatalog } from "./enrich.js";
-export { resolveHfToken, listRepoQuants, searchModels, repoOfModel, quantRank, type QuantOption, type RepoQuants, type ModelSearchResult, } from "./hf.js";
+export { resolveHfToken, listRepoQuants, searchModels, clearCardSummaryCache, repoOfModel, quantRank, type QuantOption, type RepoQuants, type ModelSearchResult, } from "./hf.js";
 export { diskUsage, totalModelBytes, planDelete, deleteModelFiles, type DiskUsage, type DeletePlan, } from "./manage.js";
 export interface ScanModelsOptions {
     withMetadata?: boolean;

package/dist/models/index.js

@@ -9,14 +9,17 @@ import { scan } from "./scan.js";
 export * from "./scan.js";
 export { pickModel, pickAutoModel } from "./pick.js";
 export { resolveModelsDirs, managedModelsDir } from "./dirs.js";
-export { pullModel, downloadRepoFiles, } from "./download.js";
+export { pullModel, bundleDownloadPlan, downloadRepoFiles, } from "./download.js";
 export { matchCatalogEntry, enrichWithCatalog } from "./enrich.js";
-export { resolveHfToken, listRepoQuants, searchModels, repoOfModel, quantRank, } from "./hf.js";
+export { resolveHfToken, listRepoQuants, searchModels, clearCardSummaryCache, repoOfModel, quantRank, } from "./hf.js";
 export { diskUsage, totalModelBytes, planDelete, deleteModelFiles, } from "./manage.js";
 /** Scan every configured models directory (managed ∪ LM Studio), de-duplicated. */
 export function scanModels(config, env = process.env, options = {}) {
     const dirs = resolveModelsDirs(config, env);
-    const seen = new Set();
+    // `Model.id` is the stable repo-relative artifact identity. The same file
+    // can exist in the managed store and LM Studio's store at different absolute
+    // paths; managed is scanned first and deliberately owns that collision.
+    const seenIds = new Set();
     const all = [];
     for (const { dir, origin } of dirs) {
         for (const model of scan({
@@ -24,9 +27,9 @@ export function scanModels(config, env = process.env, options = {}) {
             withMetadata: options.withMetadata ?? true,
             origin,
         })) {
-            if (seen.has(model.modelPath))
+            if (seenIds.has(model.id))
                 continue;
-            seen.add(model.modelPath);
+            seenIds.add(model.id);
             all.push(model);
         }
     }

package/dist/models/manage.d.ts

@@ -15,6 +15,7 @@ export interface DeletePlan {
     files: string[];
     bytes: number;
     includesProjector: boolean;
+    componentIds: string[];
 }
 /**
  * Work out exactly which files deleting a model removes: its GGUF (all shards),
@@ -24,4 +25,7 @@ export interface DeletePlan {
 export declare function planDelete(model: Model): DeletePlan;
 /** Delete the files a {@link planDelete} chose, plus a now-empty repo directory. */
 export declare function deleteModelFiles(model: Model): DeletePlan;
+/** Remove one optional bundle artifact. The primary model is never accepted,
+ * and a loaded profile may not lose a component underneath llama.cpp. */
+export declare function deleteComponentFile(model: Model, componentId: string): DeletePlan;
 //# sourceMappingURL=manage.d.ts.map

package/dist/models/manage.js

@@ -66,7 +66,7 @@ export function planDelete(model) {
     // The projector is shared across the repo's quants; only remove it if this was
     // the last model GGUF in the directory.
     let includesProjector = false;
-    if (model.mmprojPath) {
+    if (model.mmprojPath || model.components?.length) {
         const dir = path.dirname(model.modelPath);
         const doomed = new Set(files.map((f) => path.resolve(f)));
         let othersRemain = false;
@@ -86,11 +86,24 @@ export function planDelete(model) {
             othersRemain = true; // be conservative: keep the projector if unsure
         }
         if (!othersRemain) {
-            add(model.mmprojPath);
-            includesProjector = true;
+            if (model.mmprojPath) {
+                add(model.mmprojPath);
+                includesProjector = true;
+            }
+            for (const component of model.components ?? []) {
+                if (component.path && !files.includes(component.path))
+                    add(component.path);
+            }
         }
     }
-    return { files, bytes, includesProjector };
+    return {
+        files,
+        bytes,
+        includesProjector,
+        componentIds: (model.components ?? [])
+            .filter((component) => component.path && files.includes(component.path))
+            .map((component) => component.id),
+    };
 }
 /** Delete the files a {@link planDelete} chose, plus a now-empty repo directory. */
 export function deleteModelFiles(model) {
@@ -109,4 +122,21 @@ export function deleteModelFiles(model) {
     }
     return plan;
 }
+/** Remove one optional bundle artifact. The primary model is never accepted,
+ * and a loaded profile may not lose a component underneath llama.cpp. */
+export function deleteComponentFile(model, componentId) {
+    const component = model.components?.find((candidate) => candidate.id === componentId);
+    if (!component || !component.path)
+        throw new Error(`component "${componentId}" is not installed`);
+    if (component.required)
+        throw new Error("required bundle components cannot be removed separately");
+    const bytes = fs.statSync(component.path).size;
+    fs.rmSync(component.path, { force: true });
+    return {
+        files: [component.path],
+        bytes,
+        includesProjector: component.role === "vision_projector",
+        componentIds: [component.id],
+    };
+}
 //# sourceMappingURL=manage.js.map

package/dist/models/scan.js

@@ -9,42 +9,11 @@ import os from "node:os";
 import path from "node:path";
 import * as gguf from "../gguf.js";
 export const LMSTUDIO_MODELS_DIR = path.join(os.homedir(), ".lmstudio", "models");
-// Quantisation labels as they appear in filenames, longest first so that
-// Q4_K_M wins over Q4_K.
-const QUANT_PATTERNS = [
-    "IQ1_S",
-    "IQ1_M",
-    "IQ2_XXS",
-    "IQ2_XS",
-    "IQ2_S",
-    "IQ2_M",
-    "IQ3_XXS",
-    "IQ3_XS",
-    "IQ3_S",
-    "IQ3_M",
-    "IQ4_XS",
-    "IQ4_NL",
-    "Q2_K_S",
-    "Q2_K",
-    "Q3_K_S",
-    "Q3_K_M",
-    "Q3_K_L",
-    "Q4_K_S",
-    "Q4_K_M",
-    "Q5_K_S",
-    "Q5_K_M",
-    "Q6_K",
-    "Q8_0",
-    "Q4_0",
-    "Q4_1",
-    "Q5_0",
-    "Q5_1",
-    "NVFP4",
-    "MXFP4",
-    "BF16",
-    "F16",
-    "F32",
-];
+// The quant is the terminal GGUF filename suffix, optionally preceded by a
+// source-defined qualifier such as Muse's `UD-`. Matching a known substring
+// truncates newer labels (for example Q2_K_XL -> Q2_K) and misses them when
+// their exact spelling is not in a hard-coded list.
+const QUANT_SUFFIX = /(?:^|[-_])((?:UD-)?(?:IQ[1-4]|Q[2-8])(?:_[A-Z0-9]+)*|NVFP\d+|MXFP\d+|BF16|F16|F32)(?:-(?:MTP|IMATRIX|DISTILL))?(?:-\d{5}-OF-\d{5})?\.GGUF$/i;
 const MULTIPART = /-(\d{5})-of-(\d{5})\.gguf$/i;
 function walk(dir, out = []) {
     let entries;
@@ -64,12 +33,9 @@ function walk(dir, out = []) {
     return out;
 }
 export function detectQuant(filename) {
-    const upper = filename.toUpperCase();
-    for (const pattern of QUANT_PATTERNS) {
-        if (upper.includes(pattern))
-            return pattern;
-    }
-    return null;
+    const match = path.basename(filename).match(QUANT_SUFFIX);
+    // `UD-` is a source filename qualifier, not part of the user-facing quant.
+    return match?.[1]?.replace(/^UD-/i, "").toUpperCase() ?? null;
 }
 export function isProjectorFile(filename) {
     return /^mmproj/i.test(path.basename(filename));

package/dist/ops/calibrate.d.ts

@@ -1,3 +1,4 @@
+import { Supervisor } from "../service/supervisor.js";
 import type { Model, Runtime } from "../types.js";
 import type { Profile } from "../config/schema.js";
 /**
@@ -31,6 +32,8 @@ export interface CalibrateOptions {
     profile: Profile;
     samples?: number[];
     internalPort?: number;
+    /** Reuse the host's resident supervisor instead of creating a sidecar server. */
+    supervisor?: Supervisor;
     onProgress?: (event: CalibrateProgress) => void;
 }
 /** The measured KV-cache profile calibration produces. */
@@ -45,5 +48,5 @@ export interface CalibrationMeasurement {
     vision: boolean;
     measuredAt: string;
 }
-export declare function calibrate({ runtime, model, profile, samples, internalPort, onProgress, }: CalibrateOptions): Promise<CalibrationMeasurement>;
+export declare function calibrate({ runtime, model, profile, samples, internalPort, supervisor: optionsSupervisor, onProgress, }: CalibrateOptions): Promise<CalibrationMeasurement>;
 //# sourceMappingURL=calibrate.d.ts.map

package/dist/ops/calibrate.js

@@ -12,21 +12,24 @@ import { DEFAULT_INTERNAL_PORT, Supervisor } from "../service/supervisor.js";
  * buffers) cancels out of the difference.
  */
 export const DEFAULT_SAMPLES = [8192, 65536];
-export async function calibrate({ runtime, model, profile, samples = DEFAULT_SAMPLES, internalPort = DEFAULT_INTERNAL_PORT + 1, onProgress = () => { }, }) {
-    if (samples.length < 2)
+export async function calibrate({ runtime, model, profile, samples, internalPort = DEFAULT_INTERNAL_PORT + 1, supervisor: optionsSupervisor, onProgress = () => { }, }) {
+    const nativeContext = model.metadata?.contextLength ?? null;
+    const effectiveSamples = samples ??
+        (nativeContext ? [8192, nativeContext * profile.contextMultiplier] : DEFAULT_SAMPLES);
+    if (effectiveSamples.length < 2)
         throw new Error("calibration needs at least two context sizes");
-    const native = model.metadata?.contextLength || Math.max(...samples);
+    const native = (nativeContext || Math.max(...effectiveSamples)) * profile.contextMultiplier;
     const points = [];
-    for (const contextSize of samples) {
+    for (const contextSize of effectiveSamples) {
         if (contextSize > native) {
-            onProgress({ phase: "skip", contextSize, reason: `exceeds native context ${native}` });
+            onProgress({ phase: "skip", contextSize, reason: `exceeds configured context ${native}` });
             continue;
         }
-        const supervisor = new Supervisor({ runtime, internalPort });
+        const supervisor = optionsSupervisor ?? new Supervisor({ runtime, internalPort });
         onProgress({ phase: "loading", contextSize });
         const baseline = await usedBytes();
         try {
-            await supervisor.start(model, { ...profile, contextSize });
+            await supervisor.start(model, { ...profile, contextSize }, { preserveLogs: Boolean(optionsSupervisor) });
             const used = supervisor.vramAtReadyBytes ?? (await usedBytes());
             const delta = Number(used) - Number(supervisor.vramBaselineBytes ?? baseline);
             points.push({ contextSize, deltaBytes: delta, loadSeconds: supervisor.loadSeconds });

package/dist/ops/sweep.d.ts

@@ -70,8 +70,10 @@ export interface SweepOptions {
     maxTokens?: number;
     temperature?: number;
     internalPort?: number;
+    /** Reuse the host's resident supervisor instead of creating a sidecar server. */
+    supervisor?: Supervisor;
     onProgress?: (event: SweepProgress) => void;
 }
-export declare function sweep({ runtime, model, profile, budgets, maxTokens, temperature, internalPort, onProgress, }: SweepOptions): Promise<SweepReport>;
+export declare function sweep({ runtime, model, profile, budgets, maxTokens, temperature, internalPort, supervisor: optionsSupervisor, onProgress, }: SweepOptions): Promise<SweepReport>;
 export {};
 //# sourceMappingURL=sweep.d.ts.map

package/dist/ops/sweep.js

@@ -81,13 +81,13 @@ export async function runTrial({ supervisor, maxTokens, temperature, }) {
         contentPerSecond: elapsedSeconds > 0 ? content.length / elapsedSeconds : 0,
     };
 }
-export async function sweep({ runtime, model, profile, budgets = DEFAULT_BUDGETS, maxTokens = 8192, temperature = 0.7, internalPort = DEFAULT_INTERNAL_PORT + 2, onProgress = () => { }, }) {
+export async function sweep({ runtime, model, profile, budgets = DEFAULT_BUDGETS, maxTokens = 8192, temperature = 0.7, internalPort = DEFAULT_INTERNAL_PORT + 2, supervisor: optionsSupervisor, onProgress = () => { }, }) {
     const results = [];
     for (const budget of budgets) {
-        const supervisor = new Supervisor({ runtime, internalPort });
+        const supervisor = optionsSupervisor ?? new Supervisor({ runtime, internalPort });
         onProgress({ phase: "loading", budget });
         try {
-            await supervisor.start(model, { ...profile, reasoningBudget: budget });
+            await supervisor.start(model, { ...profile, reasoningBudget: budget }, { preserveLogs: Boolean(optionsSupervisor) });
             onProgress({ phase: "generating", budget });
             const trial = await runTrial({ supervisor, maxTokens, temperature });
             results.push({ budget, ...trial, error: null });

package/dist/runtime/args.d.ts

@@ -4,7 +4,7 @@
  * managed one, since both resolve to a `Runtime` (exe + optional vendorDir).
  */
 import type { Profile } from "../config/schema.js";
-import type { Runtime } from "../types.js";
+import type { Model, Runtime } from "../types.js";
 export interface ServeTarget {
     port: number;
     host?: string;
@@ -28,7 +28,7 @@ export declare function buildEnv(runtime: Runtime, baseEnv?: NodeJS.ProcessEnv,
  * Only settings that demonstrably matter for stable local inference are emitted -
  * no experimental sampler knobs.
  */
-export declare function buildArgs(profile: Profile, { port, host }: ServeTarget): string[];
+export declare function buildArgs(profile: Profile, { port, host }: ServeTarget, model?: Model): string[];
 /** The same command as a copy-pasteable shell line, for the TUI to display. */
 export declare function formatCommand(runtime: Runtime, args: string[]): string;
 //# sourceMappingURL=args.d.ts.map

package/dist/runtime/args.js

@@ -29,7 +29,7 @@ export function buildEnv(runtime, baseEnv = process.env, platform = process.plat
  * Only settings that demonstrably matter for stable local inference are emitted -
  * no experimental sampler knobs.
  */
-export function buildArgs(profile, { port, host = "127.0.0.1" }) {
+export function buildArgs(profile, { port, host = "127.0.0.1" }, model) {
     const args = [
         "-m",
         profile.modelPath ?? "",
@@ -52,6 +52,11 @@ export function buildArgs(profile, { port, host = "127.0.0.1" }) {
     if (profile.vision && profile.mmprojPath) {
         args.push("--mmproj", profile.mmprojPath);
     }
+    // Component paths were resolved by the host from the catalog manifest. Only
+    // the known llama.cpp role is emitted; clients never supply process paths.
+    const drafter = profile.componentPaths?.speculative_drafter;
+    if (drafter)
+        args.push("--model-draft", drafter);
     // The setting that was actually breaking long agentic runs.
     if (profile.reasoningBudget !== null && profile.reasoningBudget !== undefined) {
         args.push("--reasoning-budget", String(profile.reasoningBudget));
@@ -61,10 +66,22 @@ export function buildArgs(profile, { port, host = "127.0.0.1" }) {
     }
     if (profile.parallelSlots)
         args.push("--parallel", String(profile.parallelSlots));
+    if (profile.contextMultiplier > 1) {
+        const nativeContext = model?.metadata?.contextLength;
+        args.push("--rope-scaling", "yarn", "--rope-scale", String(profile.contextMultiplier), ...(nativeContext ? ["--yarn-orig-ctx", String(nativeContext)] : []), ...(model?.metadata?.arch
+            ? ["--override-kv", `${model.metadata.arch}.context_length=int:${profile.contextSize}`]
+            : []));
+    }
     if (profile.batchSize)
         args.push("-b", String(profile.batchSize));
     if (profile.ubatchSize)
         args.push("-ub", String(profile.ubatchSize));
+    if (profile.chatTemplateFile) {
+        args.push("--chat-template-file", profile.chatTemplateFile);
+        if (Object.keys(profile.chatTemplateKwargs ?? {}).length > 0) {
+            args.push("--chat-template-kwargs", JSON.stringify(profile.chatTemplateKwargs));
+        }
+    }
     if (profile.extraArgs && profile.extraArgs.length)
         args.push(...profile.extraArgs);
     return args;

package/dist/runtime/index.d.ts

@@ -3,7 +3,7 @@ import type { Runtime } from "../types.js";
 import { type InstallProgress, type RuntimeTarget } from "./managed.js";
 export { BACKENDS_DIR, LMSTUDIO_ROOT, listRuntimes as listLmStudioRuntimes } from "./lmstudio.js";
 export { buildArgs, buildEnv, formatCommand, type ServeTarget } from "./args.js";
-export { installManagedRuntime, listManagedRuntimes, listRuntimeDevices, verifyRuntimeExecutable, defaultRuntimeSpec, extractArchive, resolveRuntimeVariant, serverExeName, supportedVariants, DEFAULT_LLAMA_BUILD, type RuntimeSpec, type RuntimeTarget, type RuntimeVariant, type InstallProgress, } from "./managed.js";
+export { installManagedRuntime, removeManagedRuntime, listManagedRuntimes, listRuntimeDevices, verifyRuntimeExecutable, defaultRuntimeSpec, extractArchive, resolveRuntimeVariant, serverExeName, supportedVariants, DEFAULT_LLAMA_BUILD, listRuntimeReleases, latestRuntimeBuild, resolveLatestBuildOrPin, MissingAssetError, type ResolvedBuild, type RuntimeRelease, type RuntimeSpec, type RuntimeTarget, type RuntimeVariant, type InstallProgress, } from "./managed.js";
 /** Every runtime available on this machine, managed first then LM Studio. */
 export declare function listAllRuntimes(env?: NodeJS.ProcessEnv): Runtime[];
 /**
@@ -14,6 +14,13 @@ export declare function listAllRuntimes(env?: NodeJS.ProcessEnv): Runtime[];
 export declare function probeNvidiaGpu(): Promise<boolean>;
 /** The runtime to use given config, or null when none is available. */
 export declare function resolveRuntime(config: BrainConfig, env?: NodeJS.ProcessEnv): Runtime | null;
+/**
+ * The numeric llama.cpp build carried by a resolved runtime, when its source
+ * identifies one. LM Studio and explicit overrides need not expose their
+ * upstream build, so callers must treat null as incompatible with a component
+ * that declares a minimum build rather than guessing compatibility.
+ */
+export declare function runtimeBuild(runtime: Runtime | null | undefined): number | null;
 /** Ensure a runtime exists, downloading the default managed build if none does. */
 export declare function ensureRuntime(config: BrainConfig, env?: NodeJS.ProcessEnv, onProgress?: (progress: InstallProgress) => void, target?: RuntimeTarget): Promise<Runtime>;
 //# sourceMappingURL=index.d.ts.map