@clutor/cli 0.1.0 → 0.2.0

package/dist/{chunk-6WAEQCCP.js → chunk-2FBPYNHP.js}

@@ -320,7 +320,8 @@ function withPrefixSnapshots(inner, snaps) {
 }
 
 // src/models.ts
-import { createWriteStream } from "fs";
+import { createHash as createHash3 } from "crypto";
+import { createReadStream, createWriteStream } from "fs";
 import { mkdir, readdir, rename, rm, stat, statfs } from "fs/promises";
 import { Readable } from "stream";
 import { pipeline } from "stream/promises";
@@ -380,8 +381,9 @@ async function listLocalModels(dir) {
 }
 var GiB_ = 2 ** 30;
 var DOWNLOADS = [
-  { id: "olmoe-1b-7b-q4_k_m", catalogId: "olmoe-1b-7b", repo: "bartowski/OLMoE-1B-7B-0924-Instruct-GGUF", file: "OLMoE-1B-7B-0924-Instruct-Q4_K_M.gguf", bytes: Math.round(3.92 * GiB_), note: "a real mixture-of-experts model (64 experts, 8 used): the one to test expert streaming with" },
-  { id: "qwen2.5-coder-7b-q4_k_m", catalogId: "qwen2.5-coder-7b", repo: "Qwen/Qwen2.5-Coder-7B-Instruct-GGUF", file: "qwen2.5-coder-7b-instruct-q4_k_m.gguf", bytes: Math.round(4.36 * GiB_), note: "a dense coding model for the agent (not a mixture of experts)" }
+  { id: "olmoe-1b-7b-q4_k_m", catalogId: "olmoe-1b-7b", repo: "allenai/OLMoE-1B-7B-0924-Instruct-GGUF", file: "olmoe-1b-7b-0924-instruct-q4_k_m.gguf", bytes: 4213512672, sha256: "8c310f1435a1222338fd2d3d974975be9cd908180b644bab0c2a94da1ac32f3f", note: "a real mixture-of-experts model (64 experts, 8 used) that fits in memory: the one `clutor generate` was validated on" },
+  { id: "qwen3-30b-a3b-q4_k_m", catalogId: "qwen3-30b-a3b", repo: "Qwen/Qwen3-30B-A3B-GGUF", file: "Qwen3-30B-A3B-Q4_K_M.gguf", bytes: 18556685824, sha256: "0d003f6662faee786ed5da3e31b29c978de5ae5d275c8794c606a7f3c01aa8f5", note: "a mixture-of-experts model (128 experts, 8 used) LARGER than 16 GiB of RAM: run it with `clutor generate ... --cache-mb 4096`" },
+  { id: "qwen2.5-coder-7b-q4_k_m", catalogId: "qwen2.5-coder-7b", repo: "Qwen/Qwen2.5-Coder-7B-Instruct-GGUF", file: "qwen2.5-coder-7b-instruct-q4_k_m.gguf", bytes: 4683073536, sha256: "509287f78cb4d4cf6b3843734733b914b2c158e43e22a7f4bf5e963800894d3c", note: "a dense coding model for the agent (not a mixture of experts)" }
 ];
 var downloadUrl = (d) => `https://huggingface.co/${d.repo}/resolve/main/${d.file}`;
 var DownloadError = class extends Error {
@@ -393,29 +395,49 @@ var DownloadError = class extends Error {
 async function downloadFile(url, dest, opts = {}) {
   const f = opts.fetch ?? globalThis.fetch;
   await mkdir(resolve(dest, ".."), { recursive: true });
-  const res = await f(url, { redirect: "follow" });
+  const part = `${dest}.part`;
+  const have = await stat(part).then((s) => s.size).catch(() => 0);
+  let res = await f(url, { redirect: "follow", ...have > 0 ? { headers: { Range: `bytes=${have}-` } } : {} });
+  if (res.status === 416) {
+    await rm(part, { force: true });
+    res = await f(url, { redirect: "follow" });
+  }
   if (!res.ok || !res.body) throw new DownloadError(`the server answered ${res.status} for ${url}`);
-  const total = Number(res.headers.get("content-length") ?? 0);
+  const resumed = res.status === 206;
+  let start = 0, total;
+  if (resumed) {
+    const m = /^bytes (\d+)-\d+\/(\d+)$/.exec(res.headers.get("content-range") ?? "");
+    if (!m || Number(m[1]) !== have) throw new DownloadError("the server's answer to the resume request does not continue where the partial file stops");
+    start = have;
+    total = Number(m[2]);
+  } else {
+    total = Number(res.headers.get("content-length") ?? 0);
+  }
   if (!total) throw new DownloadError("the server did not say how large the file is, so it cannot be checked");
   if (opts.expectedBytes && Math.abs(total - opts.expectedBytes) / opts.expectedBytes > 0.05) throw new DownloadError(`expected about ${opts.expectedBytes} bytes but the server offers ${total}; not downloading`);
   const fs = await statfs(resolve(dest, ".."));
   const free = Number(fs.bavail) * Number(fs.bsize);
-  if (free < total * 1.1) throw new DownloadError(`not enough free disk: need ${(total / GiB_).toFixed(2)} GiB, have ${(free / GiB_).toFixed(2)} GiB`);
-  const part = `${dest}.part`;
-  let done = 0;
+  if (free < (total - start) * 1.1) throw new DownloadError(`not enough free disk: need ${((total - start) / GiB_).toFixed(2)} GiB, have ${(free / GiB_).toFixed(2)} GiB`);
+  const hash = opts.expectedSha256 ? createHash3("sha256") : void 0;
+  if (hash && start > 0) for await (const chunk of createReadStream(part)) hash.update(chunk);
+  let done = start;
   const body = Readable.fromWeb(res.body);
   body.on("data", (c) => {
     done += c.length;
+    hash?.update(c);
     opts.onProgress?.(done, total);
   });
   try {
-    await pipeline(body, createWriteStream(part));
-    if (done !== total) throw new DownloadError(`the download stopped at ${done} of ${total} bytes`);
-    await rename(part, dest);
+    await pipeline(body, createWriteStream(part, { flags: resumed ? "a" : "w" }));
   } catch (e) {
+    throw new DownloadError(`the download was interrupted at ${done} of ${total} bytes (${e instanceof Error ? e.message : String(e)}); run the same command again to resume`);
+  }
+  if (done !== total) throw new DownloadError(`the download stopped at ${done} of ${total} bytes; run the same command again to resume`);
+  if (hash && hash.digest("hex") !== opts.expectedSha256?.toLowerCase()) {
     await rm(part, { force: true });
-    throw e;
+    throw new DownloadError("the downloaded file does not match the SHA-256 the publisher lists; it was deleted");
   }
+  await rename(part, dest);
   return total;
 }
 
@@ -539,7 +561,7 @@ async function handleMcp(req, ctx) {
   if (req.jsonrpc !== "2.0" || typeof req.method !== "string") return err(-32600, "not a JSON-RPC 2.0 request");
   switch (req.method) {
     case "initialize":
-      return ok({ protocolVersion: "2025-03-26", capabilities: { tools: {} }, serverInfo: { name: "clutor", version: "0.1.0" } });
+      return ok({ protocolVersion: "2025-03-26", capabilities: { tools: {} }, serverInfo: { name: "clutor", version: ctx.version ?? "unknown" } });
     case "notifications/initialized":
       return { status: 202, body: "" };
     case "ping":
@@ -1000,8 +1022,8 @@ function createClutorServer(o) {
         }
       } else {
         const { mkdtemp, rm: rm2 } = await import("fs/promises");
-        const { tmpdir: tmpdir2 } = await import("os");
-        const dir = await mkdtemp(`${tmpdir2()}/clutor-bench-`);
+        const { tmpdir: tmpdir3 } = await import("os");
+        const dir = await mkdtemp(`${tmpdir3()}/clutor-bench-`);
         cleanup = () => rm2(dir, { recursive: true, force: true });
         file = `${dir}/bench.gguf`;
         await writeSyntheticGguf(file, { arch: "qwen2moe", name: "bench-moe", layers: 8, embedding: 1024, heads: 16, kvHeads: 4, contextLength: 4096, expertCount: 32, expertsUsed: 4, expertFfn: 1024, denseFfn: 0, vocab: 4096, sharedExperts: 0 });
@@ -1022,7 +1044,7 @@ function createClutorServer(o) {
       }
     }
     if (method === "POST" && path === "/api/mcp") {
-      const r = await handleMcp(await readBody(req), { isRoot: (d) => rootFor(d).catch(() => null) });
+      const r = await handleMcp(await readBody(req), { isRoot: (d) => rootFor(d).catch(() => null), version: o.version });
       return r.status === 202 ? (res.writeHead(202, cors), void res.end()) : reply(r.status, r.body);
     }
     if (method === "POST" && path === "/api/agent/run") {
@@ -1134,8 +1156,9 @@ function createClutorServer(o) {
 
 // src/engine.ts
 import { spawn as spawn2 } from "child_process";
-import { accessSync as accessSync2, constants as constants2 } from "fs";
-import { homedir as homedir3 } from "os";
+import { createHash as createHash4 } from "crypto";
+import { accessSync as accessSync2, chmodSync, constants as constants2, copyFileSync, existsSync, mkdirSync as mkdirSync2, mkdtempSync, rmSync, writeFileSync } from "fs";
+import { homedir as homedir3, tmpdir } from "os";
 import { delimiter as delimiter2, dirname, join as join5 } from "path";
 import { fileURLToPath } from "url";
 var EngineError = class extends Error {
@@ -1154,8 +1177,11 @@ var executable = (p) => {
   }
 };
 function engineSourceDir() {
-  return join5(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "c");
+  const here = dirname(fileURLToPath(import.meta.url));
+  const packaged = join5(here, "..", "c");
+  return existsSync(join5(packaged, "Makefile")) ? packaged : join5(here, "..", "..", "..", "c");
 }
+var isPackaged = () => existsSync(join5(dirname(fileURLToPath(import.meta.url)), "..", "c", "Makefile"));
 function findEngine(env = process.env) {
   const candidates = [env["CLUTOR_ENGINE"], join5(engineSourceDir(), "build", EXE), join5(homedir3(), ".clutor", "bin", EXE), ...(env["PATH"] ?? "").split(delimiter2).map((d) => join5(d, EXE))];
   return candidates.find((c) => !!c && executable(c));
@@ -1186,12 +1212,13 @@ function run(bin, args, opts = {}) {
 }
 async function buildEngine() {
   const dir = engineSourceDir();
-  const r = await run("make", ["-C", dir], { timeoutMs: 3e5 }).catch((e) => {
+  const out = isPackaged() ? join5(homedir3(), ".clutor", "bin") : join5(dir, "build");
+  const r = await run("make", ["-C", dir, ...isPackaged() ? [`BUILD=${out}`] : []], { timeoutMs: 3e5 }).catch((e) => {
     throw new EngineError(`could not run make: ${e instanceof Error ? e.message : String(e)}`);
   });
   if (r.code !== 0) throw new EngineError(`the engine did not compile:
 ${(r.stderr || r.stdout).split("\n").slice(-15).join("\n")}`);
-  const bin = join5(dir, "build", EXE);
+  const bin = join5(out, EXE);
   if (!executable(bin)) throw new EngineError(`make finished but ${bin} is missing`);
   return bin;
 }
@@ -1218,6 +1245,7 @@ function streamArgs(file, o) {
   add("--window", o.window);
   if (o.shift) add("--shift", `${o.shift.at},${o.shift.len}`);
   if (o.noOsCache) a.push("--no-os-cache");
+  if (o.trace) a.push("--trace", o.trace);
   return a;
 }
 async function engineInfo(bin, file) {
@@ -1234,10 +1262,85 @@ async function engineStream(bin, file, o = {}, timeoutMs = 9e5) {
     throw new EngineError("the engine printed something that is not a report");
   }
 }
+function engineRun(bin, args, onOut, timeoutMs = 36e5) {
+  return new Promise((resolve3, reject) => {
+    const child = spawn2(bin, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stderr = "";
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(new EngineError(`${bin} did not finish within ${timeoutMs / 1e3} seconds`));
+    }, timeoutMs);
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", onOut);
+    child.stderr.on("data", (b) => {
+      stderr += b.toString();
+    });
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      reject(new EngineError(`could not start ${bin}: ${e.message}`));
+    });
+    child.on("close", (code2) => {
+      clearTimeout(timer);
+      resolve3({ code: code2 ?? 1, stderr });
+    });
+  });
+}
+function enginePlatform() {
+  const os = process.platform === "darwin" ? "darwin" : process.platform === "linux" ? "linux" : void 0;
+  const arch = process.arch === "arm64" ? "arm64" : process.arch === "x64" ? "x64" : void 0;
+  return os && arch ? `${os}-${arch}` : void 0;
+}
+var RELEASE_BASE = (version2) => process.env["CLUTOR_RELEASE_BASE"] ?? `https://github.com/isagarpinninti/clutor/releases/download/v${version2}`;
+var MAX_ASSET = 64 * 2 ** 20;
+async function download(url) {
+  if (!url.startsWith("https://") && !/^http:\/\/(127\.0\.0\.1|localhost)[:/]/.test(url)) throw new EngineError(`refusing to download over an insecure connection: ${url}`);
+  let res;
+  try {
+    res = await fetch(url);
+  } catch (e) {
+    throw new EngineError(`could not reach ${url}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  if (!res.ok) throw new EngineError(`${url} answered ${res.status}${res.status === 404 ? ": no prebuilt engine is published for this version and platform; use `clutor engine build` instead" : ""}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  if (buf.length > MAX_ASSET) throw new EngineError(`${url} is larger than ${MAX_ASSET / 2 ** 20} MiB; refusing it`);
+  return buf;
+}
+async function installPrebuilt(version2, dest = join5(homedir3(), ".clutor", "bin")) {
+  const platform = enginePlatform();
+  if (!platform) throw new EngineError(`no prebuilt engine is published for ${process.platform}/${process.arch}; use \`clutor engine build\` (needs a C compiler)`);
+  const base = RELEASE_BASE(version2), asset = `clutor-engine-${platform}.tar.gz`;
+  const sums = (await download(`${base}/SHA256SUMS`)).toString("utf8");
+  const line = sums.split("\n").map((l) => l.trim().split(/\s+/)).find((p) => p.length >= 2 && p[1].replace(/^\*/, "") === asset);
+  if (!line) throw new EngineError(`SHA256SUMS lists no ${asset}`);
+  const tarball = await download(`${base}/${asset}`);
+  const got = createHash4("sha256").update(tarball).digest("hex");
+  if (got !== line[0].toLowerCase()) throw new EngineError(`checksum mismatch for ${asset}: expected ${line[0]}, got ${got}. Nothing was installed`);
+  const work = mkdtempSync(join5(tmpdir(), "clutor-engine-install-"));
+  try {
+    const file = join5(work, asset);
+    writeFileSync(file, tarball);
+    const x = await run("tar", ["-xzf", file, "-C", work], { timeoutMs: 6e4 });
+    if (x.code !== 0) throw new EngineError(`could not unpack ${asset}: ${x.stderr.trim()}`);
+    const unpacked = join5(work, `clutor-engine-${platform}`, EXE);
+    if (!existsSync(unpacked)) throw new EngineError(`${asset} does not contain ${EXE}`);
+    chmodSync(unpacked, 493);
+    const probe = await run(unpacked, ["--version"], { timeoutMs: 15e3 }).catch((e) => {
+      throw new EngineError(`the downloaded engine does not run here: ${e instanceof Error ? e.message : String(e)}`);
+    });
+    if (probe.code !== 0) throw new EngineError(`the downloaded engine does not run here (exit ${probe.code}); use \`clutor engine build\``);
+    mkdirSync2(dest, { recursive: true });
+    const out = join5(dest, EXE);
+    copyFileSync(unpacked, out);
+    chmodSync(out, 493);
+    return out;
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
 
 // src/cli.ts
-import { existsSync, mkdirSync as mkdirSync2, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
-import { tmpdir } from "os";
+import { existsSync as existsSync2, mkdirSync as mkdirSync3, mkdtempSync as mkdtempSync2, readFileSync, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
+import { tmpdir as tmpdir2 } from "os";
 import { dirname as dirname2, join as join6, resolve as resolve2 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import {
@@ -1288,9 +1391,13 @@ Usage: clutor <command> [options]
                                      Replay a routing trace through the expert cache: baseline LRU against clutor
   bench [--file model.gguf] [--engine] [--cache-mb N] [--tokens N] [--compute kernel|checksum]
                                      Measure real disk reads on this machine; with the native engine, also compare cache and prefetch strategies
-  stream <model.gguf> [--tokens N] [--cache-mb N] [--policy lru|wtinylfu|adaptive] [--smart J,M,TAU|off] [--prefetch on|off] [--dense auto|resident|ring] [--compute kernel|checksum] [--json]
+  stream <model.gguf> [--tokens N] [--cache-mb N] [--policy lru|wtinylfu|adaptive] [--smart J,M,TAU|off] [--prefetch on|off] [--dense auto|resident|ring] [--compute kernel|checksum] [--trace FILE] [--json]
                                      Stream a model's experts from disk through the native engine (synthetic routing; measured I/O and cache)
-  engine build|where                 Compile the native engine from c/ (needs a C compiler), or show which one is used
+  generate <model.gguf> "<prompt>" [--n N] [--cache-mb N] [--smart J,M,TAU] [--prefetch off|prev|ahead] [--trace FILE]
+                                     Generate text with the native engine's real forward pass (olmoe models). With --cache-mb the experts stream from disk through a cache of that size
+  quality <model.gguf> <text-file> --cache-mb N [--smart J,M,TAU] [--max-tokens N] [--json]
+                                     Perplexity, KL divergence and top-token agreement of a streamed (optionally smart-route) run against exact routing
+  engine install|build|where         Install the prebuilt native engine (checked against a SHA-256), or compile it from c/ (needs a C compiler), or show which one is used
   code "<task>" [--dir folder] [--apply] [--yes] [--verify "npm test"] [--max-steps N]
                                      Run the coding agent on a folder; review the diff before anything is written
   serve [dir] [--port ${DEFAULT_PORT}] [--folder dir]...   Start the local server: OpenAI and Ollama compatible API, agent, MCP
@@ -1316,7 +1423,7 @@ async function main(argv, io, session) {
   const json = flagBool(args, "json");
   try {
     if (flagBool(args, "version") || command === "version" || argv.includes("-v")) return io.out(version()), 0;
-    if (!command && !flagBool(args, "help") && !argv.includes("-h") && io.prompt && !session) return await (await import("./repl-OVODHQI5.js")).runRepl(io, (a, s) => main(a, io, s), (cfg, what) => engineSlashCommand(io, cfg, what));
+    if (!command && !flagBool(args, "help") && !argv.includes("-h") && io.prompt && !session) return await (await import("./repl-DOWMDXFR.js")).runRepl(io, (a, s) => main(a, io, s), (cfg, what) => engineSlashCommand(io, cfg, what), version());
     if (!command || flagBool(args, "help") || command === "help" || argv.includes("-h")) return io.out(HELP), 0;
     switch (command) {
       case "init":
@@ -1325,6 +1432,10 @@ async function main(argv, io, session) {
         return await models(io, args, rest[0], json);
       case "stream":
         return await streamCmd(io, args, rest[0], json);
+      case "generate":
+        return await generateCmd(io, args, rest[0], rest.slice(1).join(" "));
+      case "quality":
+        return await qualityCmd(io, args, rest[0], rest[1], json);
       case "engine":
         return await engineCmd(io, rest[0]);
       case "pull":
@@ -1373,13 +1484,13 @@ async function main(argv, io, session) {
 }
 function init(io, dirArg) {
   const dir = resolve2(io.cwd, dirArg ?? ".");
-  mkdirSync2(join6(dir, "models"), { recursive: true });
+  mkdirSync3(join6(dir, "models"), { recursive: true });
   const path = join6(dir, CONFIG_FILE);
-  if (existsSync(path)) {
+  if (existsSync2(path)) {
     io.err(`${path} already exists; leaving it alone`);
     return 1;
   }
-  writeFileSync(path, `${JSON.stringify({ port: DEFAULT_PORT, models: "models", backend: { kind: "none" }, memory: { contextTokens: 8192, kvBits: 16 }, cache: { policy: "adaptive" }, agent: { toolMode: "json", maxSteps: 30 } }, null, 2)}
+  writeFileSync2(path, `${JSON.stringify({ port: DEFAULT_PORT, models: "models", backend: { kind: "none" }, memory: { contextTokens: 8192, kvBits: 16 }, cache: { policy: "adaptive" }, agent: { toolMode: "json", maxSteps: 30 } }, null, 2)}
 `);
   const h = hostInfo3();
   io.out(`Created ${path} and ${join6(dir, "models")}.`);
@@ -1498,8 +1609,8 @@ async function bench(io, args, json) {
   let cleanup;
   if (file) path = resolve2(io.cwd, file);
   else {
-    const dir = mkdtempSync(join6(tmpdir(), "clutor-bench-"));
-    cleanup = () => rmSync(dir, { recursive: true, force: true });
+    const dir = mkdtempSync2(join6(tmpdir2(), "clutor-bench-"));
+    cleanup = () => rmSync2(dir, { recursive: true, force: true });
     path = join6(dir, "bench.gguf");
     io.err("No --file given: writing a test model of about 1 GiB to the temp folder (it will be deleted).");
     await writeSyntheticGguf2(path, { arch: "qwen2moe", name: "bench-moe", layers: 8, embedding: 1024, heads: 16, kvHeads: 4, contextLength: 4096, expertCount: 32, expertsUsed: 4, expertFfn: 1024, denseFfn: 0, vocab: 4096, sharedExperts: 0 });
@@ -1512,7 +1623,7 @@ async function bench(io, args, json) {
     const m = await measureExpertReads2(path, layout, h.totalRamBytes, 96);
     const dm = diskModelFrom(m, expertSizeBytes2(layout), layout.layers.find((l) => l.experts.length)?.experts[0]?.length ?? 1);
     const bin = findEngine();
-    if (flagBool(args, "engine") && !bin) throw new UsageError("the native engine is not built: run `clutor engine build` (needs a C compiler)");
+    if (flagBool(args, "engine") && !bin) throw new UsageError("the native engine is not installed: run `clutor engine install` (prebuilt) or `clutor engine build` (needs a C compiler)");
     const startedAt = (/* @__PURE__ */ new Date()).toISOString();
     const cmp = bin ? await compareStrategies(bin, path, flagInt(args, "cache-mb", 1, 1e6) ?? Math.max(64, Math.floor(h.totalRamBytes / 2 ** 20 / 16)), flagInt(args, "tokens", 10, 1e5) ?? 300, flagString(args, "dense"), computeFlag(args)) : void 0;
     if (json) {
@@ -1637,7 +1748,7 @@ async function code(io, args, task, session) {
   if (!task.trim()) throw new UsageError('usage: clutor code "<what to do>" [--dir folder]');
   const { config, root } = cfgFor(args, io);
   const dir = resolve2(io.cwd, flagString(args, "dir") ?? ".");
-  if (!existsSync(dir)) throw new UsageError(`${dir} does not exist`);
+  if (!existsSync2(dir)) throw new UsageError(`${dir} does not exist`);
   const backend = session ? session.backend ??= await startBackendIfConfigured(config, io) : await startBackendIfConfigured(config, io);
   try {
     const llm = llmFrom(config, backend);
@@ -1942,7 +2053,7 @@ async function pull(io, args, id) {
   const d = DOWNLOADS.find((x) => x.id === id);
   if (!d) throw new UsageError(`unknown download "${id}"; run clutor pull to see the list`);
   const dest = join6(dir, d.file);
-  if (existsSync(dest)) {
+  if (existsSync2(dest)) {
     io.out(`${dest} is already there.`);
     return 0;
   }
@@ -1954,7 +2065,7 @@ async function pull(io, args, id) {
     }
   }
   let last = 0;
-  const bytes = await downloadFile(downloadUrl(d), dest, { expectedBytes: d.bytes, onProgress: (done, total) => {
+  const bytes = await downloadFile(downloadUrl(d), dest, { expectedBytes: d.bytes, expectedSha256: d.sha256, onProgress: (done, total) => {
     const p = Math.floor(done / total * 10);
     if (p > last) {
       last = p;
@@ -2013,10 +2124,91 @@ function formatComparison(c) {
     table(rows, ["", ...c.map((x) => x.name)])
   ].join("\n");
 }
+function engineFlags(args) {
+  const out = [];
+  const num = (n, lo, hi) => {
+    const v = flagInt(args, n, lo, hi);
+    if (v !== void 0) out.push(`--${n}`, String(v));
+  };
+  num("cache-mb", 1, 1e7);
+  num("io-threads", 1, 16);
+  num("prefetch-n", 1, 64);
+  num("stage", 1, 1e5);
+  const pol = flagString(args, "policy");
+  if (pol) {
+    if (!["lru", "wtinylfu", "adaptive"].includes(pol)) throw new UsageError("--policy must be lru, wtinylfu or adaptive");
+    out.push("--policy", pol);
+  }
+  const pf = flagString(args, "prefetch");
+  if (pf) {
+    if (!["on", "off", "prev", "ahead"].includes(pf)) throw new UsageError("--prefetch must be off, prev or ahead");
+    out.push("--prefetch", pf);
+  }
+  const sm = flagString(args, "smart");
+  if (sm && sm !== "off") {
+    if (!/^\d+,\d+,[\d.]+$/.test(sm)) throw new UsageError("--smart wants J,M,TAU, for example 4,16,0.02");
+    out.push("--smart", sm);
+  }
+  if (flagBool(args, "no-os-cache")) out.push("--no-os-cache");
+  return out;
+}
+async function generateCmd(io, args, file, prompt) {
+  if (!file || !prompt.trim()) throw new UsageError('usage: clutor generate <model.gguf> "<prompt>" [--n N] [--cache-mb N] [--smart J,M,TAU]');
+  const bin = findEngine();
+  if (!bin) throw new UsageError("the native engine is not installed: run `clutor engine install` (prebuilt) or `clutor engine build` (needs a C compiler)");
+  const path = resolve2(io.cwd, file);
+  if (!existsSync2(path)) throw new UsageError(`${path} does not exist`);
+  const n = flagInt(args, "n", 1, 1e5) ?? 64;
+  const trace = flagString(args, "trace");
+  const argv = ["generate", path, prompt, "--n", String(n), ...engineFlags(args), ...trace ? ["--trace", resolve2(io.cwd, trace)] : []];
+  const r = await engineRun(bin, argv, (s) => (io.write ?? ((t) => io.out(t.replace(/\n$/, ""))))(s));
+  io.write?.("\n");
+  if (r.stderr.trim()) io.err(r.stderr.trim());
+  if (r.code !== 0) {
+    io.err(`the engine exited with ${r.code}`);
+    return 1;
+  }
+  return 0;
+}
+async function qualityCmd(io, args, file, text, json) {
+  if (!file || !text) throw new UsageError("usage: clutor quality <model.gguf> <text-file> --cache-mb N [--smart J,M,TAU] [--max-tokens N]");
+  if (flagInt(args, "cache-mb", 1, 1e7) === void 0) throw new UsageError("quality compares against a streamed run: give --cache-mb N");
+  const bin = findEngine();
+  if (!bin) throw new UsageError("the native engine is not installed: run `clutor engine install` (prebuilt) or `clutor engine build` (needs a C compiler)");
+  const path = resolve2(io.cwd, file), textPath = resolve2(io.cwd, text);
+  if (!existsSync2(path)) throw new UsageError(`${path} does not exist`);
+  if (!existsSync2(textPath)) throw new UsageError(`${textPath} does not exist`);
+  const mt = flagInt(args, "max-tokens", 2, 1e6);
+  const r = await run(bin, ["quality", path, textPath, ...engineFlags(args), ...mt ? ["--max-tokens", String(mt)] : []], { timeoutMs: 36e5 });
+  if (r.code !== 0) {
+    io.err(r.stderr.trim() || `the engine exited with ${r.code}`);
+    return 1;
+  }
+  if (json) {
+    io.out(r.stdout.trim());
+    return 0;
+  }
+  let q;
+  try {
+    q = JSON.parse(r.stdout);
+  } catch {
+    throw new EngineError("the engine printed something that is not a report");
+  }
+  const n = (k) => q[k];
+  io.out([
+    `MEASURED  ${n("tokensScored")} tokens scored, teacher-forced`,
+    `MEASURED  perplexity ${n("perplexityExact").toFixed(3)} exact routing, ${n("perplexityRun").toFixed(3)} this run (x${n("perplexityRatio").toFixed(4)})`,
+    `MEASURED  KL divergence from exact ${n("meanKL").toFixed(4)}; the top token is unchanged at ${(n("top1Agreement") * 100).toFixed(1)}% of positions`,
+    q["smart"] ? `MEASURED  smart-route used a resident expert for ${(100 * n("substitutions") / n("expertSlots")).toFixed(1)}% of expert slots; the largest probability moved was ${n("maxProbMoved").toFixed(4)}` : "smart-route off",
+    `MEASURED  expert cache hit rate ${(n("hitRate") * 100).toFixed(1)}%, ${n("gbPerToken").toFixed(3)} GB read per token`,
+    "The exact reference maps the whole file, so the OS cache is warm: time is not reported here."
+  ].join("\n"));
+  return 0;
+}
 async function streamCmd(io, args, file, json) {
   if (!file) throw new UsageError("usage: clutor stream <model.gguf> [--tokens N] [--cache-mb N] [--policy lru|wtinylfu|adaptive] [--smart J,M,TAU|off] [--prefetch on|off]");
   const bin = findEngine();
-  if (!bin) throw new UsageError("the native engine is not built: run `clutor engine build` (needs a C compiler)");
+  if (!bin) throw new UsageError("the native engine is not installed: run `clutor engine install` (prebuilt) or `clutor engine build` (needs a C compiler)");
   const num = (n, lo, hi) => flagInt(args, n, lo, hi);
   const pol = flagString(args, "policy");
   if (pol && !["lru", "wtinylfu", "adaptive"].includes(pol)) throw new UsageError("--policy must be lru, wtinylfu or adaptive");
@@ -2036,11 +2228,12 @@ async function streamCmd(io, args, file, json) {
     ...dn ? { dense: dn } : {},
     ...computeFlag(args) ? { compute: computeFlag(args) } : {},
     ...flagBool(args, "no-os-cache") ? { noOsCache: true } : {},
+    ...flagString(args, "trace") ? { trace: flagString(args, "trace") } : {},
     ...num("window", 1, 1e5) !== void 0 ? { window: num("window", 1, 1e5) } : {},
     ...shiftFlag(args)
   };
   const path = resolve2(io.cwd, file);
-  if (!existsSync(path)) throw new UsageError(`${path} does not exist`);
+  if (!existsSync2(path)) throw new UsageError(`${path} does not exist`);
   const r = await engineStream(bin, path, o);
   if (json) {
     io.out(JSON.stringify(r, null, 2));
@@ -2065,7 +2258,7 @@ function describeStream(r) {
     lines.push(`MEASURED  hit rate and peak RSS per window of tokens${note}:
 ${table(r.windows.map((w, i) => [`${i ? r.windows[i - 1].tokEnd + 1 : 1}-${w.tokEnd}`, pct(w.accesses ? w.hits / w.accesses : 0), `${(w.peakRssBytes / 2 ** 20).toFixed(0)} MiB`]), ["tokens", "hit rate", "peak RSS"])}`);
   }
-  lines.push(`${t.tokensPerSecond.toFixed(1)} passes per second over SYNTHETIC routing; the compute is ${r.config.computeMode === "kernel" ? `a Q4_0 x Q8_0 kernel (${r.config.computeKernel}) over the loaded bytes (${t.computeSeconds.toFixed(2)} s in total), not this model's maths` : "a checksum"}: this is not model tokens per second.`);
+  lines.push(`${t.tokensPerSecond.toFixed(1)} passes per second over ${r.provenance.routing === "real" ? "REAL (replayed) routing recorded from this model" : "SYNTHETIC routing"}; the compute is ${r.config.computeMode === "kernel" ? `a Q4_0 x Q8_0 kernel (${r.config.computeKernel}) over the loaded bytes (${t.computeSeconds.toFixed(2)} s in total), not this model's maths` : "a checksum"}: this is not model tokens per second.`);
   return lines.join("\n");
 }
 async function engineCmd(io, sub) {
@@ -2087,7 +2280,20 @@ async function engineCmd(io, sub) {
       throw e;
     }
   }
-  throw new UsageError("usage: clutor engine build | where");
+  if (sub === "install") {
+    io.err("Downloading the prebuilt native engine and checking its SHA-256...");
+    try {
+      io.out(`Installed ${await installPrebuilt(version())}`);
+      return 0;
+    } catch (e) {
+      if (e instanceof EngineError) {
+        io.err(e.message);
+        return 1;
+      }
+      throw e;
+    }
+  }
+  throw new UsageError("usage: clutor engine install | build | where");
 }
 async function engineSlashCommand(io, config, what) {
   const file = config.backend.llamaServer.model;
@@ -2156,8 +2362,11 @@ export {
   buildEngine,
   engineInfo,
   engineStream,
+  engineRun,
+  enginePlatform,
+  installPrebuilt,
   version,
   main,
   startBackendIfConfigured
 };
-//# sourceMappingURL=chunk-6WAEQCCP.js.map
+//# sourceMappingURL=chunk-2FBPYNHP.js.map