@otto-code/brain 0.7.6 → 0.8.1

package/dist/config/profile-edit.d.ts

@@ -0,0 +1,94 @@
+import type { Model } from "../types.js";
+import type { Profile, ProfilesStore } from "./schema.js";
+/** How a client should render a field. */
+export type ProfileFieldKind = "number" | "toggle" | "cycle";
+export interface ProfileFieldDescriptor {
+    key: string;
+    label: string;
+    kind: ProfileFieldKind;
+    /** For `number`: the increment a stepper should use. */
+    step?: number;
+    min?: number;
+    max?: number;
+    /** For `cycle`: the values to offer, in order. */
+    options?: (string | number)[];
+    /** Labels for `options`, index-aligned, when the raw value is not presentable. */
+    optionLabels?: string[];
+    /** False when this model cannot use the field at all (vision with no projector). */
+    available: boolean;
+    /** Why it is unavailable, for the disabled-state hint. */
+    unavailableReason?: string;
+}
+/**
+ * The cache types the editor cycles through. `CACHE_TYPE_BYTES` knows more
+ * (f32, bf16, q5_0, q4_1) and a write naming one of those is accepted; these
+ * four are the ones worth offering, matching the TUI's cycle.
+ */
+export declare const CACHE_TYPE_CYCLE: string[];
+/**
+ * Reasoning budgets worth offering. 0 disables thinking; -1 is unrestricted and
+ * is the documented failure mode, so it is last and carries a warning. A sweep
+ * may persist any value, so the write path accepts any integer >= -1.
+ */
+export declare const REASONING_BUDGET_CYCLE: number[];
+/** The sentinel llama-server reads as "do not cap thinking at all". */
+export declare const UNRESTRICTED_REASONING_BUDGET = -1;
+/**
+ * The user-facing name for a budget. `-1` is never shown raw: it is a sentinel,
+ * not a token count, and printing it next to a `0` row invites the reading that
+ * one of them means "less thinking" than the other when `-1` means the most
+ * possible. "unrestricted" is the one word for it everywhere (TUI, sweep table,
+ * warnings) - do not introduce a synonym.
+ */
+export declare function formatReasoningBudget(budget: number): string;
+export declare const MAX_PARALLEL_SLOTS = 16;
+export declare const MAX_GPU_LAYERS = 999;
+export declare const MIN_CONTEXT_SIZE = 1024;
+export declare const CONTEXT_STEP = 8192;
+/** The context ceiling: the model's native window, or a generous bound if unknown. */
+export declare function nativeContextLimit(model: Model | null): number;
+/** The editable fields, resolved against one model's capabilities. */
+export declare function profileFieldDescriptors(model: Model | null): ProfileFieldDescriptor[];
+/** A note attached to a field, or to the profile as a whole when `field` is null. */
+export interface ProfileWarning {
+    field: string | null;
+    severity: "info" | "warn";
+    message: string;
+    /** True when this combination cannot start, as opposed to merely being unwise. */
+    blocksStart: boolean;
+}
+/** The notes a UI shows beside the fields, and the reason a load would be refused. */
+export declare function profileWarnings(profile: Profile, model: Model | null, store?: ProfilesStore | null): ProfileWarning[];
+/** Where a model's KV bytes/token figure came from. */
+export type CalibrationState = "measured" | "inherited" | "stale" | "theoretical" | "unknown";
+export interface CalibrationInfo {
+    state: CalibrationState;
+    kvBytesPerToken: number | null;
+    measuredAt: string | null;
+    /** For `inherited`, the relative the measurement came from. */
+    measuredOn: string | null;
+}
+/**
+ * Classify the calibration backing this profile's budget. `inherited` means the
+ * figure came from a relative with the same attention geometry rescaled to this
+ * model's layer count, which the UI must never present as measured on this file.
+ */
+export declare function calibrationInfo(store: ProfilesStore, model: Model, profile: Profile): CalibrationInfo;
+export interface SanitizeResult {
+    profile: Profile;
+    /** Fields the patch named that were clamped, coerced, or dropped. */
+    adjustments: string[];
+}
+/**
+ * Apply an editable patch to a profile, clamping every field to its range and
+ * dropping anything the model cannot use.
+ *
+ * Only the eight editable keys are honoured. `modelPath`/`mmprojPath`/`modelId`
+ * are re-derived from the model on every read (`profiles.forModel`), so letting
+ * a caller set them would be a lie at best and a path-traversal at worst.
+ * `reasoningBudgetMessage`, `batchSize`, `ubatchSize` and `extraArgs` stay
+ * CLI-only: they have no measured effect worth exposing and `extraArgs` is
+ * arbitrary process arguments.
+ */
+export declare function sanitizeProfilePatch(current: Profile, patch: unknown, model: Model | null): SanitizeResult;
+//# sourceMappingURL=profile-edit.d.ts.map

package/dist/config/profile-edit.js

@@ -0,0 +1,269 @@
+/**
+ * The editable surface of a per-model profile: which fields a UI may change,
+ * what values each accepts, and what warnings a given combination earns.
+ *
+ * This exists so the ranges live in exactly one place. The TUI enforced them
+ * inline in its field table (`tui/app.ts`), which was fine while the TUI was the
+ * only editor. Now `/__host/models/:id/profile` accepts writes from Otto's Brain
+ * page too, and a validator that disagreed with the editor would either reject
+ * something the UI offered or accept something that cannot start.
+ *
+ * The warnings are the empirical part and must survive edits:
+ *  - A quantised V cache requires flash attention. Without it llama-server
+ *    refuses to allocate the cache and the model never reaches ready.
+ *  - An unrestricted reasoning budget (-1) is the failure this package exists to
+ *    prevent: thinking models spend an entire token allowance reasoning and
+ *    return no content at all.
+ *  - Changing a cache type invalidates a measured calibration, because KV
+ *    bytes/token is a function of the cache types (see `vram.ts`).
+ */
+import { CACHE_TYPE_BYTES } from "../vram.js";
+import { getCalibration, hasStaleCalibration } from "./profiles.js";
+/**
+ * The cache types the editor cycles through. `CACHE_TYPE_BYTES` knows more
+ * (f32, bf16, q5_0, q4_1) and a write naming one of those is accepted; these
+ * four are the ones worth offering, matching the TUI's cycle.
+ */
+export const CACHE_TYPE_CYCLE = ["q4_0", "q5_1", "q8_0", "f16"];
+/**
+ * Reasoning budgets worth offering. 0 disables thinking; -1 is unrestricted and
+ * is the documented failure mode, so it is last and carries a warning. A sweep
+ * may persist any value, so the write path accepts any integer >= -1.
+ */
+export const REASONING_BUDGET_CYCLE = [0, 512, 1024, 1536, 3072, -1];
+/** The sentinel llama-server reads as "do not cap thinking at all". */
+export const UNRESTRICTED_REASONING_BUDGET = -1;
+/**
+ * The user-facing name for a budget. `-1` is never shown raw: it is a sentinel,
+ * not a token count, and printing it next to a `0` row invites the reading that
+ * one of them means "less thinking" than the other when `-1` means the most
+ * possible. "unrestricted" is the one word for it everywhere (TUI, sweep table,
+ * warnings) - do not introduce a synonym.
+ */
+export function formatReasoningBudget(budget) {
+    return budget === UNRESTRICTED_REASONING_BUDGET ? "unrestricted" : String(budget);
+}
+export const MAX_PARALLEL_SLOTS = 16;
+export const MAX_GPU_LAYERS = 999;
+export const MIN_CONTEXT_SIZE = 1024;
+export const CONTEXT_STEP = 8192;
+/** The context ceiling: the model's native window, or a generous bound if unknown. */
+export function nativeContextLimit(model) {
+    const native = model?.metadata?.contextLength;
+    return typeof native === "number" && native > 0 ? native : 1000000;
+}
+/** The editable fields, resolved against one model's capabilities. */
+export function profileFieldDescriptors(model) {
+    const hasProjector = Boolean(model?.mmprojPath);
+    return [
+        {
+            key: "contextSize",
+            label: "Context",
+            kind: "number",
+            step: CONTEXT_STEP,
+            min: MIN_CONTEXT_SIZE,
+            max: nativeContextLimit(model),
+            available: true,
+        },
+        {
+            key: "cacheTypeK",
+            label: "KV cache K",
+            kind: "cycle",
+            options: CACHE_TYPE_CYCLE,
+            available: true,
+        },
+        {
+            key: "cacheTypeV",
+            label: "KV cache V",
+            kind: "cycle",
+            options: CACHE_TYPE_CYCLE,
+            available: true,
+        },
+        { key: "flashAttention", label: "Flash attention", kind: "toggle", available: true },
+        {
+            key: "vision",
+            label: "Vision",
+            kind: "toggle",
+            available: hasProjector,
+            ...(hasProjector ? {} : { unavailableReason: "no projector" }),
+        },
+        {
+            key: "reasoningBudget",
+            label: "Reasoning budget",
+            kind: "cycle",
+            options: REASONING_BUDGET_CYCLE,
+            optionLabels: ["Thinking Off", "512", "1024", "1536", "3072", "Unrestricted"],
+            min: -1,
+            available: true,
+        },
+        {
+            key: "gpuLayers",
+            label: "GPU layers",
+            kind: "number",
+            step: 1,
+            min: 0,
+            max: MAX_GPU_LAYERS,
+            available: true,
+        },
+        {
+            key: "parallelSlots",
+            label: "Parallel slots",
+            kind: "number",
+            step: 1,
+            min: 1,
+            max: MAX_PARALLEL_SLOTS,
+            available: true,
+        },
+    ];
+}
+/** Whether a KV cache type is quantised (anything that is not a float type). */
+function isQuantised(cacheType) {
+    return /^q/i.test(cacheType);
+}
+/** The notes a UI shows beside the fields, and the reason a load would be refused. */
+export function profileWarnings(profile, model, store) {
+    const warnings = [];
+    if (!profile.flashAttention && isQuantised(profile.cacheTypeV)) {
+        warnings.push({
+            field: "flashAttention",
+            severity: "warn",
+            message: "A quantised V cache requires flash attention.",
+            blocksStart: true,
+        });
+    }
+    if (profile.reasoningBudget === -1) {
+        warnings.push({
+            field: "reasoningBudget",
+            severity: "warn",
+            message: "Unrestricted: a thinking model can spend its whole token allowance reasoning and return no content.",
+            blocksStart: false,
+        });
+    }
+    if (profile.parallelSlots > 1) {
+        warnings.push({
+            field: "parallelSlots",
+            severity: "info",
+            message: `${profile.parallelSlots} concurrent requests, sharing one KV pool.`,
+            blocksStart: false,
+        });
+    }
+    if (model && store && hasStaleCalibration(store, model, profile)) {
+        warnings.push({
+            field: "cacheTypeK",
+            severity: "info",
+            message: "Cache types changed since the last measurement. Recalibrate for a real budget.",
+            blocksStart: false,
+        });
+    }
+    return warnings;
+}
+/**
+ * Classify the calibration backing this profile's budget. `inherited` means the
+ * figure came from a relative with the same attention geometry rescaled to this
+ * model's layer count, which the UI must never present as measured on this file.
+ */
+export function calibrationInfo(store, model, profile) {
+    const calibration = getCalibration(store, model, profile);
+    if (!calibration) {
+        return {
+            state: hasStaleCalibration(store, model, profile) ? "stale" : "theoretical",
+            kvBytesPerToken: null,
+            measuredAt: null,
+            measuredOn: null,
+        };
+    }
+    return {
+        state: calibration.inherited ? "inherited" : "measured",
+        kvBytesPerToken: calibration.kvBytesPerToken,
+        measuredAt: calibration.measuredAt ?? null,
+        measuredOn: calibration.measuredOn ?? null,
+    };
+}
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+/**
+ * Apply an editable patch to a profile, clamping every field to its range and
+ * dropping anything the model cannot use.
+ *
+ * Only the eight editable keys are honoured. `modelPath`/`mmprojPath`/`modelId`
+ * are re-derived from the model on every read (`profiles.forModel`), so letting
+ * a caller set them would be a lie at best and a path-traversal at worst.
+ * `reasoningBudgetMessage`, `batchSize`, `ubatchSize` and `extraArgs` stay
+ * CLI-only: they have no measured effect worth exposing and `extraArgs` is
+ * arbitrary process arguments.
+ */
+export function sanitizeProfilePatch(current, patch, model) {
+    const adjustments = [];
+    const next = { ...current };
+    if (typeof patch !== "object" || patch === null || Array.isArray(patch)) {
+        throw new Error("profile patch must be an object");
+    }
+    const p = patch;
+    const takeNumber = (key, min, max) => {
+        if (!(key in p))
+            return;
+        const raw = p[key];
+        if (typeof raw !== "number" || !Number.isFinite(raw)) {
+            throw new Error(`${key} must be a number`);
+        }
+        const rounded = Math.round(raw);
+        const clamped = clamp(rounded, min, max);
+        if (clamped !== rounded)
+            adjustments.push(`${key} clamped to ${clamped}`);
+        next[key] = clamped;
+    };
+    const takeBoolean = (key) => {
+        if (!(key in p))
+            return;
+        if (typeof p[key] !== "boolean")
+            throw new Error(`${key} must be a boolean`);
+        next[key] = p[key];
+    };
+    const takeCacheType = (key) => {
+        if (!(key in p))
+            return;
+        const raw = p[key];
+        if (typeof raw !== "string")
+            throw new Error(`${key} must be a string`);
+        const value = raw.toLowerCase();
+        if (!(value in CACHE_TYPE_BYTES)) {
+            throw new Error(`unknown KV cache type "${raw}"`);
+        }
+        next[key] = value;
+    };
+    takeNumber("contextSize", MIN_CONTEXT_SIZE, nativeContextLimit(model));
+    takeCacheType("cacheTypeK");
+    takeCacheType("cacheTypeV");
+    takeBoolean("flashAttention");
+    takeNumber("gpuLayers", 0, MAX_GPU_LAYERS);
+    takeNumber("parallelSlots", 1, MAX_PARALLEL_SLOTS);
+    // -1 (unrestricted) is the floor; anything below it is meaningless to
+    // llama-server. There is no upper bound worth inventing: a budget larger than
+    // the context is simply never reached.
+    if ("reasoningBudget" in p) {
+        const raw = p.reasoningBudget;
+        if (typeof raw !== "number" || !Number.isFinite(raw)) {
+            throw new Error("reasoningBudget must be a number");
+        }
+        const rounded = Math.round(raw);
+        const value = rounded < -1 ? -1 : rounded;
+        if (value !== rounded)
+            adjustments.push(`reasoningBudget clamped to ${value}`);
+        next.reasoningBudget = value;
+    }
+    // Vision is only real when the model actually has a projector paired with it.
+    if ("vision" in p) {
+        if (typeof p.vision !== "boolean")
+            throw new Error("vision must be a boolean");
+        if (p.vision && !model?.mmprojPath) {
+            adjustments.push("vision ignored: this model has no projector");
+            next.vision = false;
+        }
+        else {
+            next.vision = p.vision;
+        }
+    }
+    return { profile: next, adjustments };
+}
+//# sourceMappingURL=profile-edit.js.map

package/dist/config/profiles.d.ts

@@ -1,7 +1,7 @@
 /**
  * Per-model hosting profiles and the measured-calibration lookup, ported from the
  * original profiles.js. Only settings with a demonstrated effect on stability or
- * throughput are stored — notably `reasoningBudget`, which defaults to -1
+ * throughput are stored - notably `reasoningBudget`, which defaults to -1
  * (unrestricted) in llama-server and in that state makes thinking models spend an
  * entire token allowance reasoning and return no content at all.
  */
@@ -24,7 +24,7 @@ export declare function hasStaleCalibration(store: ProfilesStore, model: Model,
  * file: two models sharing an architecture and head dimensions cost the same per
  * layer regardless of quantisation or fine-tuning. Storing the measurement *per
  * layer* and keying it without the layer count lets one calibration serve a whole
- * family — which matters on a library holding a dozen variants of one base, and is
+ * family - which matters on a library holding a dozen variants of one base, and is
  * necessary because MTP builds carry an extra multi-token-prediction layer (65
  * blocks where the base has 64) and would otherwise never match.
  */

package/dist/config/profiles.js

@@ -56,7 +56,7 @@ export function hasStaleCalibration(store, model, profile) {
  * file: two models sharing an architecture and head dimensions cost the same per
  * layer regardless of quantisation or fine-tuning. Storing the measurement *per
  * layer* and keying it without the layer count lets one calibration serve a whole
- * family — which matters on a library holding a dozen variants of one base, and is
+ * family - which matters on a library holding a dozen variants of one base, and is
  * necessary because MTP builds carry an extra multi-token-prediction layer (65
  * blocks where the base has 64) and would otherwise never match.
  */

package/dist/config/schema.d.ts

@@ -562,10 +562,10 @@ export type Auth = z.infer<typeof AuthSchema>;
 /**
  * TLS termination, built into the brain so it can be exposed over HTTPS with no
  * relay in front. Four modes:
- *  - `off`      — plain HTTP (the default; loopback-only is the safe posture).
- *  - `files`    — bring your own cert/key (a real cert, or one you manage).
- *  - `self-signed` — generate a local keypair on first run, cached under `certDir`.
- *  - `tailscale` — issue and auto-renew a real Let's Encrypt cert for this
+ *  - `off`      - plain HTTP (the default; loopback-only is the safe posture).
+ *  - `files`    - bring your own cert/key (a real cert, or one you manage).
+ *  - `self-signed` - generate a local keypair on first run, cached under `certDir`.
+ *  - `tailscale` - issue and auto-renew a real Let's Encrypt cert for this
  *                  machine's MagicDNS name via `tailscaled` (no cert warnings on
  *                  the tailnet). `hostname` is auto-detected when null.
  * The service layer enforces that a non-loopback bind still carries auth.

package/dist/config/schema.js

@@ -86,10 +86,10 @@ export const AuthSchema = z
 /**
  * TLS termination, built into the brain so it can be exposed over HTTPS with no
  * relay in front. Four modes:
- *  - `off`      — plain HTTP (the default; loopback-only is the safe posture).
- *  - `files`    — bring your own cert/key (a real cert, or one you manage).
- *  - `self-signed` — generate a local keypair on first run, cached under `certDir`.
- *  - `tailscale` — issue and auto-renew a real Let's Encrypt cert for this
+ *  - `off`      - plain HTTP (the default; loopback-only is the safe posture).
+ *  - `files`    - bring your own cert/key (a real cert, or one you manage).
+ *  - `self-signed` - generate a local keypair on first run, cached under `certDir`.
+ *  - `tailscale` - issue and auto-renew a real Let's Encrypt cert for this
  *                  machine's MagicDNS name via `tailscaled` (no cert warnings on
  *                  the tailnet). `hostname` is auto-detected when null.
  * The service layer enforces that a non-loopback bind still carries auth.
@@ -147,11 +147,11 @@ export const BrainConfigSchema = z
     // 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.
     lockModel: z.boolean().default(false),
-    // Sharing/control gates (off by default — a brain is not remotely
+    // Sharing/control gates (off by default - a brain is not remotely
     // controllable until its owner opts in). `allowRemoteConfig`: a client with
     // the token may CHANGE config over the network (POST /__host/config), not
     // just use/read. `allowInsecureBind`: permit a non-loopback bind with no
-    // token (an "open, trusted network" share) — otherwise the service refuses.
+    // token (an "open, trusted network" share) - otherwise the service refuses.
     allowRemoteConfig: z.boolean().default(false),
     allowInsecureBind: z.boolean().default(false),
     defaults: ProfileDefaultsSchema.default({}),

package/dist/config/store.d.ts

@@ -3,7 +3,7 @@ import { type BrainConfig, type Catalog, type ProfilesStore } from "./schema.js"
 export declare function loadProfilesStore(paths?: BrainPaths): ProfilesStore;
 export declare function saveProfilesStore(store: ProfilesStore, paths?: BrainPaths): void;
 export declare function loadCatalog(paths?: BrainPaths): Catalog;
-/** Persisted config only — no env overrides. Used by writers. */
+/** Persisted config only - no env overrides. Used by writers. */
 export declare function loadPersistedConfig(paths?: BrainPaths): BrainConfig;
 /** Effective config: persisted file with env overrides layered on top. */
 export declare function loadBrainConfig(env?: NodeJS.ProcessEnv, paths?: BrainPaths): BrainConfig;

package/dist/config/store.js

@@ -53,7 +53,7 @@ export function loadCatalog(paths = resolveBrainPaths()) {
     return CatalogSchema.parse({ models: [] });
 }
 // --------------------------------------------------------------------- config
-/** Persisted config only — no env overrides. Used by writers. */
+/** Persisted config only - no env overrides. Used by writers. */
 export function loadPersistedConfig(paths = resolveBrainPaths()) {
     const current = readJson(paths.configFile, BrainConfigSchema);
     if (current)

package/dist/models/download.js

@@ -15,7 +15,7 @@ function resolveUrl(repo, file) {
 }
 /**
  * The GGUF filename to download. Prefer an explicit override, then the catalog
- * entry's `quantFile`, then the basename of the catalog `id` — which for the
+ * entry's `quantFile`, then the basename of the catalog `id` - which for the
  * seeded catalog is `<hfRepo>/<file>.gguf`, so the id already names the file.
  * Only if none of those yields a `.gguf` do we give up: community repos name
  * files inconsistently, so a bare id with no gguf basename still needs --file.

package/dist/models/enrich.d.ts

@@ -2,7 +2,7 @@
  * Reconciles scanned models back to their download-catalog entries so a model's
  * coding metadata (useCases, tier, thinking, contextMax) survives a `pull`. The
  * catalog carries this per entry, but once files land on disk scan.ts rebuilds a
- * Model from filename + GGUF header alone, dropping it — this is where it is
+ * Model from filename + GGUF header alone, dropping it - this is where it is
  * re-attached. Track B1 of the brain coding-capabilities work.
  *
  * The join key is the hfRepo path. download.ts writes each model to
@@ -14,7 +14,7 @@
  *
  * Total and best-effort by design: an empty catalog, a model with no match, or a
  * repo carrying several quants all resolve without throwing. Discovery returns
- * things unenriched on absence rather than raising — the caller decides whether
+ * things unenriched on absence rather than raising - the caller decides whether
  * absence matters.
  */
 import type { Catalog, CatalogModel } from "../config/schema.js";

package/dist/models/index.d.ts

@@ -1,7 +1,7 @@
 import type { BrainConfig } from "../config/schema.js";
 import type { Model } from "../types.js";
 export * from "./scan.js";
-export { pickModel } from "./pick.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 { matchCatalogEntry, enrichWithCatalog } from "./enrich.js";

package/dist/models/index.js

@@ -6,7 +6,7 @@ import { resolveModelsDirs } from "./dirs.js";
 import { enrichWithCatalog } from "./enrich.js";
 import { scan } from "./scan.js";
 export * from "./scan.js";
-export { pickModel } from "./pick.js";
+export { pickModel, pickAutoModel } from "./pick.js";
 export { resolveModelsDirs, managedModelsDir } from "./dirs.js";
 export { pullModel, downloadRepoFiles, } from "./download.js";
 export { matchCatalogEntry, enrichWithCatalog } from "./enrich.js";

package/dist/models/pick.d.ts

@@ -1,3 +1,12 @@
+import { type RankedModel } from "../ops/results.js";
 import type { Model } from "../types.js";
 export declare function pickModel(catalog: Model[], needle: string | undefined): Model;
+/**
+ * Choose a model when nothing named one: the best-ranked model from bench
+ * history that is still installed, or the first catalog entry when nothing
+ * has been benched yet. This is what "Automatic" (a null default model) means
+ * in the UI - it must always start something for a non-empty catalog. The
+ * VRAM fit check downstream in startService is what can still refuse the pick.
+ */
+export declare function pickAutoModel(catalog: Model[], ranked?: RankedModel[]): Model;
 //# sourceMappingURL=pick.d.ts.map

package/dist/models/pick.js

@@ -1,10 +1,11 @@
 /**
  * Resolve a model from an exact catalog id or a unique case-insensitive name
- * fragment. An ambiguous fragment is an error that lists the matches — ported
+ * fragment. An ambiguous fragment is an error that lists the matches - ported
  * from the original CLI's pickModel, but throwing a CommandError instead of
  * calling process.exit, so the output layer renders it.
  */
 import { CommandError } from "../output/types.js";
+import { rankModels } from "../ops/results.js";
 export function pickModel(catalog, needle) {
     if (!needle) {
         throw new CommandError({
@@ -33,4 +34,26 @@ export function pickModel(catalog, needle) {
     }
     return matches[0];
 }
+/**
+ * Choose a model when nothing named one: the best-ranked model from bench
+ * history that is still installed, or the first catalog entry when nothing
+ * has been benched yet. This is what "Automatic" (a null default model) means
+ * in the UI - it must always start something for a non-empty catalog. The
+ * VRAM fit check downstream in startService is what can still refuse the pick.
+ */
+export function pickAutoModel(catalog, ranked = rankModels()) {
+    if (catalog.length === 0) {
+        throw new CommandError({
+            code: "NO_MODEL",
+            message: "no models installed",
+            details: "run `otto brain pull <model>` to download one, or point at an LM Studio install",
+        });
+    }
+    for (const entry of ranked) {
+        const match = catalog.find((m) => m.id === entry.id);
+        if (match)
+            return match;
+    }
+    return catalog[0];
+}
 //# sourceMappingURL=pick.js.map