@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.3-beta.3

package/src/services/imagegen/aosp-unavailable.ts

@@ -0,0 +1,229 @@
+/**
+ * AOSP image-gen backend contract (WS3) — Android via JNI.
+ *
+ * On AOSP the canonical fast path is stable-diffusion.cpp built into
+ * `libstable-diffusion-jni.so` and exposed through a JNI surface in
+ * `@elizaos/plugin-aosp-local-inference`. The shim mirrors the pattern
+ * WS2 uses for `eliza_llama_mtmd_*`: a small set of `eliza_llama_imagegen_*`
+ * symbols that bun:ffi opens via the same `dlopen` path the text-gen
+ * binding uses.
+ *
+ * Required native symbols (libeliza-llama-shim, to be added):
+ *
+ *   eliza_llama_imagegen_init_from_file(
+ *     model_path: const char *,
+ *     accelerator: const char *,   // "auto" / "vulkan" / "opencl" / "cpu"
+ *     out_handle: void **
+ *   ) -> int32  // 0 = ok; non-zero = error code
+ *
+ *   eliza_llama_imagegen_free(handle: void *) -> void
+ *
+ *   eliza_llama_imagegen_generate(
+ *     handle: void *,
+ *     prompt: const char *,
+ *     prompt_len: size_t,
+ *     negative_prompt: const char *,   // may be null
+ *     negative_prompt_len: size_t,
+ *     width: int32,
+ *     height: int32,
+ *     steps: int32,
+ *     guidance_scale: float,
+ *     seed: int64,
+ *     scheduler: const char *,         // may be null
+ *     out_png_buf: uint8_t **,         // owned by shim; valid until next call
+ *     out_png_len: size_t *,
+ *     out_seed_used: int64 *,
+ *     out_inference_ms: int64 *
+ *   ) -> int32
+ *
+ * Why a shim symbol set and not a JNI-direct stable-diffusion.cpp:
+ *   The same dlopen pattern that solves the text-gen integration solves
+ *   image-gen — we ship one `libeliza-llama-shim.so` per ABI and bun:ffi
+ *   binds against a single library handle. Doing JNI directly would
+ *   require a JVM in the AOSP build, which we don't want to mandate.
+ *
+ * Performance note for AOSP image-gen:
+ *   Vulkan is the only reasonable accelerator on Android (OpenCL is
+ *   patchy across SoCs; CPU is too slow for 4-step Z-Image-Turbo
+ *   1024×1024 — Snapdragon 8 Gen 3 hits ~6s on CPU vs ~1.4s on Vulkan).
+ *   The shim defaults to `"vulkan"` and falls back to `"cpu"` only when
+ *   Vulkan compute is unavailable.
+ *
+ * Until the shim exports the symbols above, `loadAospImageGenBackend`
+ * throws a structured `ImageGenBackendUnavailableError` so the selector
+ * can fall back to a desktop-bridge or surface "unavailable" to the UI.
+ *
+ * Publishing pipeline (Android APK + AOSP system app):
+ *
+ *   Build (libstable-diffusion-jni.so per ABI):
+ *     # cd plugins/plugin-aosp-local-inference/native
+ *     # NDK r26+ required for Vulkan compute compatibility on Snapdragon 8 Gen 3.
+ *     cmake -B build-arm64-v8a -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake \
+ *       -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=android-29 \
+ *       -DSD_VULKAN=ON -DBUILD_SHARED_LIBS=ON
+ *     cmake --build build-arm64-v8a -j
+ *     # Repeat for x86_64 (Cuttlefish / emulator) — see eliza/plugins/
+ *     # plugin-local-inference/native/llama.cpp patches for the JNI x86_64
+ *     # ABI surface we already maintain for text/vision.
+ *   Sign:
+ *     # AAB / APK signature; libstable-diffusion-jni.so is signed transitively
+ *     # via the app's keystore. v2 signature with the Eliza Labs production key.
+ *     bundletool build-bundle --modules=... --output=app.aab
+ *     jarsigner -keystore eliza-prod.jks -signedjar app-signed.aab app.aab eliza-key
+ *   Notarize:
+ *     N/A on Android. Google Play handles validation; AOSP system-app
+ *     installs trust the app's own keystore.
+ *   Drop:
+ *     play.google.com (split APK by ABI; sd-cpp lib lives in the
+ *     `imagegen` dynamic feature module — only downloaded after the user
+ *     opts in to image-gen).
+ *     For sideload / Cuttlefish / dev builds:
+ *     releases.elizaos.ai/aosp-imagegen/<version>/libstable-diffusion-jni-<abi>.so
+ *
+ * Why a dynamic feature module:
+ *   The Z-Image-Turbo GGUF is ~3.4 GB; bundling that into the base APK
+ *   would push the install above the Play Store's 200 MB hard cap and
+ *   trigger an automatic split. Dynamic delivery + first-launch download
+ *   keeps the base install lean and lets the user opt in.
+ */
+
+import { ImageGenBackendUnavailableError } from "./errors";
+import { resolveSeed } from "./sd-cpp";
+import type {
+	ImageGenBackend,
+	ImageGenLoadArgs,
+	ImageGenRequest,
+	ImageGenResult,
+} from "./types";
+
+/**
+ * The AOSP binding's image-gen surface, when present. The AOSP plugin
+ * registers an instance under the runtime service name
+ * `"aosp-llama-imagegen"` once the native shim exports the symbols
+ * above. Mirrors the WS2 `AospLlamaMtmdBinding` shape.
+ */
+export interface AospImageGenBinding {
+	/** True when libeliza-llama-shim.so exports the imagegen symbols. */
+	hasImageGen(): boolean;
+	/**
+	 * Initialize a handle for the given model. The shim resolves the
+	 * accelerator hint internally; pass `"auto"` to defer to its
+	 * detection.
+	 */
+	initImageGen(args: {
+		modelPath: string;
+		accelerator?: ImageGenLoadArgs["accelerator"];
+	}): Promise<AospImageGenHandle>;
+}
+
+export interface AospImageGenHandle {
+	generate(args: {
+		prompt: string;
+		negativePrompt?: string;
+		width: number;
+		height: number;
+		steps: number;
+		guidanceScale: number;
+		seed: number;
+		scheduler?: string;
+		signal?: AbortSignal;
+	}): Promise<{
+		png: Uint8Array;
+		seedUsed: number;
+		inferenceMs: number;
+	}>;
+	dispose(): Promise<void>;
+}
+
+export interface LoadAospImageGenBackendOptions {
+	loadArgs: ImageGenLoadArgs;
+	modelKey: string;
+	binding?: AospImageGenBinding;
+	now?: () => number;
+}
+
+export async function loadAospImageGenBackend(
+	opts: LoadAospImageGenBackendOptions,
+): Promise<ImageGenBackend> {
+	const binding = opts.binding;
+	if (!binding?.hasImageGen()) {
+		throw new ImageGenBackendUnavailableError(
+			"aosp",
+			"binding_unavailable",
+			"[imagegen/aosp] libeliza-llama-shim does not export the imagegen symbols yet. Add eliza_llama_imagegen_init_from_file / _generate / _free to the AOSP shim. Until then, AOSP image-gen falls back to nothing (or to a desktop-bridge if paired).",
+		);
+	}
+	const handle = await binding.initImageGen({
+		modelPath: opts.loadArgs.modelPath,
+		accelerator: opts.loadArgs.accelerator,
+	});
+	const now = opts.now ?? Date.now;
+	let disposed = false;
+
+	return {
+		id: "aosp",
+		supports(req: ImageGenRequest) {
+			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(
+					"aosp",
+					"binding_unavailable",
+					"[imagegen/aosp] generate called after dispose()",
+				);
+			}
+			if (!req.prompt.trim()) {
+				throw new ImageGenBackendUnavailableError(
+					"aosp",
+					"unsupported_request",
+					"[imagegen/aosp] prompt is empty",
+				);
+			}
+			const seed = resolveSeed(req.seed);
+			const width = req.width ?? 1024;
+			const height = req.height ?? 1024;
+			const steps = req.steps ?? 4;
+			const guidanceScale = req.guidanceScale ?? 0;
+			const startMs = now();
+			const out = await handle.generate({
+				prompt: req.prompt,
+				negativePrompt: req.negativePrompt,
+				width,
+				height,
+				steps,
+				guidanceScale,
+				seed,
+				scheduler: req.scheduler,
+				signal: req.signal,
+			});
+			const elapsed =
+				typeof out.inferenceMs === "number" && out.inferenceMs > 0
+					? out.inferenceMs
+					: Math.max(1, now() - startMs);
+			if (req.onProgressChunk)
+				req.onProgressChunk({ step: steps, total: steps });
+			return {
+				image: out.png,
+				mime: "image/png",
+				seed: typeof out.seedUsed === "number" ? out.seedUsed : seed,
+				metadata: {
+					model: opts.modelKey,
+					prompt: req.prompt,
+					steps,
+					guidanceScale,
+					inferenceTimeMs: elapsed,
+				},
+			};
+		},
+		async dispose() {
+			if (disposed) return;
+			disposed = true;
+			await handle.dispose();
+		},
+	};
+}

package/src/services/imagegen/backend-selector.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, it } from "vitest";
+import {
+	type ImageGenRuntimeProfile,
+	resolveDefaultImageGenModel,
+	selectImageGenBackends,
+} from "./backend-selector";
+
+/**
+ * Image-gen backend selection (#8848 / WS3).
+ *
+ * `selectImageGenBackends` is the deterministic per-platform decision tree the
+ * arbiter walks at model-load time; `resolveDefaultImageGenModel` maps a tier
+ * id to a concrete diffusion file. The whole `imagegen/` dir was untested, so a
+ * regression in the accelerator ordering or the `requiredAccelerator` override
+ * (which exists precisely so release smoke tests can't silently fall back to
+ * CPU) would pass unnoticed. Both functions are pure.
+ */
+
+const profile = (
+	o: Partial<ImageGenRuntimeProfile>,
+): ImageGenRuntimeProfile => ({
+	platform: "linux",
+	arch: "x64",
+	...o,
+});
+
+describe("selectImageGenBackends — requiredAccelerator override", () => {
+	it("pins a single backend for each explicit accelerator", () => {
+		expect(
+			selectImageGenBackends(profile({ requiredAccelerator: "cuda" })),
+		).toEqual([{ backendId: "sd-cpp", accelerator: "cuda" }]);
+		expect(
+			selectImageGenBackends(profile({ requiredAccelerator: "vulkan" })),
+		).toEqual([{ backendId: "sd-cpp", accelerator: "vulkan" }]);
+		expect(
+			selectImageGenBackends(profile({ requiredAccelerator: "cpu" })),
+		).toEqual([{ backendId: "sd-cpp", accelerator: "cpu" }]);
+		expect(
+			selectImageGenBackends(profile({ requiredAccelerator: "coreml" })),
+		).toEqual([{ backendId: "coreml", accelerator: "coreml" }]);
+		expect(
+			selectImageGenBackends(profile({ requiredAccelerator: "tensorrt" })),
+		).toEqual([{ backendId: "tensorrt", accelerator: "tensorrt" }]);
+	});
+
+	it("routes a required metal accelerator to mflux only on Apple Silicon", () => {
+		expect(
+			selectImageGenBackends(
+				profile({
+					requiredAccelerator: "metal",
+					platform: "darwin",
+					arch: "arm64",
+				}),
+			),
+		).toEqual([{ backendId: "mflux", accelerator: "metal" }]);
+		// Intel Mac (or anything not darwin/arm64) → sd-cpp metal.
+		expect(
+			selectImageGenBackends(
+				profile({
+					requiredAccelerator: "metal",
+					platform: "darwin",
+					arch: "x64",
+				}),
+			),
+		).toEqual([{ backendId: "sd-cpp", accelerator: "metal" }]);
+	});
+
+	it("lets the explicit override win over the mobile shells", () => {
+		expect(
+			selectImageGenBackends(
+				profile({ requiredAccelerator: "cuda", isIos: true }),
+			),
+		).toEqual([{ backendId: "sd-cpp", accelerator: "cuda" }]);
+	});
+});
+
+describe("selectImageGenBackends — platform policy", () => {
+	it("returns Core ML only on iOS and aosp only on Android", () => {
+		expect(selectImageGenBackends(profile({ isIos: true }))).toEqual([
+			{ backendId: "coreml", accelerator: "coreml" },
+		]);
+		expect(selectImageGenBackends(profile({ isAndroid: true }))).toEqual([
+			{ backendId: "aosp", accelerator: "auto" },
+		]);
+	});
+
+	it("orders mflux→sd-cpp on Apple Silicon, sd-cpp auto→cpu on Intel Mac", () => {
+		expect(
+			selectImageGenBackends(profile({ platform: "darwin", arch: "arm64" })),
+		).toEqual([
+			{ backendId: "mflux", accelerator: "metal" },
+			{ backendId: "sd-cpp", accelerator: "cpu" },
+		]);
+		expect(
+			selectImageGenBackends(profile({ platform: "darwin", arch: "x64" })),
+		).toEqual([
+			{ backendId: "sd-cpp", accelerator: "auto" },
+			{ backendId: "sd-cpp", accelerator: "cpu" },
+		]);
+	});
+
+	it("orders tensorrt→cuda→cpu on Windows NVIDIA and vulkan→cpu on Windows AMD", () => {
+		expect(
+			selectImageGenBackends(profile({ platform: "win32", gpu: "nvidia" })),
+		).toEqual([
+			{ backendId: "tensorrt", accelerator: "tensorrt" },
+			{ backendId: "sd-cpp", accelerator: "cuda" },
+			{ backendId: "sd-cpp", accelerator: "cpu" },
+		]);
+		expect(
+			selectImageGenBackends(profile({ platform: "win32", gpu: "amd" })),
+		).toEqual([
+			{ backendId: "sd-cpp", accelerator: "vulkan" },
+			{ backendId: "sd-cpp", accelerator: "cpu" },
+		]);
+		expect(
+			selectImageGenBackends(profile({ platform: "win32", gpu: "none" })),
+		).toEqual([{ backendId: "sd-cpp", accelerator: "cpu" }]);
+	});
+
+	it("gates Linux NVIDIA CUDA on real sd-cpp evidence", () => {
+		// GPU vendor alone is NOT evidence the installed binary has CUDA.
+		expect(
+			selectImageGenBackends(profile({ platform: "linux", gpu: "nvidia" })),
+		).toEqual([{ backendId: "sd-cpp", accelerator: "cpu" }]);
+		// cudaCapable evidence promotes CUDA ahead of the CPU fallback.
+		expect(
+			selectImageGenBackends(
+				profile({
+					platform: "linux",
+					gpu: "nvidia",
+					sdCpp: { cudaCapable: true },
+				}),
+			),
+		).toEqual([
+			{ backendId: "sd-cpp", accelerator: "cuda" },
+			{ backendId: "sd-cpp", accelerator: "cpu" },
+		]);
+		// an accelerators list that includes cuda is equivalent evidence.
+		expect(
+			selectImageGenBackends(
+				profile({
+					platform: "linux",
+					gpu: "nvidia",
+					sdCpp: { accelerators: ["cuda"] },
+				}),
+			),
+		).toEqual([
+			{ backendId: "sd-cpp", accelerator: "cuda" },
+			{ backendId: "sd-cpp", accelerator: "cpu" },
+		]);
+	});
+
+	it("falls back to sd-cpp CPU for an unknown platform", () => {
+		expect(
+			selectImageGenBackends(
+				profile({ platform: "freebsd" as ImageGenRuntimeProfile["platform"] }),
+			),
+		).toEqual([{ backendId: "sd-cpp", accelerator: "cpu" }]);
+	});
+});
+
+describe("resolveDefaultImageGenModel", () => {
+	it("resolves a small tier to the SD-1.5 file (no split-diffusion fields)", () => {
+		expect(resolveDefaultImageGenModel("eliza-1-2b")).toEqual({
+			modelId: "imagegen-sd-1_5-q5_0",
+			file: "imagegen/sd-1.5-Q5_0.gguf",
+		});
+	});
+
+	it("resolves a large tier to the split Z-Image diffusion bundle", () => {
+		expect(resolveDefaultImageGenModel("eliza-1-9b")).toMatchObject({
+			modelId: "imagegen-z-image-turbo-q4_k_m",
+			file: "imagegen/z-image-turbo-Q4_K_M.gguf",
+			splitDiffusionModel: true,
+			vae: "imagegen/vae/ae.safetensors",
+		});
+	});
+
+	it("echoes back a bare model id that matches a known tier entry", () => {
+		expect(resolveDefaultImageGenModel("imagegen-sd-1_5-q5_0")).toMatchObject({
+			modelId: "imagegen-sd-1_5-q5_0",
+			file: "imagegen/sd-1.5-Q5_0.gguf",
+		});
+	});
+
+	it("returns null for an unknown key", () => {
+		expect(resolveDefaultImageGenModel("does-not-exist")).toBeNull();
+	});
+});

package/src/services/imagegen/backend-selector.ts

@@ -0,0 +1,277 @@
+/**
+ * Image-gen backend-pick logic (WS3).
+ *
+ * Given a runtime platform + accelerator hint, return the ordered list
+ * of backend ids to try. The arbiter walks this list at load time and
+ * stops at the first backend that resolves to a live handle. A backend
+ * that throws `ImageGenBackendUnavailableError` lets the selector fall
+ * through to the next.
+ *
+ * Per-platform policy:
+ *
+ *   - **macOS Apple Silicon**: `mflux` (MLX) → `sd-cpp` (CPU fallback).
+ *     mflux is Metal-accelerated through MLX; sd-cpp-CPU is the
+ *     functional last-resort if the venv isn't installed.
+ *   - **macOS Intel**: `sd-cpp` (Metal/CPU). MLX requires Apple Silicon;
+ *     mflux is skipped on Intel Macs.
+ *   - **iOS**: `coreml` only. There is no sd-cpp on iOS — Core ML is
+ *     the only sanctioned acceleration path.
+ *   - **Linux + NVIDIA**: `sd-cpp` CUDA only when the sd-cpp probe,
+ *     binary manifest, help, or version output proves CUDA support.
+ *     Otherwise use `sd-cpp` CPU and let the loader emit an explicit
+ *     CUDA-missing fallback error if CUDA was requested elsewhere.
+ *   - **Linux + AMD/Intel**: `sd-cpp --vulkan` → `sd-cpp` (CPU fallback).
+ *   - **Linux + CPU**: `sd-cpp` (CPU).
+ *   - **Windows + NVIDIA**: `tensorrt` → `sd-cpp` (CUDA) → `sd-cpp` (CPU).
+ *   - **Windows + AMD/Intel**: `sd-cpp --vulkan` → `sd-cpp` (CPU).
+ *   - **Android (AOSP)**: `aosp` (libeliza-llama-shim with Vulkan/OpenCL,
+ *     handled by `plugin-aosp-local-inference`). No second backend on
+ *     mobile — falling back to CPU sd-cpp on a phone is too slow to be
+ *     useful and would just block the UI.
+ *
+ * The selector intentionally does NOT account for tier or model
+ * compatibility — that's the catalog's job. A 27B-tier user on a
+ * Vulkan-only Linux box doesn't change the selector; it just changes
+ * which model the chosen backend loads.
+ */
+
+import type { ImageGenBackend } from "./types";
+
+/** Per-platform runtime fingerprint the selector consumes. */
+export interface ImageGenRuntimeProfile {
+	/** Node-style `process.platform`: `"linux" | "darwin" | "win32" | "android"`. */
+	platform: NodeJS.Platform | "android" | "ios";
+	/**
+	 * `process.arch` (`"x64"` | `"arm64"`). Apple Silicon = `"arm64"` on
+	 * `"darwin"`. Intel Mac = `"x64"` on `"darwin"`.
+	 */
+	arch: NodeJS.Architecture | string;
+	/**
+	 * GPU vendor hint, when detected. `"nvidia"` enables CUDA / TensorRT
+	 * paths; `"amd"` and `"intel"` favour Vulkan. `"apple"` is implied by
+	 * platform=darwin+arch=arm64.
+	 */
+	gpu?: "nvidia" | "amd" | "intel" | "apple" | "none";
+	/**
+	 * sd-cpp binary capability evidence gathered from the first-run probe,
+	 * bundle manifest, or a loader-side help/version check. GPU vendor alone
+	 * is not evidence that the installed `sd` binary was built with CUDA.
+	 */
+	sdCpp?: {
+		accelerators?: readonly string[];
+		cudaCapable?: boolean;
+	};
+	/**
+	 * Explicit accelerator requirement for release verification and operator
+	 * smoke tests. When set, the selector returns only backends that can
+	 * satisfy that accelerator, so CUDA/Vulkan evidence cannot be produced by
+	 * silently falling through to CPU.
+	 */
+	requiredAccelerator?:
+		| "cpu"
+		| "cuda"
+		| "vulkan"
+		| "metal"
+		| "coreml"
+		| "tensorrt";
+	/**
+	 * True when running inside the iOS Capacitor shell. We can't infer
+	 * from `process.platform` alone because Capacitor reports `"ios"`
+	 * but Node's typings only know `darwin`/`linux`/etc.
+	 */
+	isIos?: boolean;
+	/**
+	 * True when running inside the Android Capacitor / `plugin-aosp-local-inference`
+	 * shell. Node reports `"linux"` on AOSP, so we need an explicit signal.
+	 */
+	isAndroid?: boolean;
+}
+
+export type ImageGenBackendId = ImageGenBackend["id"];
+
+/**
+ * Ordered list of `(backendId, accelerator)` pairs to try. The caller
+ * picks the first one whose backend loader returns a live handle.
+ *
+ * Accelerator strings match `ImageGenLoadArgs.accelerator`.
+ */
+export interface ImageGenBackendChoice {
+	backendId: ImageGenBackendId;
+	accelerator?:
+		| "auto"
+		| "cpu"
+		| "cuda"
+		| "vulkan"
+		| "metal"
+		| "coreml"
+		| "tensorrt";
+}
+
+export function selectImageGenBackends(
+	profile: ImageGenRuntimeProfile,
+): readonly ImageGenBackendChoice[] {
+	if (profile.requiredAccelerator) {
+		switch (profile.requiredAccelerator) {
+			case "coreml":
+				return [{ backendId: "coreml", accelerator: "coreml" }];
+			case "tensorrt":
+				return [{ backendId: "tensorrt", accelerator: "tensorrt" }];
+			case "metal":
+				return profile.platform === "darwin" && profile.arch === "arm64"
+					? [{ backendId: "mflux", accelerator: "metal" }]
+					: [{ backendId: "sd-cpp", accelerator: "metal" }];
+			case "cuda":
+				return [{ backendId: "sd-cpp", accelerator: "cuda" }];
+			case "vulkan":
+				return [{ backendId: "sd-cpp", accelerator: "vulkan" }];
+			case "cpu":
+				return [{ backendId: "sd-cpp", accelerator: "cpu" }];
+		}
+	}
+	if (profile.isIos) {
+		// iOS Capacitor: Core ML only. No fallback — sd-cpp is not
+		// shipped on iOS and falling back to nothing surfaces a clean
+		// "unavailable on this device" error in the UI.
+		return [{ backendId: "coreml", accelerator: "coreml" }];
+	}
+	if (profile.isAndroid) {
+		// AOSP: libeliza-llama-shim with Vulkan/OpenCL. The JNI handles
+		// the acceleration path; from the JS side we just request "auto"
+		// and let the shim pick.
+		return [{ backendId: "aosp", accelerator: "auto" }];
+	}
+
+	if (profile.platform === "darwin") {
+		if (profile.arch === "arm64") {
+			// Apple Silicon: mflux (MLX/Metal) first; sd-cpp CPU as
+			// last resort if the venv isn't installed.
+			return [
+				{ backendId: "mflux", accelerator: "metal" },
+				{ backendId: "sd-cpp", accelerator: "cpu" },
+			];
+		}
+		// Intel Mac. mflux requires Apple Silicon; sd-cpp Metal is the
+		// reasonable fast path. Builds for Intel Mac sd-cpp are sparse;
+		// CPU is the safe default.
+		return [
+			{ backendId: "sd-cpp", accelerator: "auto" },
+			{ backendId: "sd-cpp", accelerator: "cpu" },
+		];
+	}
+
+	if (profile.platform === "win32") {
+		if (profile.gpu === "nvidia") {
+			return [
+				{ backendId: "tensorrt", accelerator: "tensorrt" },
+				{ backendId: "sd-cpp", accelerator: "cuda" },
+				{ backendId: "sd-cpp", accelerator: "cpu" },
+			];
+		}
+		if (profile.gpu === "amd" || profile.gpu === "intel") {
+			return [
+				{ backendId: "sd-cpp", accelerator: "vulkan" },
+				{ backendId: "sd-cpp", accelerator: "cpu" },
+			];
+		}
+		return [{ backendId: "sd-cpp", accelerator: "cpu" }];
+	}
+
+	// Linux (and any other Unix the runtime reports). sd-cpp covers
+	// CUDA, Vulkan, and CPU through the same binary; we just pick the
+	// accelerator order.
+	if (profile.platform === "linux") {
+		if (profile.gpu === "nvidia") {
+			const sdCppCudaCapable =
+				profile.sdCpp?.cudaCapable === true ||
+				profile.sdCpp?.accelerators?.includes("cuda") === true;
+			return sdCppCudaCapable
+				? [
+						{ backendId: "sd-cpp", accelerator: "cuda" },
+						{ backendId: "sd-cpp", accelerator: "cpu" },
+					]
+				: [{ backendId: "sd-cpp", accelerator: "cpu" }];
+		}
+		if (profile.gpu === "amd" || profile.gpu === "intel") {
+			return [
+				{ backendId: "sd-cpp", accelerator: "vulkan" },
+				{ backendId: "sd-cpp", accelerator: "cpu" },
+			];
+		}
+		return [{ backendId: "sd-cpp", accelerator: "cpu" }];
+	}
+
+	// Unknown platform — try sd-cpp CPU and fail cleanly if it isn't
+	// installed.
+	return [{ backendId: "sd-cpp", accelerator: "cpu" }];
+}
+
+/**
+ * Tier → default image-gen model id. Mirrors
+ * `eliza/packages/chip/ELIZA_1_BUNDLE_EXTRAS.json` and the WS10 golden test's
+ * `PER_TIER_DEFAULT` map. Used by the WS3 capability registration to
+ * resolve the catalog's bare tier id into a concrete diffusion file.
+ */
+export const TIER_TO_DEFAULT_IMAGE_MODEL: Readonly<
+	Record<
+		string,
+		{
+			modelId: string;
+			file: string;
+			splitDiffusionModel?: boolean;
+			vae?: string;
+			llm?: string;
+		}
+	>
+> = {
+	"eliza-1-2b": {
+		modelId: "imagegen-sd-1_5-q5_0",
+		file: "imagegen/sd-1.5-Q5_0.gguf",
+	},
+	"eliza-1-4b": {
+		modelId: "imagegen-sd-1_5-q5_0",
+		file: "imagegen/sd-1.5-Q5_0.gguf",
+	},
+	"eliza-1-9b": {
+		modelId: "imagegen-z-image-turbo-q4_k_m",
+		file: "imagegen/z-image-turbo-Q4_K_M.gguf",
+		splitDiffusionModel: true,
+		vae: "imagegen/vae/ae.safetensors",
+		llm: "imagegen/text-encoders/Qwen3-4B-Instruct-2507-Q4_K_M.gguf",
+	},
+	"eliza-1-27b": {
+		modelId: "imagegen-z-image-turbo-q4_k_m",
+		file: "imagegen/z-image-turbo-Q4_K_M.gguf",
+		splitDiffusionModel: true,
+		vae: "imagegen/vae/ae.safetensors",
+		llm: "imagegen/text-encoders/Qwen3-4B-Instruct-2507-Q4_K_M.gguf",
+	},
+	"eliza-1-27b-256k": {
+		modelId: "imagegen-z-image-turbo-q4_k_m",
+		file: "imagegen/z-image-turbo-Q4_K_M.gguf",
+		splitDiffusionModel: true,
+		vae: "imagegen/vae/ae.safetensors",
+		llm: "imagegen/text-encoders/Qwen3-4B-Instruct-2507-Q4_K_M.gguf",
+	},
+};
+
+/**
+ * Resolve a tier id (or raw model id) to its default image-gen model.
+ * Returns null when the input doesn't match any known tier — caller
+ * surfaces a clear error.
+ */
+export function resolveDefaultImageGenModel(keyOrTier: string): {
+	modelId: string;
+	file: string;
+	splitDiffusionModel?: boolean;
+	vae?: string;
+	llm?: string;
+} | null {
+	const direct = TIER_TO_DEFAULT_IMAGE_MODEL[keyOrTier];
+	if (direct) return direct;
+	// Allow callers to pass the bare model id straight through; if it
+	// matches a known model file in the per-tier map we echo it back.
+	for (const entry of Object.values(TIER_TO_DEFAULT_IMAGE_MODEL)) {
+		if (entry.modelId === keyOrTier) return entry;
+	}
+	return null;
+}