@otto-code/brain 0.8.10 → 0.8.13

package/dist/ops/report.js

@@ -28,6 +28,54 @@ function escapeHtml(text) {
 function formatGiB(bytes) {
     return bytes ? `${(bytes / 1024 ** 3).toFixed(1)} GB` : "-";
 }
+// The sampler defaults come from `configKey`'s own constant: the report and
+// the grouping key must agree on what counts as "the engine default", or the
+// report would print settings the key says were never changed.
+const SAMPLER_DEFAULTS = results.ENGINE_SAMPLER_DEFAULTS;
+/**
+ * The schema-3 profile settings that changed what a run was measured with,
+ * as a short human line. Returns "" when nothing deviates from the engine
+ * defaults, so an untouched run prints exactly what it always did. Older
+ * records that predate these fields store `null` for every one, which also
+ * collapses to "" - the report never guesses a value it was not given.
+ */
+function formatProfileExtras(record) {
+    const p = record.profile;
+    if (!p)
+        return "";
+    const parts = [];
+    if (p.contextMultiplier !== null && p.contextMultiplier > 1) {
+        parts.push(`x${p.contextMultiplier} ctx`);
+    }
+    if (p.cachedChats !== null && p.cachedChats > 0) {
+        parts.push(`${p.cachedChats} cached`);
+    }
+    if (p.preserveReasoning === true)
+        parts.push("reasoning preserved");
+    else if (p.preserveReasoning === false)
+        parts.push("reasoning trimmed");
+    // Each entry pairs the display name with the `SAMPLER_DEFAULTS` key the
+    // default is looked up by - the two deliberately differ (see `configKey`).
+    const sampler = [
+        ["temp", p.temperature, "temperature"],
+        ["topP", p.topP, "topP"],
+        ["topK", p.topK, "topK"],
+        ["minP", p.minP, "minP"],
+        ["pres", p.presencePenalty, "presencePenalty"],
+        ["rep", p.repeatPenalty, "repeatPenalty"],
+    ];
+    // `typeof` rather than a null check: a record from before the sampler was
+    // stored carries `undefined` for every one of these, and that must read as
+    // "not recorded", not as a deviation.
+    const deviated = sampler
+        .filter(([, value, key]) => typeof value === "number" && value !== SAMPLER_DEFAULTS[key])
+        .map(([name, value]) => `${name} ${value}`);
+    if (deviated.length > 0)
+        parts.push(deviated.join(", "));
+    if (p.hostingProfileId)
+        parts.push("hosting profile");
+    return parts.join(" · ");
+}
 /**
  * Per-model score card: each task labelled directly with its weight, then the
  * weighted Overall on its own row so the headline number reads as the sum of its
@@ -61,6 +109,7 @@ function groupedBars(records, columns, weightOf) {
             record.model.quant,
             `ctx ${(record.profile?.contextSize || 0).toLocaleString()}`,
             `rb ${record.profile?.reasoningBudget}`,
+            formatProfileExtras(record),
         ]
             .filter(Boolean)
             .join(" · ");
@@ -267,6 +316,7 @@ function build(records, allRuns = records) {
         return (`<tr><td>${escapeHtml(r.model.displayName)}</td><td>${escapeHtml(r.model.quant || "-")}</td>` +
             `<td class="num">${(r.profile?.contextSize || 0).toLocaleString()}</td>` +
             `<td class="num">${r.profile?.reasoningBudget ?? "-"}</td>` +
+            `<td class="muted">${escapeHtml(formatProfileExtras(r) || "-")}</td>` +
             `${cells}<td class="num strong">${(r.overall * 100).toFixed(0)}%</td>` +
             `<td class="num">${formatGiB(r.vramBytes)}</td>` +
             `<td class="muted">${escapeHtml(r.ranAt.slice(0, 16).replace("T", " "))}</td></tr>`);
@@ -434,7 +484,7 @@ function build(records, allRuns = records) {
     <h2>All runs</h2>
     <div class="scroll">
       <table>
-        <thead><tr><th>Model</th><th>Quant</th><th class="num">Context</th><th class="num">Reasoning</th>
+        <thead><tr><th>Model</th><th>Quant</th><th class="num">Context</th><th class="num">Reasoning</th><th>Settings</th>
           ${columns.map((c) => `<th class="num">${escapeHtml(c.category)}<span class="wt">×${weightOf.get(c.id) ?? "?"}</span></th>`).join("")}
           <th class="num">Overall<span class="wt">wtd</span></th><th class="num">VRAM</th><th>Run at</th></tr></thead>
         <tbody>${tableRows}</tbody>

package/dist/ops/results.d.ts

@@ -1,6 +1,26 @@
 import type { GpuInfo, Model, ModelFeatures } from "../types.js";
 import type { Calibration, Profile } from "../config/schema.js";
 import type { FitResult } from "../vram.js";
+/**
+ * Persistent benchmark history.
+ *
+ * One JSON file per run, so results accumulate across sessions and can be
+ * compared and charted later. Runs record the configuration they were measured
+ * under, because a score is meaningless without the quant, context size and
+ * reasoning budget that produced it.
+ *
+ * **A run records every value it was measured with, not a summary of them.** A
+ * bad score is far more often a bad setup than a bad model, and the difference
+ * is only visible from the settings: a context the VRAM fit had to cut, a
+ * reasoning budget the model spends entirely on thinking, a KV quant that
+ * wrecked recall, weights that fell off the GPU because `gpuLayers` did not
+ * cover them, a budget estimated from the formula rather than measured. None of
+ * that is recoverable after the fact, so it is all written down at save time -
+ * including the exact llama-server argv the run was served with, which is the
+ * only true statement of what ran.
+ */
+/** Resolve the writable store for benchmark scores for a given host environment. */
+declare function resolveResultsDir(env?: NodeJS.ProcessEnv): string;
 declare const RESULTS_DIR: string;
 /** Aggregate of a numeric health series (nvidia-smi samples during a run). */
 export interface AggStat {
@@ -78,7 +98,10 @@ export interface RecordModel {
  * a bad score - `gpuLayers` short of the model's layer count silently runs part
  * of it on the CPU, `parallelSlots` splits the context between slots so the
  * effective window is a fraction of `contextSize`, and `extraArgs` can override
- * anything above.
+ * anything above. Schema 3 added the settings that landed after the setup-capture
+ * change - `preserveReasoning`, `contextMultiplier`, `cachedChats`, the sampler
+ * values, and the hosting-profile identity - so the record keeps tracking the
+ * profile instead of silently stopping at the field set it was born with.
  */
 export interface RecordProfile {
     contextSize: number;
@@ -93,6 +116,28 @@ export interface RecordProfile {
     batchSize: number | null;
     ubatchSize: number | null;
     extraArgs: string[];
+    /**
+     * Schema 3+. Absent on schema 2 records, which predate the setting.
+     * Tri-state: true/false as chosen, null for "the template's own default".
+     */
+    preserveReasoning: boolean | null;
+    /** Schema 3+. RoPE extension factor; 1 is the GGUF-native window. */
+    contextMultiplier: number;
+    /** Schema 3+. Chats parked in system RAM; 0 leaves llama.cpp's default. */
+    cachedChats: number;
+    /** Schema 3+. The sampler the run was served with, server-level for every task. */
+    temperature: number | null;
+    topP: number | null;
+    topK: number | null;
+    minP: number | null;
+    presencePenalty: number | null;
+    repeatPenalty: number | null;
+    /**
+     * Schema 3+. The Brain-owned hosting profile in effect (id, not text): its
+     * chat template and system-prompt addendum change what the model is asked
+     * to do, so a run under one profile is not comparable to one under another.
+     */
+    hostingProfileId: string | null;
 }
 /**
  * How the run was actually set up, as opposed to how it was configured.
@@ -173,10 +218,12 @@ export interface RecordTask {
 /**
  * One stored benchmark run - the shared shape used across results and report.
  *
- * `schema` is 2 as of the setup-capture change: 2 carries the full profile plus
- * `setup` and `suite`; 1 carried six profile fields and neither. Readers must
- * treat everything added in 2 as absent on an older record rather than assuming
- * it, because those runs are still perfectly good scores - they just cannot say
+ * `schema` is 3 as of the profile-completeness change: 3 carries every profile
+ * field that reaches llama-server, including the sampler values and the hosting
+ * profile; 2 carried the profile as of the setup-capture change plus `setup`
+ * and `suite`; 1 carried six profile fields and neither. Readers must treat
+ * everything added after a record's schema as absent rather than assuming it,
+ * because those runs are still perfectly good scores - they just cannot say
  * what they were measured with.
  */
 export interface RunRecord {
@@ -283,14 +330,33 @@ export interface TaskColumn {
     category: string;
 }
 declare function slugify(text: string): string;
+/**
+ * llama.cpp's own sampler defaults, the values an untouched profile stores
+ * verbatim (see `ProfileSchema`). A key token is only emitted when the profile
+ * deviates from these, which is what makes an untouched profile keep its
+ * historical key after the widening.
+ */
+declare const ENGINE_SAMPLER_DEFAULTS: {
+    readonly temperature: 0.8;
+    readonly topP: 0.95;
+    readonly topK: 40;
+    readonly minP: 0.05;
+    readonly presencePenalty: 0;
+    readonly repeatPenalty: 1;
+};
 /**
  * Stable identity for "same model, same settings", so reruns can be grouped.
  *
- * Deliberately unchanged when the record grew: this string is the grouping key
- * every stored run was written with, and widening it would not re-key history -
- * it would split each model's past runs from its future ones and quietly reset
- * every variance figure on the page. New settings are recorded as data, not
- * folded in here.
+ * The base four tokens predate the record and are never rewritten - a stored
+ * run's key is its key, and re-deriving the same string for the same setup is
+ * what lets old runs stay in their old groups. The tokens added in schema 3 are
+ * appended ONLY when they deviate from the engine default, because that is what
+ * the key means: the effective configuration, and a default is the historical
+ * configuration. An untouched profile therefore keeps exactly the key it had
+ * before the setting existed, so variance figures for unchanged setups survive
+ * the widening; a run that differs only in, say, `contextMultiplier` gets a
+ * new key instead of silently merging into its predecessor's group and
+ * contaminating that group's consistency line.
  */
 declare function configKey(profile: Profile | null): string;
 declare function save({ model, profile, report, gpu, runtime, archiveId, system, args, fit, calibration, suite, timestamp, }: SaveOptions): SaveResult;
@@ -322,5 +388,5 @@ declare function variance(records?: RunRecord[]): VarianceRow[];
 declare function rankModels(records?: RunRecord[]): RankedModel[];
 /** All task ids seen across a set of records, in a stable order. */
 declare function taskColumns(records: RunRecord[]): TaskColumn[];
-export { RESULTS_DIR, save, loadAll, latestPerConfig, grouped, variance, stats, rankModels, taskColumns, configKey, slugify, };
+export { RESULTS_DIR, resolveResultsDir, save, loadAll, latestPerConfig, grouped, variance, stats, rankModels, taskColumns, configKey, slugify, ENGINE_SAMPLER_DEFAULTS, };
 //# sourceMappingURL=results.d.ts.map

package/dist/ops/results.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { resolveBrainPaths } from "../config/paths.js";
 /**
  * Persistent benchmark history.
  *
@@ -19,9 +19,14 @@ import { fileURLToPath } from "node:url";
  * including the exact llama-server argv the run was served with, which is the
  * only true statement of what ran.
  */
-const HERE = path.dirname(fileURLToPath(import.meta.url));
-const ROOT = path.resolve(HERE, "..", "..");
-const RESULTS_DIR = path.join(ROOT, "results");
+/** Resolve the writable store for benchmark scores for a given host environment. */
+function resolveResultsDir(env = process.env) {
+    return resolveBrainPaths(env).resultsDir;
+}
+// Benchmark history is host state, not package data. Keeping it beside the
+// Brain config also makes the service work from packaged/Electron installs,
+// where the package directory may be an archive or read-only.
+const RESULTS_DIR = resolveResultsDir();
 function slugify(text) {
     return String(text)
         .toLowerCase()
@@ -29,24 +34,77 @@ function slugify(text) {
         .replace(/^-|-$/g, "")
         .slice(0, 80);
 }
+/**
+ * llama.cpp's own sampler defaults, the values an untouched profile stores
+ * verbatim (see `ProfileSchema`). A key token is only emitted when the profile
+ * deviates from these, which is what makes an untouched profile keep its
+ * historical key after the widening.
+ */
+const ENGINE_SAMPLER_DEFAULTS = {
+    temperature: 0.8,
+    topP: 0.95,
+    topK: 40,
+    minP: 0.05,
+    presencePenalty: 0,
+    repeatPenalty: 1,
+};
 /**
  * Stable identity for "same model, same settings", so reruns can be grouped.
  *
- * Deliberately unchanged when the record grew: this string is the grouping key
- * every stored run was written with, and widening it would not re-key history -
- * it would split each model's past runs from its future ones and quietly reset
- * every variance figure on the page. New settings are recorded as data, not
- * folded in here.
+ * The base four tokens predate the record and are never rewritten - a stored
+ * run's key is its key, and re-deriving the same string for the same setup is
+ * what lets old runs stay in their old groups. The tokens added in schema 3 are
+ * appended ONLY when they deviate from the engine default, because that is what
+ * the key means: the effective configuration, and a default is the historical
+ * configuration. An untouched profile therefore keeps exactly the key it had
+ * before the setting existed, so variance figures for unchanged setups survive
+ * the widening; a run that differs only in, say, `contextMultiplier` gets a
+ * new key instead of silently merging into its predecessor's group and
+ * contaminating that group's consistency line.
  */
 function configKey(profile) {
     if (!profile)
         return "unknown";
-    return [
+    const parts = [
         `ctx${profile.contextSize}`,
         `kv${profile.cacheTypeK}-${profile.cacheTypeV}`,
         `rb${profile.reasoningBudget}`,
         profile.vision ? "vision" : "novision",
-    ].join("_");
+    ];
+    if (profile.contextMultiplier !== undefined && profile.contextMultiplier > 1) {
+        parts.push(`x${profile.contextMultiplier}`);
+    }
+    if (profile.cachedChats !== undefined && profile.cachedChats > 0) {
+        parts.push(`cc${profile.cachedChats}`);
+    }
+    if (profile.preserveReasoning === true)
+        parts.push("pr");
+    else if (profile.preserveReasoning === false)
+        parts.push("nopr");
+    // The sampler deviates from the engine default only when the user set it -
+    // an untouched profile stores llama.cpp's own defaults verbatim, and those
+    // are the default, so they carry no token. Each entry pairs the short token
+    // name with the `ENGINE_SAMPLER_DEFAULTS` key the default is looked up by -
+    // the two deliberately differ, so conflating them would emit every sampler
+    // value on every key.
+    const sampler = [
+        ["temp", profile.temperature, "temperature"],
+        ["p", profile.topP, "topP"],
+        ["k", profile.topK, "topK"],
+        ["minp", profile.minP, "minP"],
+        ["pres", profile.presencePenalty, "presencePenalty"],
+        ["rep", profile.repeatPenalty, "repeatPenalty"],
+    ];
+    for (const [name, value, defaultKey] of sampler) {
+        if (typeof value === "number" &&
+            Number.isFinite(value) &&
+            value !== ENGINE_SAMPLER_DEFAULTS[defaultKey]) {
+            parts.push(`${name}${value}`);
+        }
+    }
+    if (profile.hostingProfileId)
+        parts.push(`hp${profile.hostingProfileId}`);
+    return parts.join("_");
 }
 /** Read a numeric GGUF metadata field, which is `null` when the header lacked it. */
 function metadataNumber(model, key) {
@@ -83,7 +141,7 @@ function buildSetup({ args, fit, calibration, }) {
 function save({ model, profile, report, gpu = null, runtime = null, archiveId = null, system = null, args = null, fit = null, calibration = null, suite = null, timestamp = new Date(), }) {
     fs.mkdirSync(RESULTS_DIR, { recursive: true });
     const record = {
-        schema: 2,
+        schema: 3,
         ranAt: timestamp.toISOString(),
         model: {
             id: model?.id ?? null,
@@ -99,7 +157,9 @@ function save({ model, profile, report, gpu = null, runtime = null, archiveId =
         },
         // The whole profile, not a summary of it. `ProfileSchema` is `.passthrough()`
         // and its numeric fields carry defaults, so read them defensively: a profile
-        // written by an older brain can be missing anything below `vision`.
+        // written by an older brain can be missing anything below `vision`, and a
+        // schema-1-era profile can be missing the sampler values entirely (they
+        // were implicit in llama.cpp then).
         profile: profile
             ? {
                 contextSize: profile.contextSize,
@@ -114,6 +174,16 @@ function save({ model, profile, report, gpu = null, runtime = null, archiveId =
                 batchSize: profile.batchSize ?? null,
                 ubatchSize: profile.ubatchSize ?? null,
                 extraArgs: profile.extraArgs ?? [],
+                preserveReasoning: profile.preserveReasoning ?? null,
+                contextMultiplier: profile.contextMultiplier ?? 1,
+                cachedChats: profile.cachedChats ?? 0,
+                temperature: profile.temperature ?? null,
+                topP: profile.topP ?? null,
+                topK: profile.topK ?? null,
+                minP: profile.minP ?? null,
+                presencePenalty: profile.presencePenalty ?? null,
+                repeatPenalty: profile.repeatPenalty ?? null,
+                hostingProfileId: profile.hostingProfileId ?? null,
             }
             : null,
         setup: buildSetup({ args, fit, calibration }),
@@ -318,5 +388,5 @@ function taskColumns(records) {
     }
     return [...seen.entries()].map(([id, category]) => ({ id, category }));
 }
-export { RESULTS_DIR, save, loadAll, latestPerConfig, grouped, variance, stats, rankModels, taskColumns, configKey, slugify, };
+export { RESULTS_DIR, resolveResultsDir, save, loadAll, latestPerConfig, grouped, variance, stats, rankModels, taskColumns, configKey, slugify, ENGINE_SAMPLER_DEFAULTS, };
 //# sourceMappingURL=results.js.map

package/dist/ops/sweep.d.ts

@@ -7,7 +7,19 @@ import type { Profile } from "../config/schema.js";
  * Thinking models default to an unrestricted budget (-1) and will happily burn
  * an entire token allowance reasoning, returning no content at all. The right
  * cap is model-specific, so measure it: run one long-horizon task per candidate
- * budget and score by delivered content per second.
+ * budget and take the largest budget that still delivers the whole task. See
+ * rankSweepResults for why "largest" and not "fastest".
+ */
+/**
+ * The candidates a sweep tries, in ascending order of thinking room.
+ *
+ * Capped at 1536 deliberately. The ranking prefers the largest budget that
+ * still delivers, so whatever sits at the top of this list is what a healthy
+ * thinking model gets recommended - the list itself is the ceiling, and 1536 is
+ * the value every hand-set profile has run on without trouble. Each extra
+ * candidate also costs a full model load plus a long generation, so the ladder
+ * earns its length. `-1` stays because a model that fails under every finite cap
+ * still needs an answer; it ranks last and wins only in that case.
  */
 export declare const DEFAULT_BUDGETS: number[];
 export declare const LONG_TASK: string;
@@ -75,5 +87,30 @@ export interface SweepOptions {
     onProgress?: (event: SweepProgress) => void;
 }
 export declare function sweep({ runtime, model, profile, budgets, maxTokens, temperature, internalPort, supervisor: optionsSupervisor, onProgress, }: SweepOptions): Promise<SweepReport>;
+/**
+ * Rank a sweep's trials, best first. `ranked[0].budget` is the recommendation.
+ *
+ * Delivery decides first: a budget that dropped a file did not do the job.
+ * Among the budgets that delivered everything, prefer the **largest** - the most
+ * thinking room a model can have without failing to deliver.
+ *
+ * That tie used to break on content per second, which was backwards. LONG_TASK
+ * is pure output, so reasoning earns nothing on it and only costs wall clock:
+ * every budget large enough to finish delivered all four files, the tie-break
+ * therefore decided every sweep, and the smallest candidate won by construction
+ * - 0 included. That is how models ended up capped at 0 and 512, tight enough
+ * that llama-server guillotines an ordinary thought mid-sentence, injects
+ * `--reasoning-budget-message`, and the model's unfinished reasoning carries on
+ * over the content channel as user-visible prose. The sweep's job is to find the
+ * cap past which a model degenerates into reasoning forever, not the cap that
+ * types fastest. See the "reasoning budget makes thinking bleed into prose"
+ * finding in Otto Knowledge.
+ *
+ * `-1` is the one budget "largest" must not read as large: an unrestricted
+ * budget is the failure this package exists to prevent. It ranks below every
+ * finite cap and is recommended only when nothing else survived, which means a
+ * cap of any size broke the model.
+ */
+export declare function rankSweepResults(results: readonly SweepResult[]): SweepResult[];
 export {};
 //# sourceMappingURL=sweep.d.ts.map

package/dist/ops/sweep.js

@@ -6,9 +6,23 @@ import { DEFAULT_INTERNAL_PORT, Supervisor } from "../service/supervisor.js";
  * Thinking models default to an unrestricted budget (-1) and will happily burn
  * an entire token allowance reasoning, returning no content at all. The right
  * cap is model-specific, so measure it: run one long-horizon task per candidate
- * budget and score by delivered content per second.
+ * budget and take the largest budget that still delivers the whole task. See
+ * rankSweepResults for why "largest" and not "fastest".
  */
-export const DEFAULT_BUDGETS = [0, 512, 1536, 3072, -1];
+/**
+ * The candidates a sweep tries, in ascending order of thinking room.
+ *
+ * Capped at 1536 deliberately. The ranking prefers the largest budget that
+ * still delivers, so whatever sits at the top of this list is what a healthy
+ * thinking model gets recommended - the list itself is the ceiling, and 1536 is
+ * the value every hand-set profile has run on without trouble. Each extra
+ * candidate also costs a full model load plus a long generation, so the ladder
+ * earns its length. `-1` stays because a model that fails under every finite cap
+ * still needs an answer; it ranks last and wins only in that case.
+ */
+export const DEFAULT_BUDGETS = [0, 512, 1536, -1];
+/** llama.cpp's "no cap at all" sentinel, which a sweep must never recommend. */
+const UNRESTRICTED_BUDGET = -1;
 export const LONG_TASK = "Write a complete Python implementation of a thread-safe LRU cache with TTL " +
     "expiry. Produce FOUR separate complete files, each fully implemented with no " +
     "placeholders or elisions:\n" +
@@ -87,7 +101,7 @@ export async function sweep({ runtime, model, profile, budgets = DEFAULT_BUDGETS
         const supervisor = optionsSupervisor ?? new Supervisor({ runtime, internalPort });
         onProgress({ phase: "loading", budget });
         try {
-            await supervisor.start(model, { ...profile, reasoningBudget: budget }, { preserveLogs: Boolean(optionsSupervisor) });
+            await supervisor.start(model, { ...profile, reasoningBudget: budget });
             onProgress({ phase: "generating", budget });
             const trial = await runTrial({ supervisor, maxTokens, temperature });
             results.push({ budget, ...trial, error: null });
@@ -109,13 +123,7 @@ export async function sweep({ runtime, model, profile, budgets = DEFAULT_BUDGETS
             await new Promise((resolve) => setTimeout(resolve, 2500));
         }
     }
-    // Prefer runs that delivered every file; break ties on content per second.
-    const viable = results.filter((r) => !r.error && r.contentChars > 0);
-    const ranked = [...viable].sort((a, b) => {
-        if (b.filesDelivered !== a.filesDelivered)
-            return b.filesDelivered - a.filesDelivered;
-        return b.contentPerSecond - a.contentPerSecond;
-    });
+    const ranked = rankSweepResults(results);
     return {
         results,
         recommended: ranked.length ? ranked[0].budget : null,
@@ -123,4 +131,47 @@ export async function sweep({ runtime, model, profile, budgets = DEFAULT_BUDGETS
         sweptAt: new Date().toISOString(),
     };
 }
+/**
+ * Rank a sweep's trials, best first. `ranked[0].budget` is the recommendation.
+ *
+ * Delivery decides first: a budget that dropped a file did not do the job.
+ * Among the budgets that delivered everything, prefer the **largest** - the most
+ * thinking room a model can have without failing to deliver.
+ *
+ * That tie used to break on content per second, which was backwards. LONG_TASK
+ * is pure output, so reasoning earns nothing on it and only costs wall clock:
+ * every budget large enough to finish delivered all four files, the tie-break
+ * therefore decided every sweep, and the smallest candidate won by construction
+ * - 0 included. That is how models ended up capped at 0 and 512, tight enough
+ * that llama-server guillotines an ordinary thought mid-sentence, injects
+ * `--reasoning-budget-message`, and the model's unfinished reasoning carries on
+ * over the content channel as user-visible prose. The sweep's job is to find the
+ * cap past which a model degenerates into reasoning forever, not the cap that
+ * types fastest. See the "reasoning budget makes thinking bleed into prose"
+ * finding in Otto Knowledge.
+ *
+ * `-1` is the one budget "largest" must not read as large: an unrestricted
+ * budget is the failure this package exists to prevent. It ranks below every
+ * finite cap and is recommended only when nothing else survived, which means a
+ * cap of any size broke the model.
+ */
+export function rankSweepResults(results) {
+    const viable = results.filter((result) => !result.error && result.contentChars > 0);
+    return [...viable].sort((a, b) => {
+        if (b.filesDelivered !== a.filesDelivered) {
+            return b.filesDelivered - a.filesDelivered;
+        }
+        const rankA = budgetRank(a.budget);
+        const rankB = budgetRank(b.budget);
+        if (rankA === rankB) {
+            return 0;
+        }
+        // Compared rather than subtracted: the sentinel's rank is -Infinity, and
+        // -Infinity - -Infinity is NaN, which would corrupt the whole sort.
+        return rankB > rankA ? 1 : -1;
+    });
+}
+function budgetRank(budget) {
+    return budget === UNRESTRICTED_BUDGET ? Number.NEGATIVE_INFINITY : budget;
+}
 //# sourceMappingURL=sweep.js.map

package/dist/runtime/args.d.ts

@@ -3,11 +3,24 @@
  * needs. Runtime-source agnostic: works the same for an LM Studio runtime or a
  * managed one, since both resolve to a `Runtime` (exe + optional vendorDir).
  */
-import type { Profile } from "../config/schema.js";
+import type { Calibration, Profile } from "../config/schema.js";
 import type { Model, Runtime } from "../types.js";
 export interface ServeTarget {
     port: number;
     host?: string;
+    /** llama.cpp log threshold; 3 preserves its upstream default Info output. */
+    logVerbosity?: number;
+    /**
+     * A directory the engine may use for its slot save/restore/erase actions
+     * (`POST /slots`). Passing it is what UNLOCKS the `action=erase` route:
+     * llama.cpp refuses every `POST /slots` action when `--slot-save-path` is not
+     * set, and the scheduler's cross-chat KV-bleed fix erases a slot's retained
+     * KV the moment it is handed to a different chat. The directory must exist -
+     * the engine validates it at launch and throws otherwise - so the caller
+     * creates it. Absent (null) means the engine's own default: slot actions
+     * disabled, which is the pre-fix behavior.
+     */
+    slotSavePath?: string | null;
 }
 /**
  * Loader environment the child process needs so it can resolve its shared
@@ -28,7 +41,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, model?: Model): string[];
+export declare function buildArgs(profile: Profile, { port, host, logVerbosity, slotSavePath }: ServeTarget, model?: Model, calibration?: Calibration | null): 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

@@ -1,3 +1,5 @@
+import { promptCacheSize } from "../vram.js";
+const MIB = 1024 * 1024;
 /**
  * Loader environment the child process needs so it can resolve its shared
  * libraries. Both the runtime dir and its vendor dir go first, ahead of the
@@ -29,7 +31,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" }, model) {
+export function buildArgs(profile, { port, host = "127.0.0.1", logVerbosity = 3, slotSavePath = null }, model, calibration) {
     const args = [
         "-m",
         profile.modelPath ?? "",
@@ -47,8 +49,19 @@ export function buildArgs(profile, { port, host = "127.0.0.1" }, model) {
         host,
         "--port",
         String(port),
-        "--no-webui",
+        "--no-ui",
+        "-lv",
+        String(logVerbosity),
     ];
+    // A slot-save directory unlocks the engine's `POST /slots` actions - the
+    // `action=erase` the scheduler needs to wipe a slot's retained KV before it
+    // is handed to a different chat (see OWNERSHIP in scheduler.ts). Without it
+    // llama.cpp refuses every slot action with "start it with --slot-save-path".
+    // The directory must already exist: the engine validates it at launch and
+    // throws otherwise, so the caller creates it before building the args.
+    if (slotSavePath) {
+        args.push("--slot-save-path", slotSavePath);
+    }
     if (profile.vision && profile.mmprojPath) {
         args.push("--mmproj", profile.mmprojPath);
     }
@@ -64,8 +77,44 @@ export function buildArgs(profile, { port, host = "127.0.0.1" }, model) {
             args.push("--reasoning-budget-message", profile.reasoningBudgetMessage);
         }
     }
+    // Whether the reasoning trace stays in the whole history or is trimmed to the
+    // last assistant message. Emitted only on an explicit choice: llama-server's
+    // own default is the template's, and there is no third flag spelling for "do
+    // what the template says" - the absence of the flag IS that state.
+    if (profile.preserveReasoning === true) {
+        args.push("--reasoning-preserve");
+    }
+    else if (profile.preserveReasoning === false) {
+        args.push("--no-reasoning-preserve");
+    }
+    // Sampler settings. Always emitted, because the profile stores llama.cpp's own
+    // defaults verbatim, so an untouched profile produces the run it always did
+    // while the values stay visible and editable rather than implicit.
+    for (const [flag, value] of [
+        ["--temp", profile.temperature],
+        ["--top-p", profile.topP],
+        ["--top-k", profile.topK],
+        ["--min-p", profile.minP],
+        ["--presence-penalty", profile.presencePenalty],
+        ["--repeat-penalty", profile.repeatPenalty],
+    ]) {
+        if (typeof value === "number" && Number.isFinite(value)) {
+            args.push(flag, String(value));
+        }
+    }
     if (profile.parallelSlots)
         args.push("--parallel", String(profile.parallelSlots));
+    // Prompt cache: how much host RAM llama-server may use to park the KV state
+    // of chats that lost their slot, so returning to one is a bulk copy instead
+    // of a full re-prefill. Sized from the chat count the user chose, because a
+    // raw MiB figure is unusable without knowing this model's KV bytes/token.
+    // Emitted only when the size is real: with no measurement, the theoretical
+    // KV cost overestimates by multiples, and reserving multiples of the RAM
+    // actually needed is worse than leaving llama.cpp's own default in place.
+    const cache = model ? promptCacheSize(model, profile, calibration) : null;
+    if (cache && cache.source === "measured") {
+        args.push("--cache-ram", String(Math.max(1, Math.round(cache.totalBytes / MIB))));
+    }
     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
@@ -78,9 +127,15 @@ export function buildArgs(profile, { port, host = "127.0.0.1" }, model) {
         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));
-        }
+    }
+    const templateKwargs = { ...profile.chatTemplateKwargs };
+    const preservation = model?.reasoningPreservation;
+    if (preservation?.templateArgument) {
+        templateKwargs[preservation.templateArgument] =
+            profile.preserveReasoning ?? preservation.default ?? false;
+    }
+    if (Object.keys(templateKwargs).length > 0) {
+        args.push("--chat-template-kwargs", JSON.stringify(templateKwargs));
     }
     if (profile.extraArgs && profile.extraArgs.length)
         args.push(...profile.extraArgs);