@otto-code/brain 0.8.2 → 0.8.4

package/dist/service/status-events.js

@@ -0,0 +1,256 @@
+/**
+ * The brain's authoritative status event source.
+ *
+ * The brain owns its own state, so it publishes it rather than being polled for
+ * it. One daemon subscribes over SSE (`GET /__host/events`) and fans the result
+ * out to every connected Otto client, replacing a per-client status poll that
+ * could never show a transition sooner than its own interval.
+ *
+ * Three properties this has to keep:
+ *
+ *  - **Complete snapshots, never deltas.** A reader that missed an event, or
+ *    reconnected after one, must not have to reconstruct anything: the newest
+ *    snapshot is the whole truth. That is what makes reconnect repair on both
+ *    sides idempotent.
+ *  - **Coalescing lives here, not in the reader.** A timer tick that finds
+ *    nothing changed emits nothing, and a completion's traffic counters are not
+ *    a state change. Otherwise "push" would just be a poll with extra steps, and
+ *    a busy brain would broadcast to every client for every token.
+ *  - **No work while nobody is listening.** The sampler only runs while a
+ *    subscriber is attached, so a brain the daemon never subscribed to (an older
+ *    daemon, or one that is not running) pays nothing.
+ *
+ * The snapshot itself is deliberately the *cheap* status: no `resources`, whose
+ * collection spawns `nvidia-smi`. That stays an opt-in pull for the Overview tab.
+ */
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _BrainStatusPublisher_instances, _BrainStatusPublisher_listeners, _BrainStatusPublisher_closers, _BrainStatusPublisher_sampleIntervalMs, _BrainStatusPublisher_source, _BrainStatusPublisher_timer, _BrainStatusPublisher_last, _BrainStatusPublisher_lastKey, _BrainStatusPublisher_sampling, _BrainStatusPublisher_resample, _BrainStatusPublisher_closed, _BrainStatusPublisher_sample, _BrainStatusPublisher_startTimer, _BrainStatusPublisher_stopTimer;
+/**
+ * How often the publisher resamples while at least one listener is attached.
+ *
+ * A sample is needed at all because two inputs have no event to hang off:
+ * `activity` is a file written by a *different* process (a `calibrate` or
+ * `pull` CLI run), and the slot phase split is a loopback read of
+ * llama-server's `/slots`. Everything else notifies directly. Sampling is not
+ * a heartbeat: an unchanged sample emits nothing.
+ */
+const DEFAULT_SAMPLE_INTERVAL_MS = 250;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * The fields whose change is worth waking every connected client for.
+ *
+ * Everything omitted here still rides in the payload; it just cannot *trigger*
+ * a payload on its own. The omissions are the churning ones:
+ *
+ *  - `telemetry` totals and `recent` advance on every completion.
+ *  - `logLineCount` advances on every llama-server log line.
+ *  - `slots.contexts` is capacity detail that changes independently of work.
+ *
+ * `slots.threads` is intentionally included. It is sampled at a bounded 4 Hz,
+ * not notified per model token, so it gives the Overview live counts and rates
+ * without turning a fast model into a token-rate broadcast.
+ *
+ * `telemetry.warning` is kept: the reasoning-only advice is a state the UI
+ * shows, not a counter.
+ */
+export function statusChangeKey(snapshot) {
+    const scheduler = isRecord(snapshot.scheduler) ? snapshot.scheduler : null;
+    const telemetry = isRecord(snapshot.telemetry) ? snapshot.telemetry : null;
+    const slots = isRecord(snapshot.slots) ? snapshot.slots : null;
+    return JSON.stringify({
+        version: snapshot.version ?? null,
+        apiVersion: snapshot.apiVersion ?? null,
+        state: snapshot.state ?? null,
+        model: snapshot.model ?? null,
+        modelId: snapshot.modelId ?? null,
+        pid: snapshot.pid ?? null,
+        vramBytes: snapshot.vramBytes ?? null,
+        loadSeconds: snapshot.loadSeconds ?? null,
+        startedAt: snapshot.startedAt ?? null,
+        lastError: snapshot.lastError ?? null,
+        upstream: snapshot.upstream ?? null,
+        runtime: snapshot.runtime ?? null,
+        capabilities: snapshot.capabilities ?? null,
+        activity: snapshot.activity ?? null,
+        reasoning: snapshot.reasoning ?? null,
+        inference: snapshot.inference ?? null,
+        queued: snapshot.queued ?? null,
+        schedulerWaiting: scheduler?.waiting ?? null,
+        schedulerLastTurn: scheduler?.lastTurn ?? null,
+        warning: telemetry?.warning ?? null,
+        slots: slots
+            ? {
+                total: slots.total ?? null,
+                busy: slots.busy ?? null,
+                idle: slots.idle ?? null,
+                prefill: slots.prefill ?? null,
+                decode: slots.decode ?? null,
+                threads: slots.threads ?? null,
+            }
+            : null,
+    });
+}
+/**
+ * Owns the current snapshot and decides when it changed.
+ *
+ * Constructed before the router (so `serve.ts` can hand the same instance to
+ * both the router and the management API) and inert until the router installs
+ * the snapshot source with {@link setSource}. `/__host/capabilities` advertises
+ * `events` only once it is {@link ready}, so a brain can never claim a stream it
+ * cannot actually serve.
+ */
+export class BrainStatusPublisher {
+    constructor(options = {}) {
+        _BrainStatusPublisher_instances.add(this);
+        _BrainStatusPublisher_listeners.set(this, new Set());
+        /** Per-subscription teardown, so `close()` can end the responses it feeds. */
+        _BrainStatusPublisher_closers.set(this, new Set());
+        _BrainStatusPublisher_sampleIntervalMs.set(this, void 0);
+        _BrainStatusPublisher_source.set(this, null);
+        _BrainStatusPublisher_timer.set(this, null);
+        /** The last snapshot that was actually emitted, replayed to a late subscriber. */
+        _BrainStatusPublisher_last.set(this, null);
+        _BrainStatusPublisher_lastKey.set(this, null);
+        /** True while a sample is in flight, so overlapping triggers collapse into one. */
+        _BrainStatusPublisher_sampling.set(this, false);
+        /** A trigger that arrived mid-sample; runs exactly one more sample afterwards. */
+        _BrainStatusPublisher_resample.set(this, false);
+        _BrainStatusPublisher_closed.set(this, false);
+        __classPrivateFieldSet(this, _BrainStatusPublisher_sampleIntervalMs, options.sampleIntervalMs ?? DEFAULT_SAMPLE_INTERVAL_MS, "f");
+    }
+    /** Whether a snapshot source has been installed - i.e. events can be served. */
+    get ready() {
+        return __classPrivateFieldGet(this, _BrainStatusPublisher_source, "f") !== null && !__classPrivateFieldGet(this, _BrainStatusPublisher_closed, "f");
+    }
+    get listenerCount() {
+        return __classPrivateFieldGet(this, _BrainStatusPublisher_listeners, "f").size;
+    }
+    /** Install the snapshot builder. Called once, by the router. */
+    setSource(source) {
+        __classPrivateFieldSet(this, _BrainStatusPublisher_source, source, "f");
+    }
+    /**
+     * Attach a listener. It receives the current snapshot immediately when one is
+     * known, and a fresh sample is taken right away so a subscriber that arrives
+     * during a transition is not handed a stale first frame.
+     */
+    subscribe(listener, onClose) {
+        if (__classPrivateFieldGet(this, _BrainStatusPublisher_closed, "f")) {
+            onClose?.();
+            return () => { };
+        }
+        __classPrivateFieldGet(this, _BrainStatusPublisher_listeners, "f").add(listener);
+        if (onClose)
+            __classPrivateFieldGet(this, _BrainStatusPublisher_closers, "f").add(onClose);
+        if (__classPrivateFieldGet(this, _BrainStatusPublisher_last, "f"))
+            listener(__classPrivateFieldGet(this, _BrainStatusPublisher_last, "f"));
+        __classPrivateFieldGet(this, _BrainStatusPublisher_instances, "m", _BrainStatusPublisher_startTimer).call(this);
+        this.notify();
+        return () => {
+            __classPrivateFieldGet(this, _BrainStatusPublisher_listeners, "f").delete(listener);
+            if (onClose)
+                __classPrivateFieldGet(this, _BrainStatusPublisher_closers, "f").delete(onClose);
+            if (__classPrivateFieldGet(this, _BrainStatusPublisher_listeners, "f").size === 0)
+                __classPrivateFieldGet(this, _BrainStatusPublisher_instances, "m", _BrainStatusPublisher_stopTimer).call(this);
+        };
+    }
+    /**
+     * Something authoritative changed - resample now rather than at the next tick.
+     * Cheap to over-call: an unchanged snapshot emits nothing.
+     */
+    notify() {
+        if (__classPrivateFieldGet(this, _BrainStatusPublisher_closed, "f") || __classPrivateFieldGet(this, _BrainStatusPublisher_listeners, "f").size === 0)
+            return;
+        void __classPrivateFieldGet(this, _BrainStatusPublisher_instances, "m", _BrainStatusPublisher_sample).call(this);
+    }
+    /**
+     * Drop every listener and end the streams behind them.
+     *
+     * Ending them is not optional at shutdown: an open SSE response is an open
+     * connection, and `server.close()` waits for those, so a brain that only
+     * unsubscribed would hang on stop until its daemon happened to disconnect.
+     */
+    close() {
+        if (__classPrivateFieldGet(this, _BrainStatusPublisher_closed, "f"))
+            return;
+        __classPrivateFieldSet(this, _BrainStatusPublisher_closed, true, "f");
+        __classPrivateFieldGet(this, _BrainStatusPublisher_instances, "m", _BrainStatusPublisher_stopTimer).call(this);
+        __classPrivateFieldGet(this, _BrainStatusPublisher_listeners, "f").clear();
+        const closers = [...__classPrivateFieldGet(this, _BrainStatusPublisher_closers, "f")];
+        __classPrivateFieldGet(this, _BrainStatusPublisher_closers, "f").clear();
+        for (const onClose of closers) {
+            try {
+                onClose();
+            }
+            catch {
+                // Shutdown must not be blocked by one stream failing to end.
+            }
+        }
+    }
+}
+_BrainStatusPublisher_listeners = new WeakMap(), _BrainStatusPublisher_closers = new WeakMap(), _BrainStatusPublisher_sampleIntervalMs = new WeakMap(), _BrainStatusPublisher_source = new WeakMap(), _BrainStatusPublisher_timer = new WeakMap(), _BrainStatusPublisher_last = new WeakMap(), _BrainStatusPublisher_lastKey = new WeakMap(), _BrainStatusPublisher_sampling = new WeakMap(), _BrainStatusPublisher_resample = new WeakMap(), _BrainStatusPublisher_closed = new WeakMap(), _BrainStatusPublisher_instances = new WeakSet(), _BrainStatusPublisher_sample = async function _BrainStatusPublisher_sample() {
+    const source = __classPrivateFieldGet(this, _BrainStatusPublisher_source, "f");
+    if (!source || __classPrivateFieldGet(this, _BrainStatusPublisher_closed, "f"))
+        return;
+    if (__classPrivateFieldGet(this, _BrainStatusPublisher_sampling, "f")) {
+        __classPrivateFieldSet(this, _BrainStatusPublisher_resample, true, "f");
+        return;
+    }
+    __classPrivateFieldSet(this, _BrainStatusPublisher_sampling, true, "f");
+    try {
+        const snapshot = await source();
+        if (__classPrivateFieldGet(this, _BrainStatusPublisher_closed, "f"))
+            return;
+        const key = statusChangeKey(snapshot);
+        // Always keep the newest body for replay, even when nothing significant
+        // changed: a late subscriber should not get last minute's counters.
+        __classPrivateFieldSet(this, _BrainStatusPublisher_last, snapshot, "f");
+        if (key === __classPrivateFieldGet(this, _BrainStatusPublisher_lastKey, "f"))
+            return;
+        __classPrivateFieldSet(this, _BrainStatusPublisher_lastKey, key, "f");
+        // Set iteration tolerates a listener unsubscribing mid-emit, which the
+        // SSE teardown does when a daemon disconnects during a snapshot.
+        for (const listener of __classPrivateFieldGet(this, _BrainStatusPublisher_listeners, "f")) {
+            try {
+                listener(snapshot);
+            }
+            catch {
+                // A broken listener is that listener's problem; the others still get it.
+            }
+        }
+    }
+    catch {
+        // A failed sample is not a state change. The next tick tries again.
+    }
+    finally {
+        __classPrivateFieldSet(this, _BrainStatusPublisher_sampling, false, "f");
+        if (__classPrivateFieldGet(this, _BrainStatusPublisher_resample, "f")) {
+            __classPrivateFieldSet(this, _BrainStatusPublisher_resample, false, "f");
+            void __classPrivateFieldGet(this, _BrainStatusPublisher_instances, "m", _BrainStatusPublisher_sample).call(this);
+        }
+    }
+}, _BrainStatusPublisher_startTimer = function _BrainStatusPublisher_startTimer() {
+    if (__classPrivateFieldGet(this, _BrainStatusPublisher_timer, "f") || __classPrivateFieldGet(this, _BrainStatusPublisher_closed, "f"))
+        return;
+    __classPrivateFieldSet(this, _BrainStatusPublisher_timer, setInterval(() => this.notify(), __classPrivateFieldGet(this, _BrainStatusPublisher_sampleIntervalMs, "f")), "f");
+    // Never hold the process open for status reporting alone.
+    __classPrivateFieldGet(this, _BrainStatusPublisher_timer, "f").unref?.();
+}, _BrainStatusPublisher_stopTimer = function _BrainStatusPublisher_stopTimer() {
+    if (!__classPrivateFieldGet(this, _BrainStatusPublisher_timer, "f"))
+        return;
+    clearInterval(__classPrivateFieldGet(this, _BrainStatusPublisher_timer, "f"));
+    __classPrivateFieldSet(this, _BrainStatusPublisher_timer, null, "f");
+};
+//# sourceMappingURL=status-events.js.map

package/dist/service/supervisor.d.ts

@@ -15,7 +15,7 @@ import type { Profile } from "../config/schema.js";
 export declare const DEFAULT_INTERNAL_PORT = 20800;
 export type SupervisorState = "stopped" | "starting" | "ready" | "failed" | "stopping";
 export interface SupervisorOptions {
-    runtime: Runtime;
+    runtime: Runtime | null;
     internalPort?: number;
     host?: string;
     readyTimeoutMs?: number;
@@ -40,7 +40,7 @@ export interface SupervisorStatus {
  */
 export declare class Supervisor extends EventEmitter {
     #private;
-    runtime: Runtime;
+    runtime: Runtime | null;
     internalPort: number;
     host: string;
     readyTimeoutMs: number;

package/dist/service/supervisor.js

@@ -54,6 +54,12 @@ export class Supervisor extends EventEmitter {
     /** Start (or restart) the server for a model + profile. */
     async start(model, profile) {
         await this.stop();
+        if (!this.runtime) {
+            this.lastError = "no llama.cpp runtime available";
+            __classPrivateFieldGet(this, _Supervisor_instances, "m", _Supervisor_setState).call(this, "failed", this.lastError);
+            throw new Error(this.lastError);
+        }
+        const runtime = this.runtime;
         this.model = model;
         this.profile = profile;
         this.lastError = null;
@@ -62,12 +68,12 @@ export class Supervisor extends EventEmitter {
         __classPrivateFieldGet(this, _Supervisor_instances, "m", _Supervisor_setState).call(this, "starting");
         const args = buildArgs({ ...profile, modelPath: model.modelPath, mmprojPath: model.mmprojPath }, { port: this.internalPort, host: this.host });
         this.args = args;
-        this.command = formatCommand(this.runtime, args);
+        this.command = formatCommand(runtime, args);
         __classPrivateFieldGet(this, _Supervisor_instances, "m", _Supervisor_log).call(this, `launching: ${this.command}`);
         const started = Date.now();
-        this.child = spawn(this.runtime.exe, args, {
-            cwd: this.runtime.dir,
-            env: buildEnv(this.runtime),
+        this.child = spawn(runtime.exe, args, {
+            cwd: runtime.dir,
+            env: buildEnv(runtime),
             windowsHide: true,
             stdio: ["ignore", "pipe", "pipe"],
         });
@@ -194,7 +200,7 @@ export class Supervisor extends EventEmitter {
             startedAt: this.startedAt ? this.startedAt.toISOString() : null,
             lastError: this.lastError,
             upstream: this.upstreamBase,
-            runtime: `${this.runtime.label} v${this.runtime.version}`,
+            runtime: this.runtime ? `${this.runtime.label} v${this.runtime.version}` : "not installed",
         };
     }
 }

package/dist/sysmon.d.ts

@@ -34,7 +34,7 @@ export interface SlotInfo {
     threads?: Array<{
         slot: number;
         phase: "prefill" | "decode";
-        promptTokens: number;
+        promptTokens: number | null;
         generatedTokens: number;
         promptTokensPerSecond: number | null;
         tokensPerSecond: number | null;

package/dist/sysmon.js

@@ -72,6 +72,22 @@ function decodedTokens(rec) {
         if (typeof value === "number" && Number.isFinite(value))
             return value;
     }
+    // Current llama.cpp nests the counter in `next_token`; some speculative
+    // builds expose an array there. Older Otto builds only read the top level,
+    // which made every current slot look like decode with a made-up count of 1.
+    const nextToken = rec.next_token;
+    const records = Array.isArray(nextToken) ? nextToken : [nextToken];
+    let nested = null;
+    for (const value of records) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            continue;
+        const count = value.n_decoded;
+        if (typeof count === "number" && Number.isFinite(count)) {
+            nested = nested === null ? count : Math.max(nested, count);
+        }
+    }
+    if (nested !== null)
+        return nested;
     // No counter at all: report a non-zero so the slot lands in decode rather than
     // claiming a prefill that may never have been happening.
     return 1;
@@ -110,21 +126,40 @@ export class SlotActivityTracker {
         _SlotActivityTracker_previous.set(this, new Map());
     }
     sample(rows, now = Date.now()) {
-        const threads = rows.flatMap((row, slot) => {
+        const threads = rows.flatMap((row, index) => {
             const record = row;
+            const id = record.id;
+            const slot = typeof id === "number" && Number.isFinite(id) ? id : index;
             if (!isProcessing(record)) {
                 __classPrivateFieldGet(this, _SlotActivityTracker_previous, "f").delete(slot);
                 return [];
             }
-            const promptTokens = counter(record, ["n_past", "n_prompt_tokens_processed"]);
+            const promptTokens = optionalCounter(record, ["n_past", "n_prompt_tokens_processed"]);
             const generatedTokens = decodedTokens(record);
-            const phase = generatedTokens === 0 ? "prefill" : "decode";
-            const previous = __classPrivateFieldGet(this, _SlotActivityTracker_previous, "f").get(slot);
+            const task = typeof record.id_task === "string" || typeof record.id_task === "number"
+                ? record.id_task
+                : null;
+            // A reused slot starts a new measurement window. Comparing the new
+            // request's counters with the old request is how negative or absurd TPS
+            // flashes appeared at action boundaries.
+            const candidate = __classPrivateFieldGet(this, _SlotActivityTracker_previous, "f").get(slot);
+            const previous = candidate?.task === task ? candidate : undefined;
+            // llama-server may leave the previous request's decoded counter visible
+            // during the first snapshot of a newly assigned task. The task boundary
+            // is authoritative in that case; otherwise a prompt is shown as decode
+            // and prompt throughput is incorrectly reported as zero.
+            const phase = candidate !== undefined && candidate.task !== task
+                ? "prefill"
+                : previous?.phase === "prefill" && generatedTokens <= previous.generatedTokens
+                    ? "prefill"
+                    : generatedTokens === 0
+                        ? "prefill"
+                        : "decode";
             const elapsedSeconds = previous ? (now - previous.at) / 1000 : 0;
-            const rate = (current, before) => elapsedSeconds > 0 && before !== undefined && current >= before
+            const rate = (current, before) => current !== null && elapsedSeconds > 0 && before != null && current >= before
                 ? (current - before) / elapsedSeconds
                 : null;
-            __classPrivateFieldGet(this, _SlotActivityTracker_previous, "f").set(slot, { at: now, promptTokens, generatedTokens });
+            __classPrivateFieldGet(this, _SlotActivityTracker_previous, "f").set(slot, { at: now, task, promptTokens, generatedTokens, phase });
             return [
                 {
                     slot,
@@ -140,13 +175,13 @@ export class SlotActivityTracker {
     }
 }
 _SlotActivityTracker_previous = new WeakMap();
-function counter(record, keys) {
+function optionalCounter(record, keys) {
     for (const key of keys) {
         const value = record[key];
         if (typeof value === "number" && Number.isFinite(value))
             return value;
     }
-    return 0;
+    return null;
 }
 const slotActivityTracker = new SlotActivityTracker();
 /** Slot occupancy from the running server. */

package/dist/types.d.ts

@@ -49,6 +49,8 @@ export interface Model {
     tier?: string;
     /** Whether the catalog marks this as a thinking/reasoning model. */
     thinking?: boolean;
+    /** Per-request reasoning levels accepted by the model's OpenAI-compatible API. */
+    reasoningEfforts?: string[];
     /** The catalog's advertised max context, if known. */
     contextMax?: number;
     /** Back-reference: the id of the reconciled catalog entry, if matched. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@otto-code/brain",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "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": {
@@ -50,7 +50,7 @@
   "devDependencies": {
     "@types/node": "^20.9.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.6"
+    "vitest": "^4.1.10"
   },
   "engines": {
     "node": ">=20.6.0"