mlx-bun 0.5.0 → 1.0.0

package/package.json

@@ -1,45 +1,62 @@
 {
   "name": "mlx-bun",
-  "version": "0.5.0",
-  "description": "Native MLX inference for Bun on Apple Silicon \u2014 local LLM server (OpenAI/Anthropic-compatible) and TypeScript library. No Python.",
-  "type": "module",
+  "version": "1.0.0",
+  "description": "Local AI on Apple Silicon",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/joshuarossi/mlx-bun.git"
-  },
-  "homepage": "https://github.com/joshuarossi/mlx-bun#readme",
-  "bugs": "https://github.com/joshuarossi/mlx-bun/issues",
-  "keywords": [
-    "mlx",
-    "llm",
-    "apple-silicon",
-    "metal",
-    "bun",
-    "local-inference",
-    "gemma",
-    "openai-compatible",
-    "anthropic"
-  ],
+  "type": "module",
   "bin": {
-    "mlx-bun": "bin/mlx-bun.mjs"
+    "mlx-bun": "./bin/mlx-bun.mjs",
+    "mlx-bun.server": "./bin/mlx-bun.server.mjs",
+    "mlx-bun.generate": "./bin/mlx-bun.generate.mjs",
+    "mlx-bun.convert": "./bin/mlx-bun.convert.mjs",
+    "mlx-bun.fuse": "./bin/mlx-bun.fuse.mjs",
+    "mlx-bun.lora": "./bin/mlx-bun.lora.mjs",
+    "mlx-bun.upload": "./bin/mlx-bun.upload.mjs"
   },
   "exports": {
-    ".": "./src/index.ts",
     "./package.json": "./package.json",
-    "./engine": "./src/library.ts",
-    "./client": "./src/client.ts"
+    "./client": "./src/server/client.ts",
+    "./engine": "./src/cli/engine-entry.ts",
+    "./selection": "./src/cli/model-choice.ts",
+    "./server": "./src/cli/server-entry.ts"
+  },
+  "engines": {
+    "bun": ">=1.4.2"
   },
   "files": [
     "bin",
     "src",
-    "docs",
-    "README.md",
-    "LICENSE",
-    "THIRD_PARTY_LICENSES.md"
+    "dist/web",
+    "THIRD_PARTY_NOTICES.md"
   ],
-  "engines": {
-    "bun": ">=1.4.0"
+  "scripts": {
+    "typecheck": "bun ../../scripts/typecheck.ts --noEmit && bun ../../scripts/typecheck.ts --project tsconfig.browser.json",
+    "test": "bun test",
+    "build:web": "bun scripts/build-web.ts",
+    "prepack": "bun run build:web"
+  },
+  "dependencies": {
+    "@earendil-works/pi-ai": "0.80.3",
+    "@earendil-works/pi-coding-agent": "0.80.3",
+    "@mlx-bun/app-core": "1.0.0",
+    "@mlx-bun/app-host": "1.0.0",
+    "@mlx-bun/app-services": "1.0.0",
+    "@mlx-bun/hub": "1.0.0",
+    "@mlx-bun/inference": "1.0.0",
+    "@mlx-bun/mlx": "1.0.0",
+    "@mlx-bun/module-benchmarks": "1.0.0",
+    "@mlx-bun/module-chat": "1.0.0",
+    "@mlx-bun/module-datasets": "1.0.0",
+    "@mlx-bun/module-memory": "1.0.0",
+    "@mlx-bun/module-metrics": "1.0.0",
+    "@mlx-bun/module-models": "1.0.0",
+    "@mlx-bun/module-quantize": "1.0.0",
+    "@mlx-bun/module-train": "1.0.0",
+    "@mlx-bun/module-transcription": "1.0.0",
+    "@mlx-bun/quantize": "1.0.0",
+    "@mlx-bun/training": "1.0.0",
+    "@mlx-bun/web-shell": "1.0.0",
+    "typebox": "1.1.38"
   },
   "os": [
     "darwin"
@@ -47,29 +64,9 @@
   "cpu": [
     "arm64"
   ],
-  "scripts": {
-    "test": "bash scripts/test.sh",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.web.json --noEmit && tsc -p src/contracts/tsconfig.json --noEmit",
-    "link-cli": "chmod +x src/cli.ts && ln -sf $PWD/src/cli.ts $HOME/.bun/bin/mlx-bun && mlx-bun --version",
-    "build:binary": "sh scripts/build-binary.sh",
-    "release": "PUBLISH=1 sh scripts/release-binary.sh",
-    "publish:npm": "bun publish",
-    "clean": "bun scripts/clean.ts"
-  },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.104.1",
-    "@types/bun": "^1.3.14",
-    "happy-dom": "^20.10.6",
-    "openai": "^6.42.0",
-    "typescript": "6.0.3"
-  },
-  "dependencies": {
-    "@earendil-works/pi-ai": "0.80.3",
-    "@earendil-works/pi-coding-agent": "0.80.3",
-    "@huggingface/jinja": "^0.5.9",
-    "@huggingface/tokenizers": "^0.1.3",
-    "@mlc-ai/web-xgrammar": "^0.1.27",
-    "fast-png": "^8.0.0",
-    "typebox": "1.1.38"
+    "@typesafe-ai/sdk": "0.7.0",
+    "happy-dom": "20.10.6",
+    "openai": "7.34.0"
   }
 }

package/src/cli/ane-install.ts

@@ -0,0 +1,76 @@
+// The Neural Engine install step as the app runs it. `mlx-bun compile-ane` checks every Neural Engine program the
+// shipped compositions load on this Mac against the system's compile cache and compiles the ones it lacks
+// (`compileAnePrograms` from the inference library). The installer runs the verb after placing a new bundle, and the
+// app runs it quietly before every model load (`ensureAneInstall`), in a child process of this executable: a cached
+// program costs one cache check, and a program the system removed from its cache, or one no installer compiled
+// (Homebrew, npm), is compiled again before the model loads. The model load itself never compiles: a program missing
+// there fails it with AneBridgeError naming this verb, which only a load that skipped this step (a library host
+// through `mlx-bun/engine`) can meet. The cache is per code-signing identity, so the child is this executable, and the
+// check runs in the child so a serving parent that holds no model loads no native library.
+import { fileURLToPath } from "node:url";
+import { executablePath } from "../jobs/executable";
+import type { CommandArgs } from "./args";
+
+const duration = (ms: number) => ms >= 1000 ? `${(ms / 1000).toFixed(1)} s` : `${ms.toFixed(ms < 10 ? 1 : 0)} ms`;
+
+/** `mlx-bun compile-ane`: compile what the cache lacks (or, with `--check`, only list). `--quiet` prints only the
+ * programs it compiles. Returns the exit code: 0, or 1 when `--check` finds a program the cache lacks. A refused
+ * compile throws `AneBridgeError`. */
+export async function runCompileAne(args: CommandArgs, log: (line: string) => void = console.log): Promise<number> {
+  const { aneInstallPrograms, aneInstallStatus, compileAnePrograms, machineComposition } = await import("@mlx-bun/inference/models");
+  const composition = machineComposition();
+  const where = `${composition.device}, ${composition.prefillChunkTokens}-token prompt chunks`;
+  const used = (graphs: readonly string[]) => `(${graphs.join(", ")})`;
+  const quiet = !!args.values.quiet;
+  if (!aneInstallPrograms({ composition }).length) {
+    if (!quiet) log(`No model mlx-bun ships for this Mac uses the Neural Engine (${where}); nothing to compile.`);
+    return 0;
+  }
+  if (args.values.check) {
+    const status = aneInstallStatus({ composition });
+    log(`Neural Engine programs on this Mac (${where}):`);
+    for (const program of status) log(`  ${program.cached ? "compiled" : "missing "}  ${program.spec.label} ${used(program.graphs)}`);
+    if (status.every(program => program.cached)) return 0;
+    log("Run mlx-bun compile-ane to compile the missing programs.");
+    return 1;
+  }
+  let announced = false;
+  const announce = () => {
+    if (!announced) log(`Compiling the Neural Engine programs this Mac's models use (${where}):`);
+    announced = true;
+  };
+  if (!quiet) announce();
+  compileAnePrograms({ composition, onProgram: result => {
+    if (quiet && result.status === "cached") return;
+    announce();
+    log(`  ${result.status === "compiled" ? "compiled" : "cached  "}  ${result.spec.label} in ${duration(result.milliseconds)} ${used(result.graphs)}`);
+  } });
+  return 0;
+}
+
+export interface AneInstallDependencies {
+  /** Runs `mlx-bun compile-ane --quiet` in a child process of this executable and resolves its exit code. */
+  run(): Promise<number>;
+  error(message: string): void;
+}
+
+const defaults: AneInstallDependencies = {
+  async run() {
+    const entry = fileURLToPath(new URL("./main.ts", import.meta.url));
+    const verb = ["compile-ane", "--quiet"];
+    const command = entry.includes("$bunfs") ? [executablePath, ...verb] : [executablePath, entry, ...verb];
+    return await Bun.spawn(command, { stdin: "ignore", stdout: "inherit", stderr: "inherit" }).exited;
+  },
+  error: message => console.error(message),
+};
+
+/** The app's startup step, before every model load: checks each Neural Engine program this Mac's compositions load
+ * and compiles the ones the cache lacks, in a child process (silent when every program is cached). A failed step is
+ * reported and the launch goes on; a model whose composition loads a missing program then fails its load, naming the
+ * verb. */
+export async function ensureAneInstall(supplied: Partial<AneInstallDependencies> = {}): Promise<void> {
+  const deps = { ...defaults, ...supplied };
+  const code = await deps.run();
+  if (code !== 0)
+    deps.error(`mlx-bun: the Neural Engine install step failed (exit ${code}); a model that uses the Neural Engine will not load until \`mlx-bun compile-ane\` succeeds`);
+}

package/src/cli/args.ts

@@ -0,0 +1,179 @@
+import { parseArgs } from "node:util";
+import { verbHelp } from "@mlx-bun/app-services/verbs";
+import { PROGRAM, installedVerbs } from "./module-verbs";
+
+// One small source for parsing and help; no command registration framework.
+// `setup` is main's true alias of `memory` (`mlx-bun setup init` == `mlx-bun memory init`).
+const commands = {
+  serve: { description: "Serve a local model with continuous batching and the web app", positional: "[query]", options: {
+    model: { type: "string", description: "Model directory or cached registry query (overrides positional query)" },
+    query: { type: "string", description: "Cached model query when no positional/model override is supplied" },
+    host: { type: "string", description: "Bind address [default: 127.0.0.1]" },
+    port: { type: "string", description: "Listen port; 0 chooses a free port [default: 8080]" },
+    batch: { type: "string", description: "Continuous batching capacity, including at 1 [default: 8]" },
+    "decode-concurrency": { type: "string", description: "Alias for --batch (main's spelling); the same continuous capacity" },
+    "max-tokens": { type: "string", description: "Default completion cap when a request omits one" },
+    thinking: { type: "string", description: "Default thinking mode: on | off; requests may override" },
+    temperature: { type: "string", description: "Default sampling temperature [0..5]" },
+    temp: { type: "string", description: "Alias for --temperature" },
+    "top-p": { type: "string", description: "Default nucleus sampling [0..1]" },
+    "top-k": { type: "string", description: "Default top-k sampling" },
+    "kv-quant": { type: "string", description: "KV quantization: off | config | 4 | 8 | turbo[:k<bits>v<bits>] (turbo is k8v3); config without the model's kv_config.json stays bf16, and a scheme the model's cache cannot take is refused at startup [default: off]" },
+    l1: { type: "boolean", description: "Numerical preset: KV off, unfused SDPA (the default); explicit KV/kernel flags override" },
+    l2: { type: "boolean", description: "Numerical preset: model-config KV, fused SDPA; wins over --l1, explicit KV/kernel flags override" },
+    "fused-sdpa": { type: "string", description: "Startup SDPA override: on | off [default: on for KV config, off otherwise]" },
+    "kv-budget": { type: "string", description: "Aggregate batch KV budget, decimal GB; unset means no budget" },
+    "prompt-cache": { type: "string", description: "RAM prompt cache cap, GiB; 0 disables [default: 8 GB]" },
+    "ssd-cache": { type: "string", description: "Saved prompt/KV state directory, or off to disable it [default: MLX_BUN_HOME/kv]; one directory per model identity, so a model returns to its saved state" },
+    "ssd-cache-max": { type: "string", description: "Byte budget for the whole saved-state directory across every model, GiB; 0 means unlimited [default: 20]" },
+    "ssd-cache-verify": { type: "boolean", description: "Verify tensor hashes on SSD restores" },
+    "ssd-demote-idle": { type: "string", description: "Idle seconds before SSD demotion; 0 disables [default: 300]" },
+    "generation-checkpoint": { type: "string", description: "Checkpoint every N generated tokens into the saved state" },
+    "memory-budget": { type: "string", description: "Admission-control memory budget, decimal GB; requests that cannot fit are rejected instead of crashing the GPU" },
+    "model-budget": { type: "string", description: "What all resident models may use together, decimal GB: a model that fits loads beside the others, otherwise the least recently used one is drained, its saved state flushed, and released first [default: 70% of the GPU's recommended working set]" },
+    "context-length": { type: "string", description: "Context tokens a memory-planning runtime reserves [default: its preset]; models without a plan ignore it" },
+    "force-wire": { type: "boolean", description: "Wire weights into memory at load" },
+    "expert-offload": { type: "boolean", description: "MoE only: serve experts from a page-aligned file mmap built on first use" },
+    "allow-private-media": { type: "boolean", description: "Let image_url/audio_url parts fetch from private, loopback, and link-local hosts" },
+    "hlg-sampling": { type: "string", description: "Piecewise tone-curve (HLG) sampling: on | off [default: off]" },
+    "hlg-width": { type: "string", description: "HLG mid-region half-width, nats [default: 4]" },
+    "hlg-shoulder": { type: "string", description: "HLG highlight rolloff scale, nats [default: 4]" },
+    "hlg-toe": { type: "string", description: "HLG shadow rolloff scale, nats [default: 6]" },
+    "hlg-pivot-offset": { type: "string", description: "HLG pivot: nats below the top token [default: 6]" },
+    "draft-model": { type: "string", description: "Speculative decoding draft: a path or cached query resolved like the main model; kind auto-detected" },
+    "draft-kind": { type: "string", description: "Draft kind override: two-model | assistant | dspark | deepspec | mtp | ngram (ngram is model-free; mtp alone mounts <model>/mtp/)" },
+    "num-draft-tokens": { type: "string", description: "Drafts per verify round: an integer >= 1, or adaptive (each round's count, from none up to the drafter's width or the width the graph measured for its kind, from recent acceptance and the graph's measured verify costs; needs a graph measured on this machine) [default: 3; ngram: 10]" },
+    "ngram-max": { type: "string", description: "Prompt-lookup longest k-gram, integer >= 1 (ngram only) [default: 3]" },
+    "ngram-min": { type: "string", description: "Prompt-lookup shortest k-gram, integer >= 1 (ngram only) [default: 1]" },
+    mtp: { type: "string", description: "Checkpoint-native multi-token-prediction draft head: on | off [default: on]; models without one ignore it" },
+    "paged-kv": { type: "boolean", description: "Paged KV cache, composed when the model loads (env mirror MLX_BUN_PAGED_KV=1): every request keeps its full-attention keys and values in fixed blocks, stored as --kv-quant names for each layer" },
+    "paged-kv-block-size": { type: "string", description: "Tokens per KV block with --paged-kv, integer >= 1 [default: 256]" },
+    "paged-kv-direct": { type: "boolean", description: "With --paged-kv, read at most eight queries (decode, short prefill and verification windows) with the direct Metal kernel over the blocks (Lab numerics) instead of gathered blocks through the fused SDPA; TurboQuant pages and affine widths that straddle a 32-bit word read gathered" },
+    adapter: { type: "string", description: "Mount a LoRA adapter directory at startup as the default for requests without an adapter field" },
+    "adapter-path": { type: "string", description: "Alias for --adapter (mlx_lm spelling)" },
+    "whisper-model": { type: "string", description: "Whisper checkpoint (path or cached query) for /v1/audio/* beside the chat model [default: the first downloaded whisper model, resolved on the first request]; serving a Whisper checkpoint ALONE starts a transcription-only server" },
+    "whisper-idle-unload": { type: "string", description: "Seconds the Whisper weights stay loaded after a take; 0 releases them right after every take [default: 0]" },
+    "whisper-resident": { type: "boolean", description: "Never release the Whisper weights" },
+    preload: { type: "boolean", description: "Transcription-only server: load the Whisper weights before listening instead of on the first request" },
+    "no-open": { type: "boolean", description: "Do not open the web app in an interactive terminal" },
+    "in-process": { type: "boolean", description: "Load the models in this process instead of one worker process per resident model. Isolated serving is the default: this process keeps the app, web chat and jobs and loads no model, each worker is crash-isolated and respawns after a crash, and the workers are held by memory fit (--model-budget)" },
+    isolate: { type: "boolean", description: "Deprecated, accepted and ignored: isolated serving is the default (see --in-process)" },
+  } },
+  generate: { description: "Generate text once from a local model", positional: "[query] [prompt]", options: {
+    query: { type: "string", description: "Cached model query when no positional query is supplied" },
+    prompt: { type: "string", description: "Prompt text (or second positional argument); - reads stdin" },
+    "system-prompt": { type: "string", description: "System message placed before the prompt in the chat template (ignored with --raw)" },
+    raw: { type: "boolean", description: "Skip the chat template and tokenize the prompt verbatim" },
+    "max-tokens": { type: "string", description: "Completion cap [default: 256]" },
+    temperature: { type: "string", description: "Sampling temperature [default: 0]" },
+    temp: { type: "string", description: "Alias for --temperature" },
+    "top-p": { type: "string", description: "Nucleus sampling" },
+    "top-k": { type: "string", description: "Top-k sampling" },
+    "min-p": { type: "string", description: "Min-p sampling: keep tokens with probability >= min-p times the top token's [0..1]" },
+    "min-tokens-to-keep": { type: "string", description: "Tokens min-p never filters out, integer >= 1 [default: 1]" },
+    "xtc-probability": { type: "string", description: "Probability per step of XTC (exclude top choices) sampling [0..1]" },
+    "xtc-threshold": { type: "string", description: "Probability a token must exceed to be an XTC removal candidate [0..0.5]" },
+    adapter: { type: "string", description: "Mount a LoRA adapter directory for this generation" },
+    "adapter-path": { type: "string", description: "Alias for --adapter (mlx_lm spelling)" },
+    seed: { type: "string", description: "Sampler seed" },
+    "kv-quant": { type: "string", description: "KV quantization: off | config | 4 | 8 | turbo[:k<bits>v<bits>] (turbo is k8v3); config without the model's kv_config.json stays bf16, and a scheme the model's cache cannot take is refused at startup [default: off]" },
+    "quantized-kv-start": { type: "string", description: "Token count at which KV quantization starts with --kv-quant 4 | 8 | turbo | config [default: 0]" },
+    l1: { type: "boolean", description: "Numerical preset: KV off, unfused SDPA (the default); explicit KV/kernel flags override" },
+    l2: { type: "boolean", description: "Numerical preset: model-config KV, fused SDPA; wins over --l1, explicit KV/kernel flags override" },
+    "fused-sdpa": { type: "string", description: "Startup SDPA override: on | off [default: on for KV config, off otherwise]" },
+  } },
+  embed: { description: "Embed local text and print vectors", positional: "[query] [text]", options: {
+    query: { type: "string", description: "Cached model query; defaults to the first downloaded embedding model" },
+    text: { type: "string", description: "Text to embed; otherwise second positional or nonempty stdin lines" },
+    instruct: { type: "string", description: "Query instruction; omit for document embeddings" },
+    json: { type: "boolean", description: "Print one OpenAI-style embedding list instead of one vector per line" },
+  } },
+  perplexity: { description: "Perplexity of a model over a local text/JSONL dataset", positional: "[query]",
+    usage: "usage: mlx-bun perplexity <model-query-or-path> --data-path <file.txt|file.jsonl> [--sequence-length 512] [--num-samples 256] [--batch-size 8] [--seed 123]",
+    details: "mlx_lm.perplexity methodology, exactly: samples are visited in a seeded random order, tokenized,\nconcatenated, and cut into NON-OVERLAPPING rows of --sequence-length tokens; per batch the model\nscores rows[:, :-1] against rows[:, 1:] in f32 (every position counts); reported as\nppl = exp(mean CE) ± the delta-method standard error. The one deliberate difference: the data\nsource is a LOCAL file (never a Hugging Face dataset download).", options: {
+    model: { type: "string", description: "Model directory or cached registry query (mlx_lm spelling of the positional)" },
+    query: { type: "string", description: "Cached model query when no positional is supplied" },
+    "data-path": { type: "string", description: ".jsonl ({\"text\": …} rows) or plain .txt (required)" },
+    "sequence-length": { type: "string", description: "Tokens per row [default: 512]" },
+    "num-samples": { type: "string", description: "Rows to score; -1 = all available [default: 256]" },
+    "batch-size": { type: "string", description: "Rows per forward [default: 8]" },
+    seed: { type: "string", description: "Sample-shuffle seed [default: 123]" },
+  } },
+  "compile-ane": { description: "Compile the Neural Engine programs this Mac's models use that the system cache lacks (the install step)", positional: "",
+    details: "Checks every Neural Engine program the models mlx-bun ships load on this Mac against the system's compile\ncache, compiles the ones it lacks, then exits. The installer runs it, and the app runs it quietly before\nevery model load, so a program the system removed from its cache is compiled again first. Loading a model\nonly loads its programs from the cache (about 4 ms each) and never compiles: a model whose program is\nmissing fails to load and names this command. The cache belongs to the executable that compiled it, so run\nthe same mlx-bun that serves. Programs are built for the prefill chunk size (MLX_BUN_RD_PREFILL_CHUNK), so\nrun it in the environment you serve in.", options: {
+    check: { type: "boolean", description: "List each program and whether the compile cache holds it; compile nothing (exit 1 when one is missing)" },
+    quiet: { type: "boolean", description: "Print only the programs it compiles (nothing when every program is cached)" },
+  } },
+} satisfies Record<string, { description: string; positional: string; usage?: string; details?: string; options: Record<string, { type: "string" | "boolean"; description: string; short?: string }> }>;
+export type Command = keyof typeof commands;
+export type CommandArgs = { values: Record<string, string | boolean | undefined>; positionals: string[] };
+export function isCommand(name: string): name is Command { return Object.hasOwn(commands, name); }
+
+/** Bare and option-first invocations start the app; explicit verbs keep their arguments. */
+export function commandInvocation(argv: string[]): { command: string; args: string[] } {
+  const [first, ...rest] = argv;
+  const command = !first || (first.startsWith("--") && !["--help", "--version"].includes(first)) ? "serve" : first;
+  return { command: command === "gen" ? "generate" : command, args: command === "serve" && first !== "serve" ? argv : rest };
+}
+
+/** The verb's usage line: table-supplied, else derived from its positional. */
+export function usage(command: Command): string {
+  return (commands[command] as { usage?: string }).usage ?? `usage: mlx-bun ${command} ${commands[command].positional}`;
+}
+
+/** A verb's option table (name → type, short); the alias parser reads the same one. A module's verb reads from its manifest. */
+export function commandOptions(command: string): Record<string, { type: "string" | "boolean"; short?: string }> {
+  if (isCommand(command)) return commands[command].options;
+  const spec = installedVerbs().get(command);
+  if (!spec) throw new Error(`Unknown command: ${command}`);
+  return Object.fromEntries(spec.options.map(option => [option.name, { type: option.type === "boolean" ? "boolean" as const : "string" as const,
+    ...(option.short ? { short: option.short } : {}) }]));
+}
+
+/** The positional-count and required-positional rules shared by every way of building a verb's arguments. */
+export function checkPositionals(command: Command, parsed: CommandArgs): void {
+  const max = command === "generate" || command === "embed" ? 2 : commands[command].positional ? 1 : 0;
+  if (parsed.positionals.length > max) throw new Error(`Too many arguments for ${command}`);
+  if (commands[command].positional.startsWith("<") && !parsed.positionals.length) throw new Error(usage(command));
+}
+
+function joinDashValues(args: string[], options: Record<string, { type: "string" | "boolean" }>): string[] {
+  const joined: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!, next = args[i + 1];
+    if (arg.startsWith("--") && options[arg.slice(2)]?.type === "string" && next !== undefined && /^-\d/.test(next)) joined.push(`${arg}=${next}`), i++;
+    else joined.push(arg);
+  }
+  return joined;
+}
+
+export function parseCommand(command: Command, args: string[]): CommandArgs {
+  const options: Record<string, { type: "string" | "boolean"; short?: string }> = commands[command].options;
+  // Main's parser took a dash-led value (`--num-samples -1`); node's reads one only as `--num-samples=-1`.
+  if (command === "perplexity") args = joinDashValues(args, options);
+  let parsed: CommandArgs;
+  try { parsed = parseArgs({ args, options, allowPositionals: true, strict: true }); }
+  catch (error) {
+    // A verb with its own usage line answers a valueless option the way main did.
+    if ("usage" in commands[command] && (error as { code?: string }).code === "ERR_PARSE_ARGS_INVALID_OPTION_VALUE")
+      throw new Error(usage(command));
+    throw error;
+  }
+  checkPositionals(command, parsed);
+  return parsed;
+}
+
+export function help(command?: string): string {
+  if (command === "gen") command = "generate";
+  // The built-in verbs, then the installed modules' (`src/modules.ts`).
+  const verbs = installedVerbs(), listed = [...Object.entries(commands).map(([name, info]) => [name, info.description] as const),
+    ...[...verbs].map(([name, spec]) => [name, spec.summary] as const)];
+  const column = Math.max(...listed.map(([name]) => name.length));
+  if (!command) return `mlx-bun — local AI on Apple Silicon\n\nUsage: mlx-bun [options]\n       mlx-bun serve [query] [options]\n       mlx-bun <command> [options]\n\nCommands:\n${listed.map(([name, description]) => `  ${name.padEnd(column)} ${description}`).join("\n")}\n\nOptions:\n  -h, --help     Show help\n  -v, --version  Show version\n\nWith no command, start the server and web app using a cached model.\nRun mlx-bun serve --help for serving options.`;
+  const verb = verbs.get(command);
+  if (verb) return verbHelp(PROGRAM, verb);
+  if (!isCommand(command)) throw new Error(`Unknown command: ${command}`);
+  const info = commands[command];
+  const details = (info as { details?: string }).details;
+  return `mlx-bun ${command} — ${info.description}\n\nUsage: mlx-bun ${command}${info.positional ? ` ${info.positional}` : ""} [options]\n${details ? `\n${details}\n` : ""}\nOptions:\n${Object.entries(info.options).map(([name, option]: [string, { type: string; description: string; short?: string }]) => `  ${((option.short ? `-${option.short}, ` : "") + `--${name}` + (option.type === "string" ? " <value>" : "")).padEnd(24)} ${option.description}`).join("\n")}\n  -h, --help               Show help`;
+}

package/src/cli/engine-entry.ts

@@ -0,0 +1,68 @@
+// The public `mlx-bun/engine` entry (main's src/library.ts without
+// `initializeMlx`): the embedding client, the portable token-session API, and
+// `openIsolatedHost`, which owns one full-app worker process. Loading it loads
+// no native module and starts nothing; the worker's composition is imported
+// only when a host is opened (library-host.ts).
+import type { EngineHost } from "../server/client";
+
+export { createCompletionClient, createDirectHost } from "../server/client";
+export type { BatchCompletionClient, CompletionCall, CompletionClient, CompletionResponse, EngineHost, TaskClient } from "../server/client";
+export { createInferenceEngine } from "@mlx-bun/inference/execution/engine";
+export { CancellationSource } from "@mlx-bun/inference/execution/cancellation";
+export type {
+  CancelReason, Cancellation, ExecutionPlan, ExecutionPlanner, GenerationEvent, GenerationOutcome, GenerationOutput,
+  GenerationSession, InferenceEngine, InferenceMethod, MethodResult, MethodRun, RunControl, SessionState, Timer, TokenLogprobs,
+} from "@mlx-bun/inference/contracts/portable";
+
+/**
+ * Start one mlx-bun app worker on a private Unix socket, running
+ * `serve --model <model> ...arguments` through the CLI's own composition, and
+ * resolve once it serves. The host forwards to the whole app.
+ *
+ * Refused before anything is spawned: a blank `model` (an empty query would
+ * select a model automatically and may download the starter model), and any
+ * `arguments` the CLI refuses. `--host`,
+ * `--port`, and `--no-open` are accepted and do not affect the socket.
+ *
+ * `command` is the program and leading arguments of an mlx-bun CLI of this
+ * package version (the installed binary, `[bun, <package>/bin/mlx-bun.mjs]`, or
+ * `[bun, <package>/src/cli/main.ts]`), spawned as `[...command, "__worker"]`.
+ * An empty command is refused ("engine command must not be empty"). Omitted, it
+ * is this package's CLI source under the current Bun, except in a compiled
+ * consumer, which must supply one ("a compiled library consumer must supply
+ * the mlx-bun executable as command"). A CLI of another package version
+ * refuses the launch ("worker protocol version mismatch"); two builds with the
+ * same package version are not told apart.
+ *
+ * A worker that fails before ready (a load failure, a refused launch, or
+ * `readyTimeoutMs`, default 15 minutes) is stopped, its socket directory
+ * removed, and the returned promise rejects with its error. A crash after
+ * ready respawns within the CLI's restart budget.
+ *
+ * The host:
+ * - `ready` follows the current worker: pending during a respawn, rejected
+ *   ("engine restart limit reached") once the budget is spent, and rejected
+ *   ("engine host is closed") after `close()`.
+ * - `forward(request)` waits for a serving worker and sends nothing while it
+ *   waits; an aborted request rejects with its signal's reason. Hop-by-hop
+ *   headers are stripped both ways and both bodies stream. A GET or HEAD that
+ *   fails is retried once after 250 ms; nothing else is replayed. After
+ *   `close()` it rejects ("engine host is closed").
+ * - `close()` returns one promise however often it is called: it aborts
+ *   requests in flight, drains and stops the worker (SIGTERM, then SIGKILL
+ *   after the CLI's shutdown deadline, `MLX_BUN_SHUTDOWN_TIMEOUT_MS`), waits
+ *   for its exit, and then removes the socket directory.
+ *
+ * The worker's stdout and stderr lines reach this process's `console.log` and
+ * `console.error`; restart notices go to `console.error`.
+ */
+export async function openIsolatedHost(model: string, options: {
+  /** Serve arguments after `--model <model>`, as `mlx-bun serve` takes them. */
+  arguments?: readonly string[];
+  /** The mlx-bun CLI to run as the worker; required in a compiled consumer. */
+  command?: readonly string[];
+  /** How long the worker may take to report ready; default 15 minutes. */
+  readyTimeoutMs?: number;
+} = {}): Promise<EngineHost<Request, Response>> {
+  return (await import("./library-host")).openLibraryHost(model, options);
+}