@otto-code/brain 0.8.18 → 0.9.0

package/dist/runtime/index.d.ts

@@ -3,6 +3,7 @@ import type { Runtime } from "../types.js";
 import { type InstallProgress, type RuntimeTarget } from "./managed.js";
 export { BACKENDS_DIR, LMSTUDIO_ROOT, listRuntimes as listLmStudioRuntimes } from "./lmstudio.js";
 export { buildArgs, buildEnv, formatCommand, type ServeTarget } from "./args.js";
+export { llamaCppRuntimeDriver, type ModelServerDriverLaunchInput, type ModelServerLaunch, type ModelServerRuntimeDriver, } from "./model-server-driver.js";
 export { installManagedRuntime, removeManagedRuntime, listManagedRuntimes, listRuntimeDevices, verifyRuntimeExecutable, defaultRuntimeSpec, extractArchive, resolveRuntimeVariant, serverExeName, supportedVariants, DEFAULT_LLAMA_BUILD, listRuntimeReleases, latestRuntimeBuild, resolveLatestBuildOrPin, MissingAssetError, type ResolvedBuild, type RuntimeRelease, type RuntimeSpec, type RuntimeTarget, type RuntimeVariant, type InstallProgress, } from "./managed.js";
 /** Every runtime available on this machine, managed first then LM Studio. */
 export declare function listAllRuntimes(env?: NodeJS.ProcessEnv): Runtime[];

package/dist/runtime/index.js

@@ -16,6 +16,7 @@ import { listRuntimes as listLmStudioRuntimes, resolveOverride } from "./lmstudi
 import { defaultRuntimeSpec, installManagedRuntime, listManagedRuntimes, } from "./managed.js";
 export { BACKENDS_DIR, LMSTUDIO_ROOT, listRuntimes as listLmStudioRuntimes } from "./lmstudio.js";
 export { buildArgs, buildEnv, formatCommand } from "./args.js";
+export { llamaCppRuntimeDriver, } from "./model-server-driver.js";
 export { installManagedRuntime, removeManagedRuntime, listManagedRuntimes, listRuntimeDevices, verifyRuntimeExecutable, defaultRuntimeSpec, extractArchive, resolveRuntimeVariant, serverExeName, supportedVariants, DEFAULT_LLAMA_BUILD, listRuntimeReleases, latestRuntimeBuild, resolveLatestBuildOrPin, MissingAssetError, } from "./managed.js";
 /** Every runtime available on this machine, managed first then LM Studio. */
 export function listAllRuntimes(env = process.env) {

package/dist/runtime/model-server-driver.d.ts

@@ -0,0 +1,42 @@
+import type { Calibration, Profile } from "../config/schema.js";
+import type { BrainPaths } from "../config/paths.js";
+import type { Model, Runtime } from "../types.js";
+export interface ModelServerLaunch {
+    executable: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    command: string;
+    readinessPath: string;
+    propertiesPath: string | null;
+    formatLogLine(line: string): string;
+}
+export interface ModelServerDriverLaunchInput {
+    runtime: Runtime;
+    model: Model;
+    profile: Profile;
+    calibration: Calibration | null;
+    paths: BrainPaths;
+    host: string;
+    port: number;
+    logVerbosity: number;
+}
+/**
+ * Driver mechanics live here; the host owns process supervision, security,
+ * scheduler admission, status events, and the stable public endpoint.
+ */
+export interface ModelServerRuntimeDriver {
+    readonly id: string;
+    readonly displayName: string;
+    /** Native process name for engine-originated diagnostics. */
+    readonly processName: string;
+    describeProcessExit(input: {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }): string;
+    describeLaunchError(error: Error): string;
+    createLaunch(input: ModelServerDriverLaunchInput): ModelServerLaunch;
+}
+/** The first driver preserves the existing managed llama.cpp launch exactly. */
+export declare const llamaCppRuntimeDriver: ModelServerRuntimeDriver;
+//# sourceMappingURL=model-server-driver.d.ts.map

package/dist/runtime/model-server-driver.js

@@ -0,0 +1,50 @@
+/**
+ * The narrow, observed seam between the Brain host and a model-server engine.
+ *
+ * This intentionally starts with launch and introspection only. A method joins
+ * this contract when the common host needs the behavior from more than one
+ * driver; naming every current llama.cpp flag as a generic operation would
+ * create a false lowest common denominator before a second engine exists.
+ */
+import path from "node:path";
+import { mkdirSync } from "node:fs";
+import { buildArgs, buildEnv, formatCommand } from "./args.js";
+import { formatLlamaServerLog } from "../service/log-format.js";
+/** The first driver preserves the existing managed llama.cpp launch exactly. */
+export const llamaCppRuntimeDriver = {
+    id: "llama.cpp",
+    displayName: "llama.cpp",
+    processName: "llama-server",
+    describeProcessExit({ code, signal }) {
+        // 3221225781 == 0xC0000135 STATUS_DLL_NOT_FOUND: the vendor DLL trap.
+        const hint = code === 3221225781 ? " (missing runtime DLLs - the vendor directory was not on PATH)" : "";
+        return `llama-server exited with code ${code}${signal ? ` signal ${signal}` : ""}${hint}`;
+    },
+    describeLaunchError(error) {
+        return `could not launch llama-server: ${error.message}`;
+    },
+    createLaunch({ runtime, model, profile, calibration, paths, host, port, logVerbosity }) {
+        // llama.cpp enables scheduler-required slot erasure only when this existing
+        // directory is passed at launch. Failure to create it preserves the old
+        // behavior rather than making model startup fail for a cleanup feature.
+        const slotSavePath = path.join(paths.root, "slot-saves");
+        try {
+            mkdirSync(slotSavePath, { recursive: true });
+        }
+        catch {
+            /* launch without native slot actions */
+        }
+        const args = buildArgs({ ...profile, modelPath: model.modelPath, mmprojPath: model.mmprojPath }, { port, host, logVerbosity, slotSavePath }, model, calibration);
+        return {
+            executable: runtime.exe,
+            args,
+            cwd: runtime.dir,
+            env: buildEnv(runtime),
+            command: formatCommand(runtime, args),
+            readinessPath: "/health",
+            propertiesPath: "/props",
+            formatLogLine: formatLlamaServerLog,
+        };
+    },
+};
+//# sourceMappingURL=model-server-driver.js.map

package/dist/service/supervisor.d.ts

@@ -1,5 +1,6 @@
 import { type ChildProcess } from "node:child_process";
 import { EventEmitter } from "node:events";
+import { type ModelServerLaunch, type ModelServerRuntimeDriver } from "../runtime/index.js";
 import { type BrainPaths } from "../config/paths.js";
 import type { Model, Runtime } from "../types.js";
 import type { Profile, ProfilesStore } from "../config/schema.js";
@@ -18,6 +19,8 @@ export declare const DEFAULT_INTERNAL_PORT = 20800;
 export type SupervisorState = "stopped" | "starting" | "ready" | "failed" | "stopping";
 export interface SupervisorOptions {
     runtime: Runtime | null;
+    /** Native launch/introspection mechanics; lifecycle policy stays in this host. */
+    driver?: ModelServerRuntimeDriver;
     internalPort?: number;
     host?: string;
     logVerbosity?: number;
@@ -44,7 +47,7 @@ export interface SupervisorStatus {
     runtime: string;
 }
 /**
- * Owns the llama-server child process.
+ * Owns the model-server child process.
  *
  * The server always listens on a private port; `router.js` fronts it on a
  * stable one so switching models never asks a client to reconnect elsewhere.
@@ -58,6 +61,7 @@ export declare class Supervisor extends EventEmitter {
     readyTimeoutMs: number;
     paths: BrainPaths;
     getProfilesStore: () => ProfilesStore;
+    driver: ModelServerRuntimeDriver;
     state: SupervisorState;
     child: ChildProcess | null;
     model: Model | null;
@@ -75,10 +79,11 @@ export declare class Supervisor extends EventEmitter {
      * shell line is for reading, not for re-parsing.
      */
     args: string[] | null;
-    constructor({ runtime, internalPort, host, logVerbosity, readyTimeoutMs, paths, getProfilesStore, }: SupervisorOptions);
+    launch: ModelServerLaunch | null;
+    constructor({ runtime, driver, internalPort, host, logVerbosity, readyTimeoutMs, paths, getProfilesStore, }: SupervisorOptions);
     get upstreamBase(): string;
     /**
-     * Add a host-operation event to the same in-process tail as llama-server output.
+     * Add a host-operation event to the same in-process tail as model-server output.
      *
      * Calibrate, sweep, and benchmark deliberately reuse this supervisor rather
      * than creating invisible sidecar servers. Their lifecycle markers belong in
@@ -89,9 +94,9 @@ export declare class Supervisor extends EventEmitter {
     /**
      * Start (or restart) the server for a model + profile.
      *
-     * This is the sole llama-server launch boundary, so it materializes the
-     * selected hosting profile here. Keeping it beside `buildArgs()` makes the
-     * Jinja template and router-visible system addendum mandatory for every
+     * This is the sole model-server launch boundary, so it materializes the
+     * selected hosting profile here. Keeping it at this one driver call makes
+     * the Jinja template and router-visible system addendum mandatory for every
      * caller, including future maintenance operations that start a sidecar.
      */
     start(model: Model, profile: Profile): Promise<this>;

package/dist/service/supervisor.js

@@ -5,17 +5,15 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 };
 var _Supervisor_instances, _Supervisor_setState, _Supervisor_log, _Supervisor_health;
 import http from "node:http";
-import path from "node:path";
-import { mkdirSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { EventEmitter } from "node:events";
-import { buildArgs, buildEnv, formatCommand } from "../runtime/index.js";
+import { llamaCppRuntimeDriver, } from "../runtime/index.js";
 import { resolveHostingProfileForLaunch } from "../config/hosting-profiles.js";
 import { getCalibrationForBudget } from "../config/profiles.js";
 import { resolveBrainPaths } from "../config/paths.js";
 import { loadProfilesStore } from "../config/store.js";
 import { usedBytes } from "../gpu.js";
-import { formatBrainLog, formatLlamaServerLog } from "./log-format.js";
+import { formatBrainLog } from "./log-format.js";
 const LOG_LINES_KEPT = 10000;
 /**
  * Default loopback port for the private llama-server child. Deliberately clear
@@ -29,16 +27,17 @@ const LOG_LINES_KEPT = 10000;
  */
 export const DEFAULT_INTERNAL_PORT = 20800;
 /**
- * Owns the llama-server child process.
+ * Owns the model-server child process.
  *
  * The server always listens on a private port; `router.js` fronts it on a
  * stable one so switching models never asks a client to reconnect elsewhere.
  */
 export class Supervisor extends EventEmitter {
-    constructor({ runtime, internalPort = DEFAULT_INTERNAL_PORT, host = "127.0.0.1", logVerbosity = 3, readyTimeoutMs = 300000, paths = resolveBrainPaths(), getProfilesStore = loadProfilesStore, }) {
+    constructor({ runtime, driver = llamaCppRuntimeDriver, internalPort = DEFAULT_INTERNAL_PORT, host = "127.0.0.1", logVerbosity = 3, readyTimeoutMs = 300000, paths = resolveBrainPaths(), getProfilesStore = loadProfilesStore, }) {
         super();
         _Supervisor_instances.add(this);
         this.runtime = runtime;
+        this.driver = driver;
         this.internalPort = internalPort;
         this.host = host;
         this.logVerbosity = logVerbosity;
@@ -57,12 +56,13 @@ export class Supervisor extends EventEmitter {
         this.vramBaselineBytes = null;
         this.command = null;
         this.args = null;
+        this.launch = null;
     }
     get upstreamBase() {
         return `http://${this.host}:${this.internalPort}`;
     }
     /**
-     * Add a host-operation event to the same in-process tail as llama-server output.
+     * Add a host-operation event to the same in-process tail as model-server output.
      *
      * Calibrate, sweep, and benchmark deliberately reuse this supervisor rather
      * than creating invisible sidecar servers. Their lifecycle markers belong in
@@ -75,61 +75,53 @@ export class Supervisor extends EventEmitter {
     /**
      * Start (or restart) the server for a model + profile.
      *
-     * This is the sole llama-server launch boundary, so it materializes the
-     * selected hosting profile here. Keeping it beside `buildArgs()` makes the
-     * Jinja template and router-visible system addendum mandatory for every
+     * This is the sole model-server launch boundary, so it materializes the
+     * selected hosting profile here. Keeping it at this one driver call makes
+     * the Jinja template and router-visible system addendum mandatory for every
      * caller, including future maintenance operations that start a sidecar.
      */
     async start(model, profile) {
         await this.stop();
         if (!this.runtime) {
-            this.lastError = "no llama.cpp runtime available";
+            this.lastError = `no ${this.driver.displayName} runtime available`;
             __classPrivateFieldGet(this, _Supervisor_instances, "m", _Supervisor_setState).call(this, "failed", this.lastError);
             throw new Error(this.lastError);
         }
         const runtime = this.runtime;
-        // The engine's slot save/erase directory, under the brain's home so it
-        // survives across model relaunches (the dir is persistent; the engine only
-        // ever uses it for the `action=erase` the scheduler issues on a handoff,
-        // which never writes a file). Created before the args are built because
-        // llama.cpp validates it exists at launch and throws otherwise.
-        const slotSavePath = path.join(this.paths.root, "slot-saves");
-        try {
-            mkdirSync(slotSavePath, { recursive: true });
-        }
-        catch {
-            /* the engine then starts without slot actions - the pre-fix behavior */
-        }
         const launchProfile = resolveHostingProfileForLaunch(this.paths, this.getProfilesStore(), profile, model.family);
         this.model = model;
         this.profile = launchProfile;
         this.lastError = null;
         this.vramBaselineBytes = await usedBytes();
         __classPrivateFieldGet(this, _Supervisor_instances, "m", _Supervisor_setState).call(this, "starting");
-        const args = buildArgs({ ...launchProfile, modelPath: model.modelPath, mmprojPath: model.mmprojPath }, {
-            port: this.internalPort,
+        const launch = this.driver.createLaunch({
+            runtime,
+            model,
+            profile: launchProfile,
+            // The prompt-cache budget is derived from measured KV bytes/token, so the
+            // launch boundary is where it has to be resolved - nothing downstream of
+            // here can reach the calibration store.
+            calibration: getCalibrationForBudget(this.getProfilesStore(), model, launchProfile),
+            paths: this.paths,
             host: this.host,
+            port: this.internalPort,
             logVerbosity: this.logVerbosity,
-            slotSavePath,
-        }, model, 
-        // The prompt-cache budget is derived from measured KV bytes/token, so the
-        // launch boundary is where it has to be resolved - nothing downstream of
-        // here can reach the calibration store.
-        getCalibrationForBudget(this.getProfilesStore(), model, launchProfile));
-        this.args = args;
-        this.command = formatCommand(runtime, args);
+        });
+        this.launch = launch;
+        this.args = launch.args;
+        this.command = launch.command;
         __classPrivateFieldGet(this, _Supervisor_instances, "m", _Supervisor_log).call(this, formatBrainLog("model", `launching: ${this.command}`));
         const started = Date.now();
-        this.child = spawn(runtime.exe, args, {
-            cwd: runtime.dir,
-            env: buildEnv(runtime),
+        this.child = spawn(launch.executable, launch.args, {
+            cwd: launch.cwd,
+            env: launch.env,
             windowsHide: true,
             stdio: ["ignore", "pipe", "pipe"],
         });
         const onChunk = (chunk) => {
             for (const line of String(chunk).split(/\r?\n/)) {
                 if (line.trim())
-                    __classPrivateFieldGet(this, _Supervisor_instances, "m", _Supervisor_log).call(this, formatLlamaServerLog(line.trim()));
+                    __classPrivateFieldGet(this, _Supervisor_instances, "m", _Supervisor_log).call(this, launch.formatLogLine(line.trim()));
             }
         };
         this.child.stdout?.on("data", onChunk);
@@ -143,15 +135,13 @@ export class Supervisor extends EventEmitter {
                 return;
             }
             exitedEarly = { code, signal };
-            // 3221225781 == 0xC0000135 STATUS_DLL_NOT_FOUND: the vendor DLL trap.
-            const hint = code === 3221225781 ? " (missing runtime DLLs - the vendor directory was not on PATH)" : "";
-            this.lastError = `llama-server exited with code ${code}${signal ? ` signal ${signal}` : ""}${hint}`;
+            this.lastError = this.driver.describeProcessExit({ code, signal });
             __classPrivateFieldGet(this, _Supervisor_instances, "m", _Supervisor_setState).call(this, "failed", this.lastError);
             if (wasReady)
                 this.emit("crashed", this.lastError);
         });
         this.child.once("error", (error) => {
-            this.lastError = `could not launch llama-server: ${error.message}`;
+            this.lastError = this.driver.describeLaunchError(error);
             __classPrivateFieldGet(this, _Supervisor_instances, "m", _Supervisor_setState).call(this, "failed", this.lastError);
         });
         // Poll /health until the model finishes loading.
@@ -164,7 +154,7 @@ export class Supervisor extends EventEmitter {
             const used = await usedBytes();
             if (used && used > peakVram)
                 peakVram = used;
-            const health = await __classPrivateFieldGet(this, _Supervisor_instances, "m", _Supervisor_health).call(this);
+            const health = await __classPrivateFieldGet(this, _Supervisor_instances, "m", _Supervisor_health).call(this, launch.readinessPath);
             if (health) {
                 this.loadSeconds = (Date.now() - started) / 1000;
                 this.startedAt = new Date();
@@ -185,8 +175,11 @@ export class Supervisor extends EventEmitter {
     }
     /** Fetch /props from the running server (modalities, template caps, defaults). */
     props() {
+        const pathname = this.launch?.propertiesPath;
+        if (!pathname)
+            return Promise.resolve(null);
         return new Promise((resolve) => {
-            const req = http.get({ host: this.host, port: this.internalPort, path: "/props", timeout: 5000 }, (res) => {
+            const req = http.get({ host: this.host, port: this.internalPort, path: pathname, timeout: 5000 }, (res) => {
                 let body = "";
                 res.on("data", (c) => (body += c));
                 res.on("end", () => {
@@ -263,9 +256,9 @@ _Supervisor_instances = new WeakSet(), _Supervisor_setState = function _Supervis
     if (this.logLines.length > LOG_LINES_KEPT)
         this.logLines.shift();
     this.emit("log", line);
-}, _Supervisor_health = function _Supervisor_health() {
+}, _Supervisor_health = function _Supervisor_health(pathname) {
     return new Promise((resolve) => {
-        const req = http.get({ host: this.host, port: this.internalPort, path: "/health", timeout: 2500 }, (res) => {
+        const req = http.get({ host: this.host, port: this.internalPort, path: pathname, timeout: 2500 }, (res) => {
             res.resume();
             resolve(res.statusCode === 200);
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@otto-code/brain",
-  "version": "0.8.18",
+  "version": "0.9.0",
   "description": "Otto Brain - self-contained host for local GGUF models, with measured VRAM budgeting and reasoning-budget control",
   "license": "AGPL-3.0-or-later",
   "bin": {