@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.11-beta.7

package/src/services/imagegen/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Local image-generation capability (WS3) — public entry point.
+ *
+ * This module is what `provider.ts` (`createImageGenerationHandler`),
+ * the UI image-gen action, and image-gen skill imports to
+ * register the capability with the WS1 MemoryArbiter.
+ *
+ * Wiring:
+ *
+ *   const arbiter = service.getMemoryArbiter();
+ *   const registration = createImageGenCapabilityRegistration({
+ *     loader: createDefaultImageGenLoader({ ... }),
+ *   });
+ *   arbiter.registerCapability(registration);
+ *
+ * `createImageGenCapabilityRegistration` wraps the underlying backend
+ * so the arbiter's `run(request)` path:
+ *
+ *   1. Calls `backend.supports(request)`. If false, the arbiter throws
+ *      `unsupported_request` so the caller can pick a different tier
+ *      or surface a clear error.
+ *   2. Calls `backend.generate(request)` and returns the result.
+ *
+ * The capability registers with `residentRole: "vision"` so image-gen
+ * co-evicts with vision-describe — both are GPU-heavy weights with
+ * comparable RAM footprints, and the arbiter's existing one-model-per-
+ * role policy gives us free serialization. A vision-describe request
+ * arriving while image-gen is in flight will queue, wait for the
+ * generate to drain, then evict the diffusion weights and load the
+ * VL weights.
+ */
+export { type AospImageGenBinding, type AospImageGenHandle, type LoadAospImageGenBackendOptions, loadAospImageGenBackend, } from "./aosp-unavailable";
+export { type ImageGenBackendChoice, type ImageGenBackendId, type ImageGenRuntimeProfile, resolveDefaultImageGenModel, selectImageGenBackends, TIER_TO_DEFAULT_IMAGE_MODEL, } from "./backend-selector";
+export { type CoreMlImageGenBridge, type LoadCoreMlImageGenBackendOptions, loadCoreMlImageGenBackend, } from "./coreml-unavailable";
+export { ImageGenBackendUnavailableError, isImageGenUnavailable, } from "./errors";
+export { loadMfluxImageGenBackend, type MfluxBackendOptions, } from "./mflux";
+export { assertPngOutput, defaultSpawn, loadSdCppImageGenBackend, PNG_SIGNATURE, pickSeed, resolveSeed, type SdCppBackendOptions, type SdCppSpawnLike, } from "./sd-cpp";
+export { loadTensorRtImageGenBackend, type TensorRtBackendOptions, } from "./tensorrt-unavailable";
+export type { ImageGenBackend, ImageGenBackendLoader, ImageGenLoadArgs, ImageGenMimeType, ImageGenRequest, ImageGenResult, } from "./types";
+import type { CapabilityRegistration } from "../memory-arbiter";
+import type { ImageGenBackend, ImageGenBackendLoader, ImageGenRequest, ImageGenResult } from "./types";
+export interface CreateImageGenCapabilityRegistrationOptions {
+    loader: ImageGenBackendLoader;
+    /**
+     * Best-effort RAM/VRAM footprint estimate for the loaded weights. The
+     * arbiter only uses this for telemetry; eviction is by priority. The
+     * default (3500 MB) matches Z-Image-Turbo Q4_K_M; small-tier SD 1.5
+     * loaders SHOULD pass ~1100.
+     */
+    estimatedMb?: number;
+}
+/**
+ * Build a `CapabilityRegistration` ready to feed to
+ * `arbiter.registerCapability()`. Mirrors
+ * `createVisionCapabilityRegistration` from WS2.
+ */
+export declare function createImageGenCapabilityRegistration(opts: CreateImageGenCapabilityRegistrationOptions): CapabilityRegistration<ImageGenBackend, ImageGenRequest, ImageGenResult>;
+//# sourceMappingURL=index.d.ts.map

package/src/services/imagegen/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EACN,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,8BAA8B,EACnC,uBAAuB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACN,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,2BAA2B,EAC3B,sBAAsB,EACtB,2BAA2B,GAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACN,KAAK,oBAAoB,EACzB,KAAK,gCAAgC,EACrC,yBAAyB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACN,+BAA+B,EAC/B,qBAAqB,GACrB,MAAM,UAAU,CAAC;AAClB,OAAO,EACN,wBAAwB,EACxB,KAAK,mBAAmB,GACxB,MAAM,SAAS,CAAC;AACjB,OAAO,EACN,eAAe,EACf,YAAY,EACZ,wBAAwB,EACxB,aAAa,EACb,QAAQ,EACR,WAAW,EACX,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACnB,MAAM,UAAU,CAAC;AAClB,OAAO,EACN,2BAA2B,EAC3B,KAAK,sBAAsB,GAC3B,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACX,eAAe,EACf,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,cAAc,GACd,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EAEX,sBAAsB,EACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EACX,eAAe,EACf,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,2CAA2C;IAC3D,MAAM,EAAE,qBAAqB,CAAC;IAC9B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,oCAAoC,CACnD,IAAI,EAAE,2CAA2C,GAC/C,sBAAsB,CAAC,eAAe,EAAE,eAAe,EAAE,cAAc,CAAC,CA+B1E"}

package/src/services/imagegen/index.ts

@@ -0,0 +1,144 @@
+/**
+ * Local image-generation capability (WS3) — public entry point.
+ *
+ * This module is what `provider.ts` (`createImageGenerationHandler`),
+ * the UI image-gen action, and image-gen skill imports to
+ * register the capability with the WS1 MemoryArbiter.
+ *
+ * Wiring:
+ *
+ *   const arbiter = service.getMemoryArbiter();
+ *   const registration = createImageGenCapabilityRegistration({
+ *     loader: createDefaultImageGenLoader({ ... }),
+ *   });
+ *   arbiter.registerCapability(registration);
+ *
+ * `createImageGenCapabilityRegistration` wraps the underlying backend
+ * so the arbiter's `run(request)` path:
+ *
+ *   1. Calls `backend.supports(request)`. If false, the arbiter throws
+ *      `unsupported_request` so the caller can pick a different tier
+ *      or surface a clear error.
+ *   2. Calls `backend.generate(request)` and returns the result.
+ *
+ * The capability registers with `residentRole: "vision"` so image-gen
+ * co-evicts with vision-describe — both are GPU-heavy weights with
+ * comparable RAM footprints, and the arbiter's existing one-model-per-
+ * role policy gives us free serialization. A vision-describe request
+ * arriving while image-gen is in flight will queue, wait for the
+ * generate to drain, then evict the diffusion weights and load the
+ * VL weights.
+ */
+
+export {
+	type AospImageGenBinding,
+	type AospImageGenHandle,
+	type LoadAospImageGenBackendOptions,
+	loadAospImageGenBackend,
+} from "./aosp-unavailable";
+export {
+	type ImageGenBackendChoice,
+	type ImageGenBackendId,
+	type ImageGenRuntimeProfile,
+	resolveDefaultImageGenModel,
+	selectImageGenBackends,
+	TIER_TO_DEFAULT_IMAGE_MODEL,
+} from "./backend-selector";
+export {
+	type CoreMlImageGenBridge,
+	type LoadCoreMlImageGenBackendOptions,
+	loadCoreMlImageGenBackend,
+} from "./coreml-unavailable";
+export {
+	ImageGenBackendUnavailableError,
+	isImageGenUnavailable,
+} from "./errors";
+export {
+	loadMfluxImageGenBackend,
+	type MfluxBackendOptions,
+} from "./mflux";
+export {
+	assertPngOutput,
+	defaultSpawn,
+	loadSdCppImageGenBackend,
+	PNG_SIGNATURE,
+	pickSeed,
+	resolveSeed,
+	type SdCppBackendOptions,
+	type SdCppSpawnLike,
+} from "./sd-cpp";
+export {
+	loadTensorRtImageGenBackend,
+	type TensorRtBackendOptions,
+} from "./tensorrt-unavailable";
+export type {
+	ImageGenBackend,
+	ImageGenBackendLoader,
+	ImageGenLoadArgs,
+	ImageGenMimeType,
+	ImageGenRequest,
+	ImageGenResult,
+} from "./types";
+
+import type {
+	ArbiterCapability,
+	CapabilityRegistration,
+} from "../memory-arbiter";
+import { ImageGenBackendUnavailableError } from "./errors";
+import type {
+	ImageGenBackend,
+	ImageGenBackendLoader,
+	ImageGenRequest,
+	ImageGenResult,
+} from "./types";
+
+export interface CreateImageGenCapabilityRegistrationOptions {
+	loader: ImageGenBackendLoader;
+	/**
+	 * Best-effort RAM/VRAM footprint estimate for the loaded weights. The
+	 * arbiter only uses this for telemetry; eviction is by priority. The
+	 * default (3500 MB) matches Z-Image-Turbo Q4_K_M; small-tier SD 1.5
+	 * loaders SHOULD pass ~1100.
+	 */
+	estimatedMb?: number;
+}
+
+/**
+ * Build a `CapabilityRegistration` ready to feed to
+ * `arbiter.registerCapability()`. Mirrors
+ * `createVisionCapabilityRegistration` from WS2.
+ */
+export function createImageGenCapabilityRegistration(
+	opts: CreateImageGenCapabilityRegistrationOptions,
+): CapabilityRegistration<ImageGenBackend, ImageGenRequest, ImageGenResult> {
+	const capability: ArbiterCapability = "image-gen";
+	const loader = opts.loader;
+	return {
+		capability,
+		// Co-evict with vision-describe. Both are GPU-heavy modalities
+		// with similar load times; sharing the `vision` slot keeps the
+		// resident-role table flat and lets the WS1 swap path handle
+		// vision-vs-image-gen contention with the existing queue.
+		residentRole: "vision",
+		estimatedMb: opts.estimatedMb ?? 3500,
+		async load(modelKey: string): Promise<ImageGenBackend> {
+			return await loader(modelKey);
+		},
+		async unload(backend: ImageGenBackend): Promise<void> {
+			await backend.dispose();
+		},
+		async run(
+			backend: ImageGenBackend,
+			request: ImageGenRequest,
+		): Promise<ImageGenResult> {
+			if (!backend.supports(request)) {
+				throw new ImageGenBackendUnavailableError(
+					backend.id,
+					"unsupported_request",
+					`[imagegen] backend "${backend.id}" does not support this request (width=${request.width ?? "default"} height=${request.height ?? "default"} scheduler=${request.scheduler ?? "default"})`,
+				);
+			}
+			return await backend.generate(request);
+		},
+	};
+}

package/src/services/imagegen/mflux.d.ts

@@ -0,0 +1,74 @@
+/**
+ * MLX-mflux image-gen backend (WS3) — macOS Apple Silicon.
+ *
+ * `mflux` is the community MLX port of FLUX.1 with Z-Image-Turbo support
+ * (https://github.com/filipstrand/mflux). It's a Python package that
+ * ships a `mflux-generate` CLI; we shell out to it from a venv the
+ * bundle installer creates at `${MODELS_DIR}/mlx/mflux`.
+ *
+ * Why a venv (and not a Node MLX binding):
+ *   - MLX Python is the canonical fast path on Apple Silicon — the
+ *     mflux maintainers track upstream MLX optimizations directly.
+ *   - There is no stable MLX Node binding today; writing one would
+ *     duplicate MLX Python's surface for very little gain. Diffusion
+ *     latency dominates the IPC cost.
+ *   - The mflux CLI is stable, with `--model …`, `--prompt …`,
+ *     `--steps …`, `--seed …`, `--output …`.
+ *
+ * Venv resolution:
+ *   1. `opts.binaryPath` (test injection).
+ *   2. `process.env.MFLUX_BIN` (operator override; usually the venv's
+ *      `bin/mflux-generate`).
+ *   3. `${MODELS_DIR}/mlx/mflux/bin/mflux-generate`.
+ *
+ * Model resolution:
+ *   mflux expects `--model` to be either a HuggingFace repo id
+ *   (`black-forest-labs/FLUX.1-schnell`) or a local checkpoint
+ *   directory. The bundle installer writes the local path; we pass it
+ *   verbatim.
+ *
+ * GPU validation status:
+ *   On Apple Silicon this hits the Metal Performance Shaders backend
+ *   through MLX. We have no Mac on this host — see
+ *   `__tests__/imagegen-handler.test.ts` notes for the on-device check
+ *   (M2 / M3 Max smoke for Z-Image-Turbo 4-step <2s 1024×1024).
+ *
+ * Publishing pipeline (macOS Apple Silicon only — Intel Mac falls back to
+ * sd-cpp Metal, see `sd-cpp.ts`):
+ *
+ *   Build:
+ *     python3 -m venv ${MODELS_DIR}/mlx/mflux
+ *     ${MODELS_DIR}/mlx/mflux/bin/pip install --upgrade pip
+ *     ${MODELS_DIR}/mlx/mflux/bin/pip install mflux           # arm64-only wheel
+ *   Sign:
+ *     codesign --force --options runtime --timestamp \
+ *       --sign "Developer ID Application: Eliza Labs Inc." \
+ *       ${MODELS_DIR}/mlx/mflux/bin/python3
+ *     codesign --force --options runtime --timestamp \
+ *       --sign "Developer ID Application: Eliza Labs Inc." \
+ *       ${MODELS_DIR}/mlx/mflux/bin/mflux-generate
+ *   Notarize:
+ *     ditto -c -k --keepParent ${MODELS_DIR}/mlx/mflux mflux-venv.zip
+ *     xcrun notarytool submit mflux-venv.zip \
+ *       --apple-id <ci-secret> --team-id <eliza-labs-team> --wait
+ *     xcrun stapler staple ${MODELS_DIR}/mlx/mflux/bin/mflux-generate
+ *   Drop:
+ *     releases.elizaos.ai/mflux/<version>/darwin-arm64/mflux-venv.tar.zst
+ *   The bundle installer untars the venv into the user's `${MODELS_DIR}/
+ *   mlx/mflux/` directory; the first launch runs `mflux-generate --help`
+ *   to warm up the cache.
+ */
+import { type SdCppSpawnLike } from "./sd-cpp";
+import type { ImageGenBackend, ImageGenLoadArgs } from "./types";
+export interface MfluxBackendOptions {
+    loadArgs: ImageGenLoadArgs;
+    modelKey: string;
+    binaryPath?: string;
+    outputDir?: string;
+    spawnImpl?: SdCppSpawnLike;
+    /** Test seam — when set, skips subprocess and writes these bytes. */
+    fakeImageBytes?: Uint8Array;
+    now?: () => number;
+}
+export declare function loadMfluxImageGenBackend(opts: MfluxBackendOptions): Promise<ImageGenBackend>;
+//# sourceMappingURL=mflux.d.ts.map

package/src/services/imagegen/mflux.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mflux.d.ts","sourceRoot":"","sources":["mflux.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAMH,OAAO,EAIN,KAAK,cAAc,EACnB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EACX,eAAe,EACf,gBAAgB,EAGhB,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,mBAAmB;IACnC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,qEAAqE;IACrE,cAAc,CAAC,EAAE,UAAU,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACnB;AAID,wBAAsB,wBAAwB,CAC7C,IAAI,EAAE,mBAAmB,GACvB,OAAO,CAAC,eAAe,CAAC,CA8H1B"}

package/src/services/imagegen/mflux.ts

@@ -0,0 +1,313 @@
+/**
+ * MLX-mflux image-gen backend (WS3) — macOS Apple Silicon.
+ *
+ * `mflux` is the community MLX port of FLUX.1 with Z-Image-Turbo support
+ * (https://github.com/filipstrand/mflux). It's a Python package that
+ * ships a `mflux-generate` CLI; we shell out to it from a venv the
+ * bundle installer creates at `${MODELS_DIR}/mlx/mflux`.
+ *
+ * Why a venv (and not a Node MLX binding):
+ *   - MLX Python is the canonical fast path on Apple Silicon — the
+ *     mflux maintainers track upstream MLX optimizations directly.
+ *   - There is no stable MLX Node binding today; writing one would
+ *     duplicate MLX Python's surface for very little gain. Diffusion
+ *     latency dominates the IPC cost.
+ *   - The mflux CLI is stable, with `--model …`, `--prompt …`,
+ *     `--steps …`, `--seed …`, `--output …`.
+ *
+ * Venv resolution:
+ *   1. `opts.binaryPath` (test injection).
+ *   2. `process.env.MFLUX_BIN` (operator override; usually the venv's
+ *      `bin/mflux-generate`).
+ *   3. `${MODELS_DIR}/mlx/mflux/bin/mflux-generate`.
+ *
+ * Model resolution:
+ *   mflux expects `--model` to be either a HuggingFace repo id
+ *   (`black-forest-labs/FLUX.1-schnell`) or a local checkpoint
+ *   directory. The bundle installer writes the local path; we pass it
+ *   verbatim.
+ *
+ * GPU validation status:
+ *   On Apple Silicon this hits the Metal Performance Shaders backend
+ *   through MLX. We have no Mac on this host — see
+ *   `__tests__/imagegen-handler.test.ts` notes for the on-device check
+ *   (M2 / M3 Max smoke for Z-Image-Turbo 4-step <2s 1024×1024).
+ *
+ * Publishing pipeline (macOS Apple Silicon only — Intel Mac falls back to
+ * sd-cpp Metal, see `sd-cpp.ts`):
+ *
+ *   Build:
+ *     python3 -m venv ${MODELS_DIR}/mlx/mflux
+ *     ${MODELS_DIR}/mlx/mflux/bin/pip install --upgrade pip
+ *     ${MODELS_DIR}/mlx/mflux/bin/pip install mflux           # arm64-only wheel
+ *   Sign:
+ *     codesign --force --options runtime --timestamp \
+ *       --sign "Developer ID Application: Eliza Labs Inc." \
+ *       ${MODELS_DIR}/mlx/mflux/bin/python3
+ *     codesign --force --options runtime --timestamp \
+ *       --sign "Developer ID Application: Eliza Labs Inc." \
+ *       ${MODELS_DIR}/mlx/mflux/bin/mflux-generate
+ *   Notarize:
+ *     ditto -c -k --keepParent ${MODELS_DIR}/mlx/mflux mflux-venv.zip
+ *     xcrun notarytool submit mflux-venv.zip \
+ *       --apple-id <ci-secret> --team-id <eliza-labs-team> --wait
+ *     xcrun stapler staple ${MODELS_DIR}/mlx/mflux/bin/mflux-generate
+ *   Drop:
+ *     releases.elizaos.ai/mflux/<version>/darwin-arm64/mflux-venv.tar.zst
+ *   The bundle installer untars the venv into the user's `${MODELS_DIR}/
+ *   mlx/mflux/` directory; the first launch runs `mflux-generate --help`
+ *   to warm up the cache.
+ */
+
+import { existsSync, promises as fs, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ImageGenBackendUnavailableError } from "./errors";
+import {
+	assertPngOutput,
+	defaultSpawn,
+	resolveSeed,
+	type SdCppSpawnLike,
+} from "./sd-cpp";
+import type {
+	ImageGenBackend,
+	ImageGenLoadArgs,
+	ImageGenRequest,
+	ImageGenResult,
+} from "./types";
+
+export interface MfluxBackendOptions {
+	loadArgs: ImageGenLoadArgs;
+	modelKey: string;
+	binaryPath?: string;
+	outputDir?: string;
+	spawnImpl?: SdCppSpawnLike;
+	/** Test seam — when set, skips subprocess and writes these bytes. */
+	fakeImageBytes?: Uint8Array;
+	now?: () => number;
+}
+
+const DEFAULT_BIN = "mflux-generate";
+
+export async function loadMfluxImageGenBackend(
+	opts: MfluxBackendOptions,
+): Promise<ImageGenBackend> {
+	const binary = resolveBinary(opts.binaryPath);
+	const now = opts.now ?? Date.now;
+
+	if (!opts.fakeImageBytes) {
+		await assertBinaryAvailable(binary, opts.spawnImpl);
+	}
+
+	const outputDir = opts.outputDir ?? mkdtempSync(join(tmpdir(), "mflux-"));
+	let disposed = false;
+
+	return {
+		id: "mflux",
+		supports(req) {
+			// mflux supports flexible WxH but resolution must be a /16 multiple
+			// for FLUX. SD 1.5 in mflux (less common) needs /8. We round up,
+			// so accept anything reasonable.
+			const w = req.width ?? 1024;
+			const h = req.height ?? 1024;
+			if (w <= 0 || h <= 0) return false;
+			if (w > 2048 || h > 2048) return false;
+			return true;
+		},
+		async generate(req): Promise<ImageGenResult> {
+			if (disposed) {
+				throw new ImageGenBackendUnavailableError(
+					"mflux",
+					"subprocess_failed",
+					"[imagegen/mflux] generate called after dispose()",
+				);
+			}
+			if (!req.prompt.trim()) {
+				throw new ImageGenBackendUnavailableError(
+					"mflux",
+					"unsupported_request",
+					"[imagegen/mflux] prompt is empty",
+				);
+			}
+			const seed = resolveSeed(req.seed);
+			const width = req.width ?? 1024;
+			const height = req.height ?? 1024;
+			// FLUX schnell / Z-Image-Turbo are 4-step turbo models; default
+			// to 4 here when the caller didn't specify.
+			const steps = req.steps ?? 4;
+			// FLUX schnell is CFG-free; mflux ignores the value but we record
+			// it as 0 in metadata when the caller didn't ask for one.
+			const guidanceScale = req.guidanceScale ?? 0;
+			const outputPath = join(outputDir, `out-${seed}-${now()}.png`);
+			const startMs = now();
+
+			if (opts.fakeImageBytes) {
+				await fs.writeFile(outputPath, opts.fakeImageBytes);
+				const elapsed = Math.max(1, now() - startMs);
+				if (req.onProgressChunk)
+					req.onProgressChunk({ step: steps, total: steps });
+				return {
+					image: opts.fakeImageBytes,
+					mime: "image/png",
+					seed,
+					metadata: {
+						model: opts.modelKey,
+						prompt: req.prompt,
+						steps,
+						guidanceScale,
+						inferenceTimeMs: elapsed,
+					},
+				};
+			}
+
+			if (!existsSync(opts.loadArgs.modelPath)) {
+				throw new ImageGenBackendUnavailableError(
+					"mflux",
+					"model_missing",
+					`[imagegen/mflux] model not found: ${opts.loadArgs.modelPath}`,
+				);
+			}
+
+			const args: string[] = [
+				"--model",
+				opts.loadArgs.modelPath,
+				"--prompt",
+				req.prompt,
+				"--width",
+				String(width),
+				"--height",
+				String(height),
+				"--steps",
+				String(steps),
+				"--seed",
+				String(seed),
+				"--output",
+				outputPath,
+			];
+			if (req.guidanceScale !== undefined) {
+				args.push("--guidance", String(req.guidanceScale));
+			}
+
+			await runMflux(binary, args, {
+				signal: req.signal,
+				spawnImpl: opts.spawnImpl,
+				onProgressChunk: req.onProgressChunk,
+				totalSteps: steps,
+			});
+
+			const bytes = new Uint8Array(await fs.readFile(outputPath));
+			assertPngOutput(bytes, "mflux", "subprocess_failed");
+			const elapsed = Math.max(1, now() - startMs);
+			return {
+				image: bytes,
+				mime: "image/png",
+				seed,
+				metadata: {
+					model: opts.modelKey,
+					prompt: req.prompt,
+					steps,
+					guidanceScale,
+					inferenceTimeMs: elapsed,
+				},
+			};
+		},
+		async dispose() {
+			if (disposed) return;
+			disposed = true;
+			await fs.rm(outputDir, { recursive: true, force: true }).catch(() => {});
+		},
+	};
+}
+
+function resolveBinary(override?: string): string {
+	if (override) return override;
+	const envBin = process.env.MFLUX_BIN;
+	if (envBin?.trim()) return envBin.trim();
+	return DEFAULT_BIN;
+}
+
+async function assertBinaryAvailable(
+	binary: string,
+	spawnImpl?: SdCppSpawnLike,
+): Promise<void> {
+	try {
+		const code = await new Promise<number | null>((resolve, reject) => {
+			const proc = defaultSpawn(spawnImpl)(binary, ["--help"]);
+			proc.on("error", (err: Error) => reject(err));
+			proc.on("exit", (c: number | null) => resolve(c));
+		});
+		// `mflux-generate --help` exits 0 on success. Tolerate code 2 in
+		// older mflux versions where --help is the default and exits non-zero.
+		if (code !== 0 && code !== 2) {
+			throw new ImageGenBackendUnavailableError(
+				"mflux",
+				"binary_version_mismatch",
+				`[imagegen/mflux] '${binary} --help' exited with code ${code}`,
+			);
+		}
+	} catch (err) {
+		if (err instanceof ImageGenBackendUnavailableError) throw err;
+		const message = err instanceof Error ? err.message : String(err);
+		throw new ImageGenBackendUnavailableError(
+			"mflux",
+			"binary_missing",
+			`[imagegen/mflux] cannot run '${binary} --help': ${message}. Set MFLUX_BIN or install the bundle's mflux venv at \${MODELS_DIR}/mlx/mflux.`,
+			{ cause: err },
+		);
+	}
+}
+
+async function runMflux(
+	binary: string,
+	args: readonly string[],
+	opts: {
+		signal?: AbortSignal;
+		spawnImpl?: SdCppSpawnLike;
+		onProgressChunk?: ImageGenRequest["onProgressChunk"];
+		totalSteps: number;
+	},
+): Promise<void> {
+	await new Promise<void>((resolve, reject) => {
+		const proc = defaultSpawn(opts.spawnImpl)(binary, args, {
+			signal: opts.signal,
+		});
+		const stderr = proc.stderr;
+		if (
+			opts.onProgressChunk &&
+			stderr &&
+			typeof (stderr as NodeJS.ReadableStream).on === "function"
+		) {
+			let leftover = "";
+			(stderr as NodeJS.ReadableStream).on("data", (chunk: Buffer | string) => {
+				const text =
+					leftover +
+					(typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+				const lines = text.split(/\r?\n/);
+				leftover = lines.pop() ?? "";
+				for (const line of lines) {
+					// mflux prints `Step N/M` to stderr (tqdm-style).
+					const m = line.match(/step\s*(\d+)\s*\/\s*(\d+)/i);
+					if (!m) continue;
+					opts.onProgressChunk?.({
+						step: Number(m[1]),
+						total: Number(m[2]) || opts.totalSteps,
+					});
+				}
+			});
+		}
+		proc.on("error", (err: Error) => reject(err));
+		proc.on("exit", (code: number | null) => {
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			reject(
+				new ImageGenBackendUnavailableError(
+					"mflux",
+					"subprocess_failed",
+					`[imagegen/mflux] mflux-generate exited with code ${code}`,
+				),
+			);
+		});
+	});
+}