@clutor/cli 0.1.1 → 0.2.0

package/dist/{chunk-YL63VENN.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, existsSync } 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 {
@@ -1222,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) {
@@ -1238,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 as existsSync2, 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 {
@@ -1292,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
@@ -1320,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":
@@ -1329,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":
@@ -1377,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 (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")}.`);
@@ -1502,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 });
@@ -1516,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) {
@@ -1958,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;
@@ -2017,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");
@@ -2040,6 +2228,7 @@ 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)
   };
@@ -2069,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) {
@@ -2091,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;
@@ -2160,8 +2362,11 @@ export {
   buildEngine,
   engineInfo,
   engineStream,
+  engineRun,
+  enginePlatform,
+  installPrebuilt,
   version,
   main,
   startBackendIfConfigured
 };
-//# sourceMappingURL=chunk-YL63VENN.js.map
+//# sourceMappingURL=chunk-2FBPYNHP.js.map