@otto-code/brain 0.8.4 → 0.8.6

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

@@ -35,7 +35,7 @@ import type { Supervisor } from "./supervisor.js";
  * the API is this" for the rare change that no single flag describes. A daemon
  * reads both and never requires an exact package-version match.
  */
-export declare const HOST_API_VERSION = 2;
+export declare const HOST_API_VERSION = 3;
 /**
  * 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
@@ -74,6 +74,29 @@ export interface HostCapabilities {
     liveInference: boolean;
     /** Whether writes are currently permitted (allowRemoteConfig). */
     writable: boolean;
+    /** POST/GET /__host/jobs and POST /__host/jobs/cancel. */
+    jobs: boolean;
+    /** POST /__host/restart delegates a restart to the service owner. */
+    restart: boolean;
+}
+/** A long-running operation owned by this brain host, not its caller. */
+export interface HostJob {
+    id: string;
+    kind: "pull" | "runtime-install" | "calibrate" | "sweep" | "bench";
+    label: string;
+    target: string | null;
+    status: "running" | "succeeded" | "failed" | "canceled";
+    percent: null;
+    message: string | null;
+    error: string | null;
+    startedAt: string;
+    finishedAt: string | null;
+}
+export interface HostJobRunner {
+    start: (kind: HostJob["kind"], target: string | null, args: string[]) => HostJob;
+    list: () => HostJob[];
+    cancel: (jobId: string) => Promise<HostJob[]>;
+    query: (args: string[]) => Promise<unknown>;
 }
 export interface HostApiDeps {
     supervisor: Supervisor;
@@ -98,6 +121,10 @@ export interface HostApiDeps {
      * its daemon keeps polling status.
      */
     statusEvents?: BrainStatusPublisher | null;
+    /** Long operations that must execute on this brain's machine. */
+    jobs?: HostJobRunner;
+    /** Gracefully restart the serving process after its HTTP acknowledgement. */
+    restart?: () => void;
 }
 /** One row of the model inventory: the scan, metadata, profile and score joined. */
 export interface InventoryRow {

package/dist/service/host-api.js

@@ -14,7 +14,7 @@ const DEFAULT_LOG_LINES = 200;
  * the API is this" for the rare change that no single flag describes. A daemon
  * reads both and never requires an exact package-version match.
  */
-export const HOST_API_VERSION = 2;
+export const HOST_API_VERSION = 3;
 /**
  * How often the SSE stream writes a comment line when nothing has changed.
  *
@@ -128,6 +128,8 @@ export function createHostApi(deps) {
         events: Boolean(deps.statusEvents?.ready),
         liveInference: Boolean(deps.statusEvents?.ready),
         writable: deps.getAllowWrite(),
+        jobs: Boolean(deps.jobs),
+        restart: Boolean(deps.restart),
     });
     /** Refuse a write unless the owner opted into remote configuration. */
     const guardWrite = (res) => {
@@ -432,10 +434,193 @@ export function createHostApi(deps) {
             handleEvents(req, res, publisher);
             return true;
         }
+        // A remote caller can restart a managed brain without gaining start/stop
+        // control over the host daemon. Acknowledge first so it does not race the
+        // connection it is about to close.
+        if (route === "/__host/restart" && method === "POST") {
+            if (!deps.restart) {
+                sendError(res, 404, "this brain cannot restart itself");
+                return true;
+            }
+            if (!guardWrite(res))
+                return true;
+            sendJson(res, { accepted: true });
+            queueMicrotask(() => deps.restart?.());
+            return true;
+        }
         if (route === "/__host/logs" && method === "GET") {
             handleLogs(res, params);
             return true;
         }
+        // Benchmark jobs are deliberately host-owned. A remote daemon only proxies
+        // these calls, so selecting a remote brain can never wake the local GPU.
+        if (route === "/__host/jobs" && method === "GET") {
+            if (!deps.jobs) {
+                sendError(res, 404, "this brain does not serve remote jobs");
+            }
+            else {
+                sendJson(res, { jobs: deps.jobs.list() });
+            }
+            return true;
+        }
+        if (route === "/__host/jobs/bench" && method === "POST") {
+            if (!deps.jobs) {
+                sendError(res, 404, "this brain does not serve remote jobs");
+                return true;
+            }
+            readJsonBody(req, 4096, (result) => {
+                if (!result.ok) {
+                    sendError(res, 400, result.error);
+                    return;
+                }
+                const model = result.body.model;
+                if (model !== undefined && model !== null && typeof model !== "string") {
+                    sendError(res, 400, "model must be a string or null");
+                    return;
+                }
+                try {
+                    sendJson(res, {
+                        job: deps.jobs?.start("bench", model ?? null, [
+                            "bench",
+                            ...(model ? ["--model", model] : []),
+                        ]) ?? null,
+                    });
+                }
+                catch (error) {
+                    sendError(res, 409, errorMessage(error));
+                }
+            });
+            return true;
+        }
+        const jobStarts = {
+            "/__host/jobs/pull": {
+                kind: "pull",
+                makeArgs: (body) => {
+                    const model = body.model;
+                    if (typeof model !== "string" || !model)
+                        throw new Error("model is required");
+                    return { target: model, args: ["pull", "--json", "--", model] };
+                },
+            },
+            "/__host/jobs/add": {
+                kind: "pull",
+                makeArgs: (body) => {
+                    const repo = body.repo;
+                    const quant = body.quant;
+                    if (typeof repo !== "string" || !repo || typeof quant !== "string" || !quant)
+                        throw new Error("repo and quant are required");
+                    return {
+                        target: `${repo}#${quant}`,
+                        args: ["add", "--quant", quant, "--json", "--", repo],
+                    };
+                },
+            },
+            "/__host/jobs/runtime-install": {
+                kind: "runtime-install",
+                makeArgs: (body) => {
+                    const build = body.build;
+                    if (build !== undefined && build !== null && typeof build !== "string")
+                        throw new Error("build must be a string or null");
+                    return {
+                        target: typeof build === "string" ? build : null,
+                        args: [
+                            "runtime",
+                            "install",
+                            "--json",
+                            ...(typeof build === "string" ? ["--build", build] : []),
+                        ],
+                    };
+                },
+            },
+            "/__host/jobs/calibrate": {
+                kind: "calibrate",
+                makeArgs: (body) => {
+                    const model = body.model;
+                    if (typeof model !== "string" || !model)
+                        throw new Error("model is required");
+                    return { target: model, args: ["calibrate", "--model", model, "--json"] };
+                },
+            },
+            "/__host/jobs/sweep": {
+                kind: "sweep",
+                makeArgs: (body) => {
+                    const model = body.model;
+                    if (typeof model !== "string" || !model)
+                        throw new Error("model is required");
+                    return { target: model, args: ["sweep", "--model", model, "--json"] };
+                },
+            },
+        };
+        const start = jobStarts[route];
+        if (start && method === "POST") {
+            if (!deps.jobs) {
+                sendError(res, 404, "this brain does not serve remote jobs");
+                return true;
+            }
+            if (!guardWrite(res))
+                return true;
+            readJsonBody(req, 4096, (result) => {
+                if (!result.ok) {
+                    sendError(res, 400, result.error);
+                    return;
+                }
+                try {
+                    const spec = start.makeArgs(result.body);
+                    sendJson(res, { job: deps.jobs?.start(start.kind, spec.target, spec.args) ?? null });
+                }
+                catch (error) {
+                    sendError(res, 400, errorMessage(error));
+                }
+            });
+            return true;
+        }
+        if (route === "/__host/catalog" && method === "GET") {
+            void deps.jobs?.query(["catalog", "--json"]).then((models) => sendJson(res, { models }));
+            return true;
+        }
+        if (route === "/__host/runtimes" && method === "GET") {
+            void deps.jobs
+                ?.query(["runtime", "list", "--json"])
+                .then((runtimes) => sendJson(res, { runtimes }));
+            return true;
+        }
+        if (route === "/__host/hf/search" && method === "GET") {
+            const query = params.get("query") ?? "";
+            const limit = Math.max(1, Math.min(100, Number(params.get("limit")) || 25));
+            void deps.jobs
+                ?.query(["search", "--json", "--limit", String(limit), "--", query])
+                .then((results) => sendJson(res, { results }));
+            return true;
+        }
+        if (route === "/__host/hf/quants" && method === "GET") {
+            const repo = params.get("repo") ?? "";
+            void deps.jobs
+                ?.query(["add", "--list-quants", "--json", "--", repo])
+                .then((quants) => sendJson(res, { quants }));
+            return true;
+        }
+        if (route === "/__host/jobs/cancel" && method === "POST") {
+            if (!deps.jobs) {
+                sendError(res, 404, "this brain does not serve remote jobs");
+                return true;
+            }
+            readJsonBody(req, 4096, (result) => {
+                if (!result.ok) {
+                    sendError(res, 400, result.error);
+                    return;
+                }
+                const jobId = result.body.jobId;
+                if (typeof jobId !== "string" || !jobId) {
+                    sendError(res, 400, "jobId is required");
+                    return;
+                }
+                void deps.jobs
+                    ?.cancel(jobId)
+                    .then((jobs) => sendJson(res, { jobs }))
+                    .catch((error) => sendError(res, 500, errorMessage(error)));
+            });
+            return true;
+        }
         if (route === "/__host/resources" && method === "GET") {
             void (async () => {
                 try {

package/dist/service/serve.d.ts

@@ -1,14 +1,3 @@
-/**
- * The headless brain service: the router + supervisor bound to a port, with the
- * VRAM fit, on-demand model switching, remote auth, built-in TLS, and pid-file
- * lifecycle. Used both by `otto brain serve` (foreground) and by a detached
- * `otto brain start`. It stays provider-neutral about the runtime source - it
- * takes whatever resolveRuntime picks (managed or LM Studio).
- *
- * TLS is served in-process (config.tls): HTTPS with a files / self-signed /
- * tailscale certificate, hot-swapped on renewal. This is what lets the brain be
- * exposed securely over a network with no relay in front of it.
- */
 import http from "node:http";
 import type { BrainConfig } from "../config/schema.js";
 import type { Model } from "../types.js";

package/dist/service/serve.js

@@ -9,6 +9,8 @@
  * tailscale certificate, hot-swapped on renewal. This is what lets the brain be
  * exposed securely over a network with no relay in front of it.
  */
+import { execFile, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import http from "node:http";
 import https from "node:https";
 import { getCalibration, forModel, loadPersistedConfig, loadProfilesStore, saveBrainConfig, saveProfilesStore, } from "../config/index.js";
@@ -54,6 +56,130 @@ function collectEvals() {
         return { rankings: [], latest: [], variance: [], runCount: 0 };
     }
 }
+const REMOTE_JOB_RETENTION_MS = 5 * 60000;
+/**
+ * Runs a benchmark as a child of the brain service. This is intentionally here
+ * rather than in the connecting daemon: its process, model store, results
+ * directory and GPU all belong to the host that is being benchmarked.
+ */
+class ServiceJobRunner {
+    constructor() {
+        this.jobs = new Map();
+    }
+    start(kind, target, args) {
+        const running = [...this.jobs.values()].find((job) => job.status === "running");
+        if (running)
+            throw new Error(`Another operation is already running (${running.label}).`);
+        const job = {
+            id: `brainjob_${randomUUID()}`,
+            kind,
+            label: kind === "bench"
+                ? target
+                    ? `Benchmark ${target}`
+                    : "Benchmark models"
+                : `${kind} ${target ?? ""}`.trim(),
+            target,
+            status: "running",
+            percent: null,
+            message: null,
+            error: null,
+            startedAt: new Date().toISOString(),
+            finishedAt: null,
+            child: null,
+        };
+        // The service is launched by the same CLI entry point as `otto-brain bench`.
+        // Reusing that entry point keeps its config/path resolution on this host.
+        const entry = process.argv[1];
+        if (!entry)
+            throw new Error("The brain service has no CLI entry point.");
+        const child = spawn(process.execPath, [entry, ...args], {
+            cwd: process.cwd(),
+            env: process.env,
+            stdio: ["ignore", "ignore", "pipe"],
+            windowsHide: true,
+        });
+        job.child = child;
+        this.jobs.set(job.id, job);
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", (chunk) => {
+            const last = chunk.trim().split(/\r?\n/).at(-1)?.trim();
+            if (last)
+                job.message = last.slice(-1000);
+        });
+        child.once("error", (error) => this.finish(job, "failed", error.message));
+        child.once("close", (code) => {
+            if (job.status !== "running")
+                return;
+            this.finish(job, code === 0 ? "succeeded" : "failed", code === 0 ? null : `Exited with code ${code}.`);
+        });
+        return this.publicJob(job);
+    }
+    async query(args) {
+        const entry = process.argv[1];
+        if (!entry)
+            throw new Error("The brain service has no CLI entry point.");
+        return new Promise((resolve, reject) => {
+            const child = spawn(process.execPath, [entry, ...args], {
+                cwd: process.cwd(),
+                env: process.env,
+                stdio: ["ignore", "pipe", "pipe"],
+                windowsHide: true,
+            });
+            let out = "";
+            let err = "";
+            child.stdout?.setEncoding("utf8");
+            child.stderr?.setEncoding("utf8");
+            child.stdout?.on("data", (chunk) => (out += chunk));
+            child.stderr?.on("data", (chunk) => (err += chunk));
+            child.once("error", reject);
+            child.once("close", (code) => {
+                if (code !== 0)
+                    return reject(new Error(err.trim() || `Exited with code ${code}.`));
+                try {
+                    resolve(JSON.parse(out));
+                }
+                catch {
+                    reject(new Error("The brain command returned invalid JSON."));
+                }
+            });
+        });
+    }
+    list() {
+        const cutoff = Date.now() - REMOTE_JOB_RETENTION_MS;
+        for (const [id, job] of this.jobs) {
+            if (job.finishedAt && Date.parse(job.finishedAt) < cutoff)
+                this.jobs.delete(id);
+        }
+        return [...this.jobs.values()]
+            .sort((a, b) => b.startedAt.localeCompare(a.startedAt))
+            .map((job) => this.publicJob(job));
+    }
+    async cancel(jobId) {
+        const job = this.jobs.get(jobId);
+        if (!job || job.status !== "running" || !job.child)
+            return this.list();
+        const child = job.child;
+        if (process.platform === "win32" && child.pid) {
+            await new Promise((resolve) => execFile("taskkill", ["/pid", String(child.pid), "/t", "/f"], () => resolve()));
+        }
+        else {
+            child.kill("SIGTERM");
+        }
+        this.finish(job, "canceled", "Canceled.");
+        return this.list();
+    }
+    finish(job, status, error) {
+        if (job.status !== "running")
+            return;
+        job.child = null;
+        job.status = status;
+        job.error = error;
+        job.finishedAt = new Date().toISOString();
+    }
+    publicJob({ child: _child, ...job }) {
+        return job;
+    }
+}
 function isLoopback(host) {
     return host === "127.0.0.1" || host === "::1" || host === "localhost";
 }
@@ -263,6 +389,10 @@ export async function startService({ config, modelNeedle, env = process.env, onL
     // /__host/events. One instance, so `capabilities.events` and the stream can
     // never disagree about whether this brain publishes.
     const statusEvents = new BrainStatusPublisher();
+    const jobs = new ServiceJobRunner();
+    // Assigned once `stop` exists below. This indirection lets the management API
+    // answer a remote restart request before closing its own socket.
+    let requestRestart = () => { };
     const hostApi = createHostApi({
         supervisor,
         getCatalog: () => catalog,
@@ -290,6 +420,8 @@ export async function startService({ config, modelNeedle, env = process.env, onL
         getModelsDir: () => managedModelsDir(config, env),
         sampleResources: () => sampleSystem(cpuSampler, { host: supervisor.host, port: supervisor.internalPort }),
         statusEvents,
+        jobs,
+        restart: () => requestRestart(),
     });
     const handler = withAuth(createRouter({
         supervisor,
@@ -366,6 +498,9 @@ export async function startService({ config, modelNeedle, env = process.env, onL
         await new Promise((resolve) => server.close(() => resolve()));
         removePidFile(env);
     };
+    requestRestart = () => {
+        void stop().finally(() => process.exit(75));
+    };
     return {
         server,
         supervisor,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@otto-code/brain",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "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": {