@clutor/cli 0.1.1 → 0.3.0

package/dist/{chunk-RBSFKJ6L.js → chunk-BZZUO7XX.js}

@@ -6,6 +6,38 @@ import {
 
 // src/repl.ts
 import { TOOLS } from "@clutor/core";
+
+// src/banner.ts
+var GLYPHS = {
+  C: [" \u2588\u2588\u2588\u2588\u2588\u2588\u2557", "\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D", "\u2588\u2588\u2551     ", "\u2588\u2588\u2551     ", "\u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2557", " \u255A\u2550\u2550\u2550\u2550\u2550\u255D"],
+  L: ["\u2588\u2588\u2557     ", "\u2588\u2588\u2551     ", "\u2588\u2588\u2551     ", "\u2588\u2588\u2551     ", "\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557", "\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D"],
+  U: ["\u2588\u2588\u2557   \u2588\u2588\u2557", "\u2588\u2588\u2551   \u2588\u2588\u2551", "\u2588\u2588\u2551   \u2588\u2588\u2551", "\u2588\u2588\u2551   \u2588\u2588\u2551", "\u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D", " \u255A\u2550\u2550\u2550\u2550\u2550\u255D "],
+  T: ["\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557", "\u255A\u2550\u2550\u2588\u2588\u2554\u2550\u2550\u255D", "   \u2588\u2588\u2551   ", "   \u2588\u2588\u2551   ", "   \u2588\u2588\u2551   ", "   \u255A\u2550\u255D   "],
+  O: [" \u2588\u2588\u2588\u2588\u2588\u2588\u2557 ", "\u2588\u2588\u2554\u2550\u2550\u2550\u2588\u2588\u2557", "\u2588\u2588\u2551   \u2588\u2588\u2551", "\u2588\u2588\u2551   \u2588\u2588\u2551", "\u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D", " \u255A\u2550\u2550\u2550\u2550\u2550\u255D "],
+  R: ["\u2588\u2588\u2588\u2588\u2588\u2588\u2557 ", "\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557", "\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D", "\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557", "\u2588\u2588\u2551  \u2588\u2588\u2551", "\u255A\u2550\u255D  \u255A\u2550\u255D"]
+};
+var WORDMARK = Array.from({ length: 6 }, (_, row) => [..."CLUTOR"].map((ch) => GLYPHS[ch]?.[row] ?? "").join(""));
+var WORDMARK_WIDTH = Math.max(...WORDMARK.map((r) => r.length));
+var GRADIENT = [51, 45, 39, 33, 63, 99];
+function useColor(env = process.env, isTTY = !!process.stdout.isTTY) {
+  return isTTY && !("NO_COLOR" in env) && env["TERM"] !== "dumb";
+}
+function banner(o) {
+  const paint = (code, s) => o.color ? `\x1B[${typeof code === "number" ? `38;5;${code}` : code}m${s}\x1B[0m` : s;
+  const dim = (s) => paint("2", s);
+  const wide = (o.columns ?? 80) >= WORDMARK_WIDTH + 2;
+  const lines = [""];
+  if (wide) lines.push(...WORDMARK.map((r, i) => paint(GRADIENT[i] ?? 99, r)));
+  else lines.push(paint(45, "C L U T O R"));
+  lines.push("", `${paint("1", "clutor interactive session")} ${dim(`v${o.version}`)}`, dim("big models on small machines, with honest numbers"), "");
+  lines.push(`  ${dim("folder")}  ${o.folder}`, `  ${dim("model")}   ${o.model}`, "");
+  lines.push(`  ${dim("tips")}    type a task in plain words and the agent works on this folder`);
+  lines.push(`          its changes are held aside; nothing is written without your approval`);
+  lines.push(`          /help lists commands \xB7 /plan <model> \xB7 /cache \xB7 /exit`, "");
+  return lines.join("\n");
+}
+
+// src/repl.ts
 var FORWARD = {
   status: { usage: "/status", help: "machine, model backend, memory plan, receipts" },
   doctor: { usage: "/doctor", help: "check this machine and the configuration" },
@@ -60,7 +92,7 @@ function helpText() {
 
 ${table(rows)}`;
 }
-async function runRepl(io, run, engine) {
+async function runRepl(io, run, engine, version = "dev") {
   const ask = io.prompt;
   const session = { auto: false, notes: [], usage: { promptTokens: 0, completionTokens: 0 } };
   const load = () => {
@@ -73,10 +105,7 @@ async function runRepl(io, run, engine) {
   };
   const cfg = load();
   const model = (c) => !c ? "not configured" : c.backend.kind === "openai" ? `${c.backend.model ?? "default"} at ${c.backend.baseUrl}` : c.backend.llamaServer.model ?? "not configured (set backend.llamaServer.model)";
-  io.out(`clutor interactive session
-  folder  ${io.cwd}
-  model   ${model(cfg)}
-  Type a task, or /help for commands. Nothing is written to your files without your approval.`);
+  io.out(banner({ version, folder: io.cwd, model: model(cfg), columns: process.stdout.columns ?? 80, color: useColor() }));
   try {
     for (; ; ) {
       const line = (await ask("clt> ")).trim();
@@ -175,4 +204,4 @@ export {
   splitWords,
   runRepl
 };
-//# sourceMappingURL=chunk-RBSFKJ6L.js.map
+//# sourceMappingURL=chunk-BZZUO7XX.js.map

package/dist/chunk-BZZUO7XX.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/repl.ts","../src/banner.ts"],"sourcesContent":["import { TOOLS } from \"@clutor/core\";\nimport { loadConfig, ConfigError, type ClutorConfig } from \"./config\";\nimport { banner, useColor } from \"./banner\";\nimport { table } from \"./format\";\nimport type { Io, SessionState } from \"./cli\";\n\n/**\n * The interactive session that `clutor` opens when it is started with no command in a terminal. Text you type is a task for the coding\n * agent (its changes are held aside until you approve them); a line starting with `/` is a command. Most commands are the ordinary\n * clutor commands, so they behave exactly as they do outside the session.\n */\n\ntype Run = (argv: string[], session: SessionState) => Promise<number>;\ntype EngineView = (config: ClutorConfig, what: \"layers\" | \"cache\") => Promise<void>;\n\ninterface Slash { usage: string; help: string }\n\n/** Commands that are forwarded unchanged to the normal CLI. */\nconst FORWARD: Record<string, Slash> = {\n  status: { usage: \"/status\", help: \"machine, model backend, memory plan, receipts\" },\n  doctor: { usage: \"/doctor\", help: \"check this machine and the configuration\" },\n  models: { usage: \"/models\", help: \"model catalog and the .gguf files in your models folder\" },\n  plan: { usage: \"/plan <model> [--ram GiB]\", help: \"will it fit, where the memory goes, how fast it could possibly run\" },\n  simulate: { usage: \"/simulate <model> [--cache GiB]\", help: \"replay a routing trace through the expert cache (synthetic)\" },\n  inspect: { usage: \"/inspect <file.gguf>\", help: \"read a model file's header\" },\n  bench: { usage: \"/bench [--file model.gguf]\", help: \"measure real disk reads; with the engine, compare cache strategies\" },\n  stream: { usage: \"/stream <model.gguf>\", help: \"stream a model's experts through the native engine (synthetic routing)\" },\n  pull: { usage: \"/pull [id]\", help: \"list or download a small test model\" },\n  init: { usage: \"/init\", help: \"create clutor.config.json and a models folder here\" },\n  backend: { usage: \"/backend\", help: \"show how llama-server would be started\" },\n  ledger: { usage: \"/ledger\", help: \"verify the receipt log and list recent tasks and checkpoints\" },\n  decide: { usage: '/decide --prompt \"<text>\" --choices \"a,b\"', help: \"one forward pass: probability of each choice\" },\n};\n\nconst OWN: Record<string, Slash> = {\n  help: { usage: \"/help\", help: \"this list\" },\n  model: { usage: \"/model\", help: \"which model this session talks to\" },\n  verify: { usage: \"/verify [command|off]\", help: \"run this check after every task and only offer changes that pass it\" },\n  yes: { usage: \"/yes\", help: \"toggle: run project commands without asking (only for projects you trust)\" },\n  undo: { usage: \"/undo\", help: \"restore the files changed by the last applied task\" },\n  tools: { usage: \"/tools\", help: \"what the agent can do\" },\n  cost: { usage: \"/cost\", help: \"tokens used this session, as reported by the model server\" },\n  history: { usage: \"/history\", help: \"tasks done in this session\" },\n  clear: { usage: \"/clear\", help: \"forget this session's task history\" },\n  layers: { usage: \"/layers\", help: \"where the model file's bytes are, per layer (native engine)\" },\n  cache: { usage: \"/cache\", help: \"a streaming pass over the model file: cache, prefetch, disk waits\" },\n  exit: { usage: \"/exit\", help: \"leave (also /quit, Ctrl-D)\" },\n};\n\n/** Splits a line into words, honouring single and double quotes. */\nexport function splitWords(line: string): string[] {\n  const out: string[] = [];\n  let cur = \"\", quote: string | undefined, has = false;\n  for (const ch of line) {\n    if (quote) { if (ch === quote) quote = undefined; else cur += ch; }\n    else if (ch === '\"' || ch === \"'\") { quote = ch; has = true; }\n    else if (/\\s/.test(ch)) { if (cur || has) out.push(cur); cur = \"\"; has = false; }\n    else cur += ch;\n  }\n  if (cur || has) out.push(cur);\n  return out;\n}\n\nfunction helpText(): string {\n  const rows = [...Object.values(OWN), ...Object.values(FORWARD)].map((c) => [c.usage, c.help]);\n  return `Type a task in plain words and the agent works on this folder. Its changes are held aside; you see the diff and approve before anything is written.\\n\\n${table(rows)}`;\n}\n\nexport async function runRepl(io: Io, run: Run, engine: EngineView, version = \"dev\"): Promise<number> {\n  const ask = io.prompt as NonNullable<Io[\"prompt\"]>;\n  const session: SessionState = { auto: false, notes: [], usage: { promptTokens: 0, completionTokens: 0 } };\n  const load = (): ClutorConfig | undefined => {\n    try { return loadConfig(io.cwd).config; } catch (e) { io.err(e instanceof ConfigError || e instanceof Error ? e.message : String(e)); return undefined; }\n  };\n  const cfg = load();\n  const model = (c: ClutorConfig | undefined): string => !c ? \"not configured\" : c.backend.kind === \"openai\" ? `${c.backend.model ?? \"default\"} at ${c.backend.baseUrl}` : c.backend.llamaServer.model ?? \"not configured (set backend.llamaServer.model)\";\n  io.out(banner({ version, folder: io.cwd, model: model(cfg), columns: process.stdout.columns ?? 80, color: useColor() }));\n\n  try {\n    for (;;) {\n      const line = (await ask(\"clt> \")).trim();\n      if (!line) continue;\n      if (!line.startsWith(\"/\")) { await guarded(io, () => run([\"code\", line, \"--dir\", io.cwd], session)); continue; }\n\n      const [word = \"\", ...rest] = splitWords(line.slice(1));\n      const name = word.toLowerCase();\n      if (name === \"exit\" || name === \"quit\") return 0;\n      if (name === \"help\" || name === \"?\") { io.out(helpText()); continue; }\n      if (name === \"model\") { io.out(`model: ${model(load())}${session.backend ? \" (running)\" : \"\"}\\nverify: ${session.verify ?? \"none\"}   auto-approve: ${session.auto ? \"on\" : \"off\"}`); continue; }\n      if (name === \"verify\") {\n        const v = rest.join(\" \").trim();\n        if (!v) io.out(session.verify ? `verify: ${session.verify}` : \"verify: none. Set one with /verify npm test\");\n        else if (v === \"off\") { delete session.verify; io.out(\"verify: off\"); }\n        else { session.verify = v; io.out(`verify: ${v}. It runs in a scratch copy after each task; changes are only offered when it passes.`); }\n        continue;\n      }\n      if (name === \"yes\") { session.auto = !session.auto; io.out(session.auto ? \"auto-approve ON: commands from the agent run without asking.\" : \"auto-approve off.\"); continue; }\n      if (name === \"undo\") {\n        if (!session.lastCheckpoint) { io.out(\"Nothing to undo in this session.\"); continue; }\n        const { id, dir } = session.lastCheckpoint;\n        if (await guarded(io, () => run([\"rollback\", id, \"--dir\", dir], session)) === 0) delete session.lastCheckpoint;\n        continue;\n      }\n      if (name === \"tools\") { io.out(table(TOOLS.map((t) => [t.name, t.description.split(\". \")[0] ?? \"\"]))); continue; }\n      if (name === \"cost\") {\n        const u = session.usage;\n        io.out(`${u.promptTokens} prompt + ${u.completionTokens} generated tokens this session (reported by the model server; local models cost no money).`);\n        continue;\n      }\n      if (name === \"history\") { io.out(session.notes.length ? session.notes.map((n, i) => `${i + 1}. ${n}`).join(\"\\n\") : \"No tasks yet.\"); continue; }\n      if (name === \"clear\") { session.notes.length = 0; io.out(\"(session history cleared)\"); continue; }\n      if (name === \"layers\" || name === \"cache\") {\n        const c = load();\n        if (c) await guarded(io, async () => { await engine(c, name); return 0; });\n        continue;\n      }\n      if (FORWARD[name]) { await guarded(io, () => run([name, ...rest], session)); continue; }\n      io.err(`unknown command /${word}. /help lists them.`);\n    }\n  } finally {\n    try { await session.backend?.stop(); } catch { /* the server may already be gone */ }\n  }\n}\n\nasync function guarded(io: Io, f: () => Promise<number>): Promise<number | undefined> {\n  try { return await f(); } catch (e) { io.err(e instanceof Error ? e.message : String(e)); return undefined; }\n}\n","/**\n * The welcome screen of the interactive session: the name in large block letters, then where you are and what to type.\n * Colour is used only on a terminal that asked for it (not when piped, not with NO_COLOR); the text is the same either way.\n */\n\nconst GLYPHS: Record<string, string[]> = {\n  C: [\" ██████╗\", \"██╔════╝\", \"██║     \", \"██║     \", \"╚██████╗\", \" ╚═════╝\"],\n  L: [\"██╗     \", \"██║     \", \"██║     \", \"██║     \", \"███████╗\", \"╚══════╝\"],\n  U: [\"██╗   ██╗\", \"██║   ██║\", \"██║   ██║\", \"██║   ██║\", \"╚██████╔╝\", \" ╚═════╝ \"],\n  T: [\"████████╗\", \"╚══██╔══╝\", \"   ██║   \", \"   ██║   \", \"   ██║   \", \"   ╚═╝   \"],\n  O: [\" ██████╗ \", \"██╔═══██╗\", \"██║   ██║\", \"██║   ██║\", \"╚██████╔╝\", \" ╚═════╝ \"],\n  R: [\"██████╗ \", \"██╔══██╗\", \"██████╔╝\", \"██╔══██╗\", \"██║  ██║\", \"╚═╝  ╚═╝\"],\n};\n\n/** The six rows of \"CLUTOR\" in block letters. */\nexport const WORDMARK: string[] = Array.from({ length: 6 }, (_, row) => [...\"CLUTOR\"].map((ch) => GLYPHS[ch]?.[row] ?? \"\").join(\"\"));\nexport const WORDMARK_WIDTH = Math.max(...WORDMARK.map((r) => r.length));\n\n/** Top to bottom: cyan, through blue, to violet (xterm 256-colour codes). */\nconst GRADIENT = [51, 45, 39, 33, 63, 99];\n\nexport interface BannerOptions {\n  version: string;\n  folder: string;\n  model: string;\n  /** Width of the terminal in columns; a narrower terminal than the block letters gets a one-line title. */\n  columns?: number;\n  color?: boolean;\n}\n\nexport function useColor(env: NodeJS.ProcessEnv = process.env, isTTY: boolean = !!process.stdout.isTTY): boolean {\n  return isTTY && !(\"NO_COLOR\" in env) && env[\"TERM\"] !== \"dumb\";\n}\n\nexport function banner(o: BannerOptions): string {\n  const paint = (code: number | string, s: string): string => (o.color ? `\\x1b[${typeof code === \"number\" ? `38;5;${code}` : code}m${s}\\x1b[0m` : s);\n  const dim = (s: string): string => paint(\"2\", s);\n  const wide = (o.columns ?? 80) >= WORDMARK_WIDTH + 2;\n  const lines: string[] = [\"\"];\n  if (wide) lines.push(...WORDMARK.map((r, i) => paint(GRADIENT[i] ?? 99, r)));\n  else lines.push(paint(45, \"C L U T O R\"));\n  lines.push(\"\", `${paint(\"1\", \"clutor interactive session\")} ${dim(`v${o.version}`)}`, dim(\"big models on small machines, with honest numbers\"), \"\");\n  lines.push(`  ${dim(\"folder\")}  ${o.folder}`, `  ${dim(\"model\")}   ${o.model}`, \"\");\n  lines.push(`  ${dim(\"tips\")}    type a task in plain words and the agent works on this folder`);\n  lines.push(`          its changes are held aside; nothing is written without your approval`);\n  lines.push(`          /help lists commands · /plan <model> · /cache · /exit`, \"\");\n  return lines.join(\"\\n\");\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-YL63VENN.js → chunk-ODS6ND7T.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,11 @@ 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: "granite-3.0-3b-a800m-q4_k_m", catalogId: "granite-3.0-3b-a800m", repo: "bartowski/granite-3.0-3b-a800m-instruct-GGUF", file: "granite-3.0-3b-a800m-instruct-Q4_K_M.gguf", bytes: 2059356e3, sha256: "aa6287bafd182d06a6d11b0d001458deec902e8c0522875fc20cde2f561ebf6d", note: "IBM Granite MoE (40 experts, 8 used, 1.9 GiB): the third architecture the engine can run with `clutor generate`" },
+  { 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-1.5b-q4_k_m", catalogId: "qwen2.5-1.5b", repo: "Qwen/Qwen2.5-1.5B-Instruct-GGUF", file: "qwen2.5-1.5b-instruct-q4_k_m.gguf", bytes: 1117320736, sha256: "6a1a2eb6d15622bf3c96857206351ba97e1af16c30d7a74ee38970e434e9407e", note: "a small dense model (1.0 GiB): the fourth architecture the engine can run with `clutor generate`" },
+  { 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 +397,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 +563,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":
@@ -925,6 +949,7 @@ function createClutorServer(o) {
         if (e instanceof DecideError) throw new HttpError(e.status, e.message);
         throw e;
       }
+      await Promise.all(ready);
       const root = roots.values().next().value;
       const receipt = root ? await sealDecision(root, model, b.prompt, b.choices, result, startedAt) : null;
       return reply(200, { choice: result.choice, probabilities: result.probabilities, probabilityMassOnChoices: result.probabilityMassOnChoices, latencyMs: result.latencyMs, receipt });
@@ -1000,8 +1025,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 +1047,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 +1159,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 +1248,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 +1265,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 +1394,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 +1426,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 +1435,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 +1487,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 +1612,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 +1626,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 +2068,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 +2127,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 +2231,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 +2261,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 +2283,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 +2365,11 @@ export {
   buildEngine,
   engineInfo,
   engineStream,
+  engineRun,
+  enginePlatform,
+  installPrebuilt,
   version,
   main,
   startBackendIfConfigured
 };
-//# sourceMappingURL=chunk-YL63VENN.js.map
+//# sourceMappingURL=chunk-ODS6ND7T.js.map