@otto-code/brain 0.8.10 → 0.8.13

package/dist/config/schema.js

@@ -6,6 +6,25 @@
  */
 import { z } from "zod";
 export const DEFAULT_REASONING_MESSAGE = "Enough analysis. Write the complete answer now.";
+const TemplateArgumentSchema = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/u);
+/**
+ * Model-native names for reasoning controls exposed by its chat template.
+ * These are catalog metadata, not caller-provided flags: the host owns the
+ * translation from the OpenAI-compatible request into template arguments.
+ */
+export const ReasoningTemplateSchema = z
+    .object({
+    enableThinkingArgument: TemplateArgumentSchema,
+    effortArgument: TemplateArgumentSchema,
+})
+    .strict();
+/** A template's native spelling for Brain's provider-neutral preservation setting. */
+export const ReasoningPreservationSchema = z
+    .object({
+    templateArgument: TemplateArgumentSchema,
+    default: z.boolean().optional(),
+})
+    .strict();
 // --------------------------------------------------------------- profiles store
 export const ProfileSchema = z
     .object({
@@ -24,7 +43,37 @@ export const ProfileSchema = z
     vision: z.boolean().default(false),
     reasoningBudget: z.number().default(1536),
     reasoningBudgetMessage: z.string().default(DEFAULT_REASONING_MESSAGE),
+    /**
+     * Tri-state, matching llama-server's own `--reasoning-preserve` /
+     * `--no-reasoning-preserve` / unset: `true` keeps the reasoning trace in the
+     * whole history, `false` forces it to the last assistant message only, and
+     * null/undefined leaves the template's own default alone. Null is the
+     * default precisely so an untouched profile emits no flag and launches
+     * exactly as it did before this field existed.
+     */
+    preserveReasoning: z.boolean().nullable().optional(),
+    // ------------------------------------------------------------- sampling
+    // Defaults are llama.cpp's own, read from `llama-server --help` on the
+    // pinned build (b10433) so an untouched profile runs identically to one
+    // that never emitted these flags. They are stored and emitted explicitly
+    // rather than left implicit because a sampler the user can see is one they
+    // can reason about; re-check them when DEFAULT_LLAMA_BUILD moves.
+    temperature: z.number().default(0.8),
+    topP: z.number().default(0.95),
+    topK: z.number().default(40),
+    minP: z.number().default(0.05),
+    presencePenalty: z.number().default(0),
+    repeatPenalty: z.number().default(1),
     parallelSlots: z.number().default(1),
+    /**
+     * How many chats' KV state llama-server may park in system RAM when they
+     * lose their GPU slot, so returning to one costs a bulk copy instead of a
+     * full re-prefill. Stored as a count, not a size: the byte budget it turns
+     * into (`--cache-ram`) depends on the measured KV bytes/token and the
+     * per-slot context, both of which move when other fields are edited.
+     * 0 means "leave llama.cpp's own default alone" - the flag is not emitted.
+     */
+    cachedChats: z.number().default(0),
     /** 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. */
@@ -171,6 +220,8 @@ export const RuntimeConfigSchema = z
     // auto = prefer a managed runtime, fall back to LM Studio discovery.
     source: z.enum(["auto", "managed", "lmstudio"]).default("auto"),
     path: z.string().nullable().default(null),
+    /** llama.cpp's `--log-verbosity`: 0 generic output through 5 debug. */
+    logVerbosity: z.number().int().min(0).max(5).default(3),
 })
     .strict();
 export const ProfileDefaultsSchema = z
@@ -200,9 +251,13 @@ export const BrainConfigSchema = z
     // persisted fallback so users can set it once (config set hfToken <token>).
     hfToken: z.string().nullable().default(null),
     defaultModel: z.string().nullable().default(null),
-    // Pin the host to a single model: serve only the default/resident model and
-    // refuse completion requests that name a different one, instead of queuing a
-    // switch. For hosts that load one model and must not thrash between clients.
+    /** Maximum independently hosted llama-server model processes. */
+    maxLoadedModels: z.number().int().min(1).max(16).default(1),
+    /** Stable ids selected for residency while model locking is enabled. */
+    lockedModels: z.array(z.string()).default([]),
+    // Pin the host to the selected resident set and refuse completion requests
+    // that name a different model. With a one-process host this preserves the
+    // original single-model lock behavior.
     lockModel: z.boolean().default(false),
     // Sharing/control gates (off by default - a brain is not remotely
     // controllable until its owner opts in). `allowRemoteConfig`: a client with
@@ -224,6 +279,8 @@ export const CatalogModelSchema = z
     name: z.string(),
     /** Stable UI family identity. Otto clients resolve this to a monochrome glyph. */
     family: z.string().optional(),
+    /** Otto-curated favorite shown as a gold premium badge in the Brain Library. */
+    favorite: z.boolean().default(false),
     publisher: z.string().optional(),
     hfRepo: z.string(),
     quant: z.string(),
@@ -234,6 +291,9 @@ export const CatalogModelSchema = z
     vision: z.boolean().optional(),
     thinking: z.boolean().optional(),
     reasoningEfforts: z.array(z.string()).optional(),
+    reasoningEffortDefault: z.string().optional(),
+    reasoningTemplate: ReasoningTemplateSchema.optional(),
+    reasoningPreservation: ReasoningPreservationSchema.optional(),
     contextMax: z.number().optional(),
     useCases: z.array(z.string()).optional(),
     tier: z.string().optional(),
@@ -265,6 +325,8 @@ export const CatalogSchema = z
     note: z.string().optional(),
     vramBudgetBytes: z.number().optional(),
     systemRamBytes: z.number().optional(),
+    /** Retired curated ids that no longer belong to any canonical catalog entry. */
+    retiredModelIds: z.array(z.string()).default([]),
     models: z.array(CatalogModelSchema).default([]),
 })
     .passthrough();

package/dist/config/store.js

@@ -65,10 +65,13 @@ export function loadCatalog(paths = resolveBrainPaths()) {
         if (!legacy)
             return current;
         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 ?? []));
+        // Curated models can be replaced or intentionally removed from the
+        // shortlist. Both kinds of retired ids stay product-owned so they do not
+        // survive a seed refresh as accidental "user-added" catalog rows.
+        const retiredSeedIds = new Set([
+            ...legacy.retiredModelIds,
+            ...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);

package/dist/gguf.d.ts

@@ -53,7 +53,14 @@ interface GgufSummary {
     isProjector: boolean;
     /** Chat template exposes a thinking/reasoning channel. */
     reasoning: boolean;
+    /** Native preservation argument, normalized by model enrichment when present. */
+    reasoningPreservationArgument?: "preserve_thinking" | "preserve_reasoning";
 }
+/** Read model-specific template spellings without leaking them into the UI contract. */
+export declare function detectTemplateReasoningCapabilities(chatTemplate: string): {
+    reasoning: boolean;
+    reasoningPreservationArgument?: "preserve_thinking" | "preserve_reasoning";
+};
 /**
  * Pull out the fields that matter for hosting decisions.
  */

package/dist/gguf.js

@@ -176,6 +176,19 @@ export function readMetadata(file) {
     }
     throw new Error(`could not read GGUF header from ${file}`);
 }
+/** Read model-specific template spellings without leaking them into the UI contract. */
+export function detectTemplateReasoningCapabilities(chatTemplate) {
+    const reasoningPreservationArgument = /\bpreserve_thinking\b/iu.test(chatTemplate)
+        ? "preserve_thinking"
+        : /\bpreserve_reasoning\b/iu.test(chatTemplate)
+            ? "preserve_reasoning"
+            : undefined;
+    return {
+        reasoning: Boolean(reasoningPreservationArgument ||
+            /<think>|<\/think>|reasoning_content|enable_thinking/iu.test(chatTemplate)),
+        ...(reasoningPreservationArgument ? { reasoningPreservationArgument } : {}),
+    };
+}
 /**
  * Pull out the fields that matter for hosting decisions.
  */
@@ -202,7 +215,7 @@ export function summarize(file) {
     const chatTemplate = typeof meta["tokenizer.chat_template"] === "string"
         ? meta["tokenizer.chat_template"]
         : "";
-    const reasoning = /<think>|<\/think>|reasoning_content|enable_thinking/i.test(chatTemplate);
+    const reasoningCapabilities = detectTemplateReasoningCapabilities(chatTemplate);
     return {
         file,
         fileSize,
@@ -226,7 +239,7 @@ export function summarize(file) {
         expertCount: (get("expert_count") ?? null),
         eosTokenId: (meta["tokenizer.ggml.eos_token_id"] ?? null),
         isProjector: Boolean(meta["clip.has_vision_encoder"] || arch === "clip"),
-        reasoning,
+        ...reasoningCapabilities,
     };
 }
 //# sourceMappingURL=gguf.js.map

package/dist/models/download.d.ts

@@ -13,7 +13,7 @@ export interface PullOptions {
 }
 /** 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): {
+export declare function bundleDownloadPlan(model: CatalogModel, componentIds?: string[], primaryFiles?: string[], primaryBytes?: number, includeRequired?: boolean): {
     repo: string;
     files: string[];
     totalBytes: number | null;

package/dist/models/download.js

@@ -195,13 +195,13 @@ async function streamRepoFile(url, destPath, label, token, onProgress, received)
 }
 /** 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) {
+export function bundleDownloadPlan(model, componentIds = [], primaryFiles, primaryBytes, includeRequired = true) {
     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 components = (model.components ?? []).filter((component) => (includeRequired && 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`);

package/dist/models/enrich.d.ts

@@ -14,6 +14,12 @@ export declare function familyFromGgufMetadata(model: Model): string | undefined
  * specific (longest) hfRepo.
  */
 export declare function matchCatalogEntry(model: Model, catalog: Catalog): CatalogModel | null;
+/**
+ * Bundle components are supporting artifacts, not independently selectable
+ * models. The disk scanner sees every GGUF, so remove an exact manifest match
+ * before the host exposes the inventory to the CLI or desktop client.
+ */
+export declare function excludeCatalogComponentArtifacts(models: Model[], catalog: Catalog): Model[];
 /**
  * Return copies of the models with catalog coding metadata attached where a match
  * exists; models with no match (and every model when the catalog is empty) pass

package/dist/models/enrich.js

@@ -112,6 +112,15 @@ export function matchCatalogEntry(model, catalog) {
     }
     return best;
 }
+/**
+ * Bundle components are supporting artifacts, not independently selectable
+ * models. The disk scanner sees every GGUF, so remove an exact manifest match
+ * before the host exposes the inventory to the CLI or desktop client.
+ */
+export function excludeCatalogComponentArtifacts(models, catalog) {
+    const componentIds = new Set(catalog.models.flatMap((entry) => (entry.components ?? []).map((component) => normalizePath(`${component.hfRepo ?? entry.hfRepo}/${component.file}`))));
+    return models.filter((model) => !componentIds.has(normalizePath(model.id)));
+}
 /**
  * Return copies of the models with catalog coding metadata attached where a match
  * exists; models with no match (and every model when the catalog is empty) pass
@@ -123,7 +132,14 @@ export function enrichWithCatalog(models, catalog) {
         if (!entry) {
             const enriched = enrichDiscoveredProjector(model);
             const family = familyFromGgufMetadata(enriched);
-            return family ? { ...enriched, family } : enriched;
+            const reasoningPreservation = detectedReasoningPreservation(enriched);
+            if (!family && !reasoningPreservation)
+                return enriched;
+            return {
+                ...enriched,
+                ...(family ? { family } : {}),
+                ...(reasoningPreservation ? { reasoningPreservation } : {}),
+            };
         }
         const components = resolveComponents(model, entry);
         const projector = components?.find((component) => component.role === "vision_projector");
@@ -141,10 +157,20 @@ export function enrichWithCatalog(models, catalog) {
             tier: entry.tier,
             thinking: entry.thinking,
             reasoningEfforts: entry.reasoningEfforts,
+            reasoningEffortDefault: entry.reasoningEffortDefault,
+            reasoningTemplate: entry.reasoningTemplate,
+            reasoningPreservation: entry.reasoningPreservation ?? detectedReasoningPreservation(model),
             contextMax: entry.contextMax,
         };
     });
 }
+/** Map the two known template spellings to one model capability. */
+function detectedReasoningPreservation(model) {
+    const templateArgument = model.metadata?.reasoningPreservationArgument;
+    return templateArgument === "preserve_thinking" || templateArgument === "preserve_reasoning"
+        ? { templateArgument }
+        : undefined;
+}
 /** Promote a scanner-paired projector in an arbitrary Hugging Face repository
  * into the same component inventory shape used by curated bundles. */
 function enrichDiscoveredProjector(model) {

package/dist/models/index.d.ts

@@ -4,7 +4,7 @@ export * from "./scan.js";
 export { pickModel, pickAutoModel } from "./pick.js";
 export { resolveModelsDirs, managedModelsDir, type ModelsDir } from "./dirs.js";
 export { pullModel, bundleDownloadPlan, downloadRepoFiles, type PullOptions, type PullProgress, type DownloadFilesOptions, } from "./download.js";
-export { matchCatalogEntry, enrichWithCatalog } from "./enrich.js";
+export { matchCatalogEntry, enrichWithCatalog, excludeCatalogComponentArtifacts, } from "./enrich.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 {

package/dist/models/index.js

@@ -3,14 +3,14 @@ import { resolveBrainPaths } from "../config/paths.js";
 import { CatalogSchema } from "../config/schema.js";
 import { loadCatalog } from "../config/store.js";
 import { resolveModelsDirs } from "./dirs.js";
-import { enrichWithCatalog } from "./enrich.js";
+import { enrichWithCatalog, excludeCatalogComponentArtifacts } from "./enrich.js";
 import { loadRenameMap } from "./rename-map.js";
 import { scan } from "./scan.js";
 export * from "./scan.js";
 export { pickModel, pickAutoModel } from "./pick.js";
 export { resolveModelsDirs, managedModelsDir } from "./dirs.js";
 export { pullModel, bundleDownloadPlan, downloadRepoFiles, } from "./download.js";
-export { matchCatalogEntry, enrichWithCatalog } from "./enrich.js";
+export { matchCatalogEntry, enrichWithCatalog, excludeCatalogComponentArtifacts, } from "./enrich.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. */
@@ -33,7 +33,8 @@ export function scanModels(config, env = process.env, options = {}) {
             all.push(model);
         }
     }
-    const enriched = enrichWithCatalog(all, loadCatalogSafe(env));
+    const catalog = loadCatalogSafe(env);
+    const enriched = enrichWithCatalog(excludeCatalogComponentArtifacts(all, catalog), catalog);
     const renameMap = loadRenameMap(resolveBrainPaths(env));
     for (const model of enriched) {
         if (renameMap[model.id]) {

package/dist/ops/archive.d.ts

@@ -1,4 +1,17 @@
 import type { Model } from "../types.js";
+/**
+ * Raw model output archive.
+ *
+ * Scoring is a separate, replayable pass over stored transcripts rather than
+ * something that only happens live. This exists because a bug in the scorer
+ * (a filename matcher that attributed every test block to the wrong file) made
+ * seven models look identical, and fixing it cost a full re-run on the GPU. The
+ * model outputs had been correct all along - only the grading was wrong.
+ *
+ * With the transcript on disk, a scorer fix re-grades history in seconds.
+ */
+/** Resolve the writable transcript store for a given host environment. */
+declare function resolveArchiveDir(env?: NodeJS.ProcessEnv): string;
 declare const ARCHIVE_DIR: string;
 /** One archived request/response exchange. */
 export interface TranscriptEntry {
@@ -30,5 +43,5 @@ declare function load(id: string): Record<string, TranscriptEntry[]>;
 declare function list(): string[];
 /** Total bytes held, so the archive can be pruned knowingly. */
 declare function size(): number;
-export { ARCHIVE_DIR, runId, runDir, put, load, list, size };
+export { ARCHIVE_DIR, resolveArchiveDir, runId, runDir, put, load, list, size };
 //# sourceMappingURL=archive.d.ts.map

package/dist/ops/archive.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
-import { fileURLToPath } from "node:url";
+import { resolveBrainPaths } from "../config/paths.js";
 /**
  * Raw model output archive.
  *
@@ -13,9 +13,13 @@ import { fileURLToPath } from "node:url";
  *
  * With the transcript on disk, a scorer fix re-grades history in seconds.
  */
-const HERE = path.dirname(fileURLToPath(import.meta.url));
-const ROOT = path.resolve(HERE, "..", "..");
-const ARCHIVE_DIR = path.join(ROOT, "results", "transcripts");
+/** Resolve the writable transcript store for a given host environment. */
+function resolveArchiveDir(env = process.env) {
+    return path.join(resolveBrainPaths(env).resultsDir, "transcripts");
+}
+// Raw benchmark exchanges are host state too. They must follow the score store
+// into OTTO_HOME rather than attempting to write beside the installed package.
+const ARCHIVE_DIR = resolveArchiveDir();
 function runId(model, timestamp = new Date()) {
     const stamp = timestamp.toISOString().replace(/[:.]/g, "-");
     const slug = String(model?.displayName || "unknown")
@@ -101,5 +105,5 @@ function size() {
     }
     return bytes;
 }
-export { ARCHIVE_DIR, runId, runDir, put, load, list, size };
+export { ARCHIVE_DIR, resolveArchiveDir, runId, runDir, put, load, list, size };
 //# sourceMappingURL=archive.js.map

package/dist/ops/calibrate.d.ts

@@ -1,6 +1,6 @@
 import { Supervisor } from "../service/supervisor.js";
 import type { Model, Runtime } from "../types.js";
-import type { Profile } from "../config/schema.js";
+import type { Calibration, Profile } from "../config/schema.js";
 /**
  * Measure a model's real KV-cache cost per token.
  *
@@ -10,8 +10,15 @@ import type { Profile } from "../config/schema.js";
  * slope: bytes/token = (vram_b - vram_a) / (ctx_b - ctx_a). Everything that
  * does not scale with context (weights, projector, CUDA context, compute
  * buffers) cancels out of the difference.
+ *
+ * Two invariants keep that slope honest. The high sample is the profile's
+ * configured context (the depth the user will actually serve at) capped by
+ * what fits in VRAM - never the raw native × multiplier ceiling, which on a
+ * tight card loads a cache that spills to system RAM and biases the slope low.
+ * A sample whose load split the KV cache to CPU is unusable: the GPU delta
+ * misses the spilled share, the bytes/token comes out understated, and the
+ * budget then declares a context "fits" that actually runs on a RAM cache.
  */
-export declare const DEFAULT_SAMPLES: number[];
 /** A single context-size measurement collected during calibration. */
 export interface CalibrationSample {
     contextSize: number;
@@ -26,14 +33,42 @@ export interface CalibrateProgress {
     deltaBytes?: number;
     error?: string;
 }
+/**
+ * Detect that a load split its KV cache onto system RAM.
+ *
+ * `usedBytes()` reads nvidia-smi, which only sees the GPU share of the cache.
+ * When llama-server cannot hold the whole allocation in VRAM it does not fail
+ * the load - it offloads the overflow to CPU and the load "succeeds" at a
+ * fraction of the VRAM the context should cost. The startup banner is the
+ * only place the split is stated.
+ */
+export declare function kvSpilledToCpu(logLines: string[]): boolean;
+/**
+ * The largest context size the static VRAM budget allows, or null when the
+ * cost per token is unknown and the budget cannot answer. Used to keep the
+ * calibration samples inside the region where the GPU sees the whole cache.
+ */
+export declare function maxContextForCalibration(model: Model, profile: Profile, calibration: Calibration | null, totalVramBytes: number): number | null;
 export interface CalibrateOptions {
     runtime: Runtime;
     model: Model;
     profile: Profile;
+    /** Explicit context sizes to measure. Replaces the default strategy entirely. */
     samples?: number[];
+    /**
+     * The calibration being replaced, if one exists. The best prior on bytes/token
+     * for this exact profile shape, so the sample cap can use the measured figure
+     * instead of the (over-estimating) theoretical one.
+     */
+    priorCalibration?: Calibration | null;
     internalPort?: number;
     /** Reuse the host's resident supervisor instead of creating a sidecar server. */
     supervisor?: Supervisor;
+    /**
+     * Pause after stopping each sample so the driver releases its allocation
+     * before the next load. Tests run with zero.
+     */
+    releaseDelayMs?: number;
     onProgress?: (event: CalibrateProgress) => void;
 }
 /** The measured KV-cache profile calibration produces. */
@@ -48,5 +83,5 @@ export interface CalibrationMeasurement {
     vision: boolean;
     measuredAt: string;
 }
-export declare function calibrate({ runtime, model, profile, samples, internalPort, supervisor: optionsSupervisor, onProgress, }: CalibrateOptions): Promise<CalibrationMeasurement>;
+export declare function calibrate({ runtime, model, profile, samples, priorCalibration, internalPort, supervisor: optionsSupervisor, releaseDelayMs, onProgress, }: CalibrateOptions): Promise<CalibrationMeasurement>;
 //# sourceMappingURL=calibrate.d.ts.map

package/dist/ops/calibrate.js

@@ -1,24 +1,67 @@
-import { usedBytes } from "../gpu.js";
+import { query, usedBytes } from "../gpu.js";
 import * as vram from "../vram.js";
 import { DEFAULT_INTERNAL_PORT, Supervisor } from "../service/supervisor.js";
 /**
- * Measure a model's real KV-cache cost per token.
+ * Detect that a load split its KV cache onto system RAM.
  *
- * The theoretical formula (layers x kv_heads x dims x bytes) overestimates
- * badly on architectures that only keep a full cache on some layers - by ~4x
- * on `qwen35`. So we load the model twice at two context sizes and take the
- * slope: bytes/token = (vram_b - vram_a) / (ctx_b - ctx_a). Everything that
- * does not scale with context (weights, projector, CUDA context, compute
- * buffers) cancels out of the difference.
+ * `usedBytes()` reads nvidia-smi, which only sees the GPU share of the cache.
+ * When llama-server cannot hold the whole allocation in VRAM it does not fail
+ * the load - it offloads the overflow to CPU and the load "succeeds" at a
+ * fraction of the VRAM the context should cost. The startup banner is the
+ * only place the split is stated.
  */
-export const DEFAULT_SAMPLES = [8192, 65536];
-export async function calibrate({ runtime, model, profile, samples, internalPort = DEFAULT_INTERNAL_PORT + 1, supervisor: optionsSupervisor, onProgress = () => { }, }) {
+export function kvSpilledToCpu(logLines) {
+    return logLines.some((line) => /KV .*split|CPU buffer size|KV cache.*offload|offloading \d+ layers? to cpu/i.test(line));
+}
+/**
+ * The largest context size the static VRAM budget allows, or null when the
+ * cost per token is unknown and the budget cannot answer. Used to keep the
+ * calibration samples inside the region where the GPU sees the whole cache.
+ */
+export function maxContextForCalibration(model, profile, calibration, totalVramBytes) {
+    const max = vram.maxContextThatFits({
+        model,
+        profile,
+        calibration,
+        totalVramBytes,
+    });
+    return max && max >= 4096 ? max : null;
+}
+export async function calibrate({ runtime, model, profile, samples, priorCalibration = null, internalPort = DEFAULT_INTERNAL_PORT + 1, supervisor: optionsSupervisor, releaseDelayMs = 3000, onProgress = () => { }, }) {
     const nativeContext = model.metadata?.contextLength ?? null;
-    const effectiveSamples = samples ??
-        (nativeContext ? [8192, nativeContext * profile.contextMultiplier] : DEFAULT_SAMPLES);
+    const nativeCeiling = nativeContext ? nativeContext * profile.contextMultiplier : null;
+    const gpu = (await query());
+    // The high sample is the depth the profile will actually serve at - its
+    // configured context, clamped to the native × multiplier ceiling - not the
+    // raw ceiling itself. On a card where that depth does not fit, the static
+    // budget caps it at the largest context that does. Measuring at a context
+    // whose KV spills to CPU understates bytes/token and poisons the budget.
+    const configured = Math.max(4096, profile.contextSize);
+    let high = configured;
+    if (nativeCeiling !== null && high > nativeCeiling)
+        high = nativeCeiling;
+    if (gpu !== null) {
+        const maxFits = maxContextForCalibration(model, profile, priorCalibration, gpu.totalBytes);
+        if (maxFits !== null && high > maxFits) {
+            high = maxFits;
+            onProgress({
+                phase: "skip",
+                contextSize: configured,
+                reason: `configured context exceeds what fits in VRAM; measuring at ${high.toLocaleString()}`,
+            });
+        }
+    }
+    // The low sample is a fixed small context far enough below the serving depth
+    // that the KV delta dominates the fixed terms (weights, CUDA context). The
+    // high sample never drops below it: a VRAM cap that pushed the two together
+    // would make the slope a difference of near-equal numbers, and at high == low
+    // a division by zero.
+    const lowContext = 4096;
+    const highContext = Math.max(high, lowContext * 2);
+    const effectiveSamples = samples ?? [lowContext, highContext];
     if (effectiveSamples.length < 2)
         throw new Error("calibration needs at least two context sizes");
-    const native = (nativeContext || Math.max(...effectiveSamples)) * profile.contextMultiplier;
+    const native = nativeCeiling ?? Math.max(...effectiveSamples);
     const points = [];
     for (const contextSize of effectiveSamples) {
         if (contextSize > native) {
@@ -29,7 +72,12 @@ export async function calibrate({ runtime, model, profile, samples, internalPort
         onProgress({ phase: "loading", contextSize });
         const baseline = await usedBytes();
         try {
-            await supervisor.start(model, { ...profile, contextSize }, { preserveLogs: Boolean(optionsSupervisor) });
+            await supervisor.start(model, { ...profile, contextSize });
+            if (kvSpilledToCpu(supervisor.logLines)) {
+                const reason = `KV cache split to CPU at ${contextSize.toLocaleString()} context`;
+                onProgress({ phase: "failed", contextSize, reason });
+                throw new Error(`${reason} - the context does not fit in VRAM. Lower the context or use a smaller KV cache type before calibrating.`);
+            }
             const used = supervisor.vramAtReadyBytes ?? (await usedBytes());
             const delta = Number(used) - Number(supervisor.vramBaselineBytes ?? baseline);
             points.push({ contextSize, deltaBytes: delta, loadSeconds: supervisor.loadSeconds });
@@ -46,21 +94,22 @@ export async function calibrate({ runtime, model, profile, samples, internalPort
         finally {
             await supervisor.stop();
             // Let the driver actually release the allocation before the next sample.
-            await new Promise((resolve) => setTimeout(resolve, 3000));
+            if (releaseDelayMs > 0)
+                await new Promise((resolve) => setTimeout(resolve, releaseDelayMs));
         }
     }
     if (points.length < 2) {
         throw new Error("calibration produced fewer than two usable samples");
     }
     points.sort((a, b) => a.contextSize - b.contextSize);
-    const low = points[0];
-    const high = points[points.length - 1];
-    const kvBytesPerToken = (high.deltaBytes - low.deltaBytes) / (high.contextSize - low.contextSize);
+    const lowPoint = points[0];
+    const highPoint = points[points.length - 1];
+    const kvBytesPerToken = (highPoint.deltaBytes - lowPoint.deltaBytes) / (highPoint.contextSize - lowPoint.contextSize);
     if (!(kvBytesPerToken > 0)) {
         throw new Error("measured a non-positive bytes-per-token; results are unusable");
     }
     const fixedBytes = model.sizeBytes + (profile.vision && model.mmprojPath ? model.mmprojBytes : 0);
-    const baseOverheadBytes = Math.max(0, low.deltaBytes - fixedBytes - kvBytesPerToken * low.contextSize);
+    const baseOverheadBytes = Math.max(0, lowPoint.deltaBytes - fixedBytes - kvBytesPerToken * lowPoint.contextSize);
     const theoretical = vram.theoreticalKvBytesPerToken(model.metadata, profile.cacheTypeK, profile.cacheTypeV);
     return {
         kvBytesPerToken,