@otto-code/brain 0.7.5 → 0.8.0

package/dist/service/activity.d.ts

@@ -0,0 +1,83 @@
+/** The long-running ops worth reporting. Anything else is not worth a state. */
+export type BrainActivityKind = "calibrate" | "sweep" | "benchmark" | "download" | "scan";
+export interface BrainActivityRecord {
+    kind: BrainActivityKind;
+    /** The process running the op, so a crashed op does not pin the status. */
+    pid: number;
+    /** What it is working on - a model id, usually. Shown in the tooltip. */
+    target: string | null;
+    /** Completion in [0,1], for ops that can measure it. Null when they cannot. */
+    progress: number | null;
+    startedAt: string;
+}
+export interface BrainActivityHandle {
+    /** Publish progress. Throttled: this is a disk write on a hot loop otherwise. */
+    update(progress: number | null): void;
+    /** Clear the record. Safe to call more than once. */
+    end(): void;
+}
+/**
+ * Announce that this process has started a long-running op.
+ *
+ * Deliberately last-writer-wins rather than refusing when a record already
+ * exists: two ops at once is a real (if unwise) thing to do, the newer one is
+ * the more interesting answer, and a failed announce must never be a reason for
+ * the op itself to fail.
+ */
+export declare function beginActivity(kind: BrainActivityKind, options?: {
+    target?: string | null;
+    env?: NodeJS.ProcessEnv;
+}): BrainActivityHandle;
+/**
+ * The op currently owning the host, or null.
+ *
+ * Clears the record as a side effect when the process behind it is gone, so a
+ * killed op self-heals on the next status poll rather than needing a restart.
+ */
+export declare function readActivity(env?: NodeJS.ProcessEnv): BrainActivityRecord | null;
+export declare function clearActivity(env?: NodeJS.ProcessEnv): void;
+/**
+ * Run `fn` with the op announced, clearing the record however it finishes.
+ *
+ * The announce is never allowed to break the op: this is status reporting, and
+ * a read-only home directory is not a reason for a benchmark to fail.
+ */
+export declare function withActivity<T>(kind: BrainActivityKind, options: {
+    target?: string | null;
+    env?: NodeJS.ProcessEnv;
+}, fn: (handle: BrainActivityHandle) => Promise<T>): Promise<T>;
+/**
+ * Whether a streamed chunk carries reasoning, and whether it carries content.
+ *
+ * These are the router's own predicates, lifted out so the live flag and the
+ * end-of-stream `reasoning-only` verdict cannot drift apart. They are
+ * deliberately crude substring tests over the raw SSE bytes: the brain proxies
+ * both the Anthropic and the OpenAI shapes, chunk boundaries fall wherever the
+ * network puts them, and parsing partial JSON per chunk on the hot proxy path
+ * would cost more than the signal is worth.
+ */
+export declare function chunkHasReasoning(text: string): boolean;
+export declare function chunkHasContent(text: string): boolean;
+/**
+ * Which in-flight completions are currently mid-thought.
+ *
+ * A request counts as thinking once reasoning has gone past and before any
+ * content has: that is the window where the model is working and the user has
+ * nothing to read yet, which is exactly what the rail's "thinking" state is
+ * claiming. The moment content starts the request is generating instead, even
+ * if more reasoning follows - a stream that is producing readable output should
+ * not report as though it were still silent.
+ *
+ * A set rather than a boolean because llama-server runs several slots at once,
+ * and one request finishing its thought must not clear the flag for another.
+ */
+export declare class ReasoningTracker {
+    #private;
+    /** Note a chunk of `requestId`'s stream. Cheap enough to call per chunk. */
+    observe(requestId: string, text: string): void;
+    /** Forget the request. Must be called on end *and* on error, or the flag sticks. */
+    end(requestId: string): void;
+    get active(): boolean;
+    get count(): number;
+}
+//# sourceMappingURL=activity.d.ts.map

package/dist/service/activity.js

@@ -0,0 +1,216 @@
+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 _ReasoningTracker_reasoning, _ReasoningTracker_content;
+/**
+ * What long-running work currently owns the brain, and whether the loaded model
+ * is mid-reasoning.
+ *
+ * Two trackers with deliberately different lifetimes:
+ *
+ * - **Ops** (`calibrate`, `sweep`, `benchmark`, `pull`, `scan`) run in their own
+ *   CLI process. The service answering `/__host/status` is a different process
+ *   and cannot see them, so the op announces itself through a small file under
+ *   `$OTTO_HOME/otto-brain/`, the same way `pid-lock.ts` publishes the service
+ *   itself. Staleness is decided by probing the recorded pid: a `calibrate` that
+ *   was killed with Ctrl-C never gets to clean up after itself, and a status
+ *   that stays stuck on "calibrating" forever is worse than no status at all.
+ *
+ * - **Reasoning** is per-request and lives only as long as the stream does, so
+ *   it is plain in-process state on the router. It never touches disk.
+ *
+ * Both feed the one `activity` field on the host status, which the client turns
+ * into the Brain rail's icon.
+ */
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { resolveBrainPaths } from "../config/paths.js";
+import { writePrivateFileAtomicSync } from "../config/private-files.js";
+import { isProcessAlive } from "./pid-lock.js";
+const ACTIVITY_KINDS = new Set(["calibrate", "sweep", "benchmark", "download", "scan"]);
+/** How often progress may reach the disk. */
+const PROGRESS_WRITE_INTERVAL_MS = 1000;
+/**
+ * Announce that this process has started a long-running op.
+ *
+ * Deliberately last-writer-wins rather than refusing when a record already
+ * exists: two ops at once is a real (if unwise) thing to do, the newer one is
+ * the more interesting answer, and a failed announce must never be a reason for
+ * the op itself to fail.
+ */
+export function beginActivity(kind, options = {}) {
+    const env = options.env ?? process.env;
+    const record = {
+        kind,
+        pid: process.pid,
+        target: options.target ?? null,
+        progress: null,
+        startedAt: new Date().toISOString(),
+    };
+    writeActivity(record, env);
+    let lastWriteMs = Date.now();
+    let ended = false;
+    return {
+        update(progress) {
+            if (ended)
+                return;
+            const now = Date.now();
+            if (now - lastWriteMs < PROGRESS_WRITE_INTERVAL_MS)
+                return;
+            lastWriteMs = now;
+            record.progress = clampProgress(progress);
+            writeActivity(record, env);
+        },
+        end() {
+            if (ended)
+                return;
+            ended = true;
+            // Only clear a record this process owns. An op that outlived us - or a
+            // newer one that overwrote ours - must keep reporting.
+            const current = readActivityFile(env);
+            if (current && current.pid !== process.pid)
+                return;
+            clearActivity(env);
+        },
+    };
+}
+/**
+ * The op currently owning the host, or null.
+ *
+ * Clears the record as a side effect when the process behind it is gone, so a
+ * killed op self-heals on the next status poll rather than needing a restart.
+ */
+export function readActivity(env = process.env) {
+    const record = readActivityFile(env);
+    if (!record)
+        return null;
+    if (!isProcessAlive(record.pid)) {
+        clearActivity(env);
+        return null;
+    }
+    return record;
+}
+export function clearActivity(env = process.env) {
+    const { activityFile } = resolveBrainPaths(env);
+    rmSync(activityFile, { force: true });
+}
+/**
+ * Run `fn` with the op announced, clearing the record however it finishes.
+ *
+ * The announce is never allowed to break the op: this is status reporting, and
+ * a read-only home directory is not a reason for a benchmark to fail.
+ */
+export async function withActivity(kind, options, fn) {
+    let handle;
+    try {
+        handle = beginActivity(kind, options);
+    }
+    catch {
+        handle = { update() { }, end() { } };
+    }
+    try {
+        return await fn(handle);
+    }
+    finally {
+        try {
+            handle.end();
+        }
+        catch {
+            // Ignore: see above.
+        }
+    }
+}
+function writeActivity(record, env) {
+    const { activityFile } = resolveBrainPaths(env);
+    writePrivateFileAtomicSync(activityFile, `${JSON.stringify(record, null, 2)}\n`);
+}
+function readActivityFile(env) {
+    const { activityFile } = resolveBrainPaths(env);
+    if (!existsSync(activityFile))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(activityFile, "utf8"));
+        if (!isActivityKind(parsed.kind) || typeof parsed.pid !== "number")
+            return null;
+        return {
+            kind: parsed.kind,
+            pid: parsed.pid,
+            target: typeof parsed.target === "string" ? parsed.target : null,
+            progress: clampProgress(parsed.progress ?? null),
+            startedAt: typeof parsed.startedAt === "string" ? parsed.startedAt : new Date().toISOString(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isActivityKind(value) {
+    return typeof value === "string" && ACTIVITY_KINDS.has(value);
+}
+function clampProgress(progress) {
+    if (typeof progress !== "number" || !Number.isFinite(progress))
+        return null;
+    return Math.min(1, Math.max(0, progress));
+}
+/**
+ * Whether a streamed chunk carries reasoning, and whether it carries content.
+ *
+ * These are the router's own predicates, lifted out so the live flag and the
+ * end-of-stream `reasoning-only` verdict cannot drift apart. They are
+ * deliberately crude substring tests over the raw SSE bytes: the brain proxies
+ * both the Anthropic and the OpenAI shapes, chunk boundaries fall wherever the
+ * network puts them, and parsing partial JSON per chunk on the hot proxy path
+ * would cost more than the signal is worth.
+ */
+export function chunkHasReasoning(text) {
+    return text.includes("thinking") || text.includes("reasoning");
+}
+export function chunkHasContent(text) {
+    return text.includes('"text_delta"') || /"content"\s*:\s*"[^"]/.test(text);
+}
+/**
+ * Which in-flight completions are currently mid-thought.
+ *
+ * A request counts as thinking once reasoning has gone past and before any
+ * content has: that is the window where the model is working and the user has
+ * nothing to read yet, which is exactly what the rail's "thinking" state is
+ * claiming. The moment content starts the request is generating instead, even
+ * if more reasoning follows - a stream that is producing readable output should
+ * not report as though it were still silent.
+ *
+ * A set rather than a boolean because llama-server runs several slots at once,
+ * and one request finishing its thought must not clear the flag for another.
+ */
+export class ReasoningTracker {
+    constructor() {
+        _ReasoningTracker_reasoning.set(this, new Set());
+        _ReasoningTracker_content.set(this, new Set());
+    }
+    /** Note a chunk of `requestId`'s stream. Cheap enough to call per chunk. */
+    observe(requestId, text) {
+        if (__classPrivateFieldGet(this, _ReasoningTracker_content, "f").has(requestId))
+            return;
+        if (chunkHasContent(text)) {
+            __classPrivateFieldGet(this, _ReasoningTracker_content, "f").add(requestId);
+            __classPrivateFieldGet(this, _ReasoningTracker_reasoning, "f").delete(requestId);
+            return;
+        }
+        if (chunkHasReasoning(text)) {
+            __classPrivateFieldGet(this, _ReasoningTracker_reasoning, "f").add(requestId);
+        }
+    }
+    /** Forget the request. Must be called on end *and* on error, or the flag sticks. */
+    end(requestId) {
+        __classPrivateFieldGet(this, _ReasoningTracker_reasoning, "f").delete(requestId);
+        __classPrivateFieldGet(this, _ReasoningTracker_content, "f").delete(requestId);
+    }
+    get active() {
+        return __classPrivateFieldGet(this, _ReasoningTracker_reasoning, "f").size > 0;
+    }
+    get count() {
+        return __classPrivateFieldGet(this, _ReasoningTracker_reasoning, "f").size;
+    }
+}
+_ReasoningTracker_reasoning = new WeakMap(), _ReasoningTracker_content = new WeakMap();
+//# sourceMappingURL=activity.js.map

package/dist/service/host-api.d.ts

@@ -0,0 +1,132 @@
+/**
+ * The brain's management API: everything Otto's Brain page needs that is not
+ * inference.
+ *
+ * This is deliberately served by the brain rather than driven by the daemon
+ * shelling out to the CLI. The daemon's `BrainOpsManager` runs `otto-brain
+ * <verb> --json`, which is local-only by construction, so every capability built
+ * that way needs a second implementation before a remote brain can have it. The
+ * daemon already resolves this endpoint by mode (local child or remote host), so
+ * a capability added here works the same in both without a branch anywhere.
+ *
+ * Model ids are relative file paths and therefore contain slashes, so the
+ * model-scoped routes take `?id=` rather than a path segment. Encoding a slash
+ * as %2F inside a path is the kind of thing an intermediary silently normalises,
+ * and the failure would look like "model not found" rather than a routing bug.
+ *
+ * Writes are gated on the same `allowRemoteConfig` flag as POST /__host/config.
+ * A brain that may be *used* over the network is not thereby a brain whose model
+ * files may be deleted over the network.
+ */
+import type http from "node:http";
+import { calibrationInfo, profileWarnings } from "../config/profile-edit.js";
+import type { Profile, ProfileDefaults, ProfilesStore } from "../config/schema.js";
+import { planDelete } from "../models/manage.js";
+import type { RankedModel } from "../ops/results.js";
+import type { GpuInfo, Model } from "../types.js";
+import * as vram from "../vram.js";
+import type { SystemSample } from "../sysmon.js";
+import type { Supervisor } from "./supervisor.js";
+/**
+ * What this brain can serve. The daemon folds this into `brain.host.status` and
+ * Otto gates each tab on it, because the daemon and the brain version
+ * independently: a current daemon can be pointed at an older brain, and the
+ * honest answer is "update the brain on that host", not a degraded reimplementation.
+ */
+export interface HostCapabilities {
+    /** GET/POST /__host/model/profile */
+    profiles: boolean;
+    /** GET /__host/model/budget */
+    budget: boolean;
+    /** GET /__host/logs */
+    logs: boolean;
+    /** DELETE /__host/model */
+    delete: boolean;
+    /** POST /__host/model/load and /__host/model/unload */
+    load: boolean;
+    /** The `resources` block on /__host/status */
+    resources: boolean;
+    /** GET /__host/models */
+    inventory: boolean;
+    /** Whether writes are currently permitted (allowRemoteConfig). */
+    writable: boolean;
+}
+export interface HostApiDeps {
+    supervisor: Supervisor;
+    /** The live catalog. Replaced wholesale by `rescan`. */
+    getCatalog: () => Model[];
+    /** Re-read the model directories, e.g. after a delete. Returns the new catalog. */
+    rescan: () => Model[];
+    getProfilesStore: () => ProfilesStore;
+    saveProfiles: (store: ProfilesStore) => void;
+    getProfileDefaults: () => ProfileDefaults | undefined;
+    queryGpuInfo: () => Promise<GpuInfo | null>;
+    getRanking: () => RankedModel[];
+    loadModel: (model: Model) => Promise<void>;
+    /** Mirrors POST /__host/config's gate: may a network caller change things? */
+    getAllowWrite: () => boolean;
+    /** The managed models directory, for disk accounting. Null when unresolvable. */
+    getModelsDir: () => string | null;
+    sampleResources: () => Promise<SystemSample>;
+}
+/** One row of the model inventory: the scan, metadata, profile and score joined. */
+export interface InventoryRow {
+    id: string;
+    displayName: string;
+    publisher: string | null;
+    quant: string | null;
+    sizeBytes: number;
+    mmprojBytes: number;
+    origin: string | null;
+    arch: string | null;
+    contextLength: number | null;
+    blockCount: number | null;
+    headCountKv: number | null;
+    /** Capability flags, matching the TUI's V / M / R badges. */
+    hasProjector: boolean;
+    reasoning: boolean;
+    mtp: boolean;
+    distilled: boolean;
+    useCases: string[];
+    tier: string | null;
+    profile: Profile;
+    calibration: ReturnType<typeof calibrationInfo>;
+    budget: vram.Budget | null;
+    maxContextThatFits: number | null;
+    score: RankedModel | null;
+    state: "loaded" | "loading" | "not-loaded";
+    warnings: ReturnType<typeof profileWarnings>;
+}
+/**
+ * Join one model's scan row, GGUF metadata, saved profile, calibration, VRAM
+ * budget and benchmark score into the single shape the Models tab renders.
+ *
+ * Exported for testing: the join is the part worth pinning down, since the
+ * client would otherwise have to correlate three unrelated lists by display name.
+ */
+export declare function buildInventoryRow(params: {
+    model: Model;
+    store: ProfilesStore;
+    defaults: ProfileDefaults | undefined;
+    gpu: GpuInfo | null;
+    ranking: RankedModel[];
+    supervisor: Supervisor;
+}): InventoryRow;
+export interface HostApi {
+    /** Returns true when it answered the request, false to fall through. */
+    handle: (req: http.IncomingMessage, res: http.ServerResponse) => boolean;
+    /**
+     * The current capability set. Exposed separately from the route so
+     * `/__host/status` can carry it inline: the daemon polls status constantly and
+     * would otherwise need a second round trip, or a cache that goes stale the
+     * moment `allowRemoteConfig` is toggled, since `writable` lives in here.
+     */
+    capabilities: () => HostCapabilities;
+}
+/**
+ * Build the `/__host/*` management handler.
+ */
+export declare function createHostApi(deps: HostApiDeps): HostApi;
+/** The delete plan without performing it, for a confirmation dialog. */
+export declare function describeDelete(model: Model): ReturnType<typeof planDelete>;
+//# sourceMappingURL=host-api.d.ts.map