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

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

@@ -0,0 +1,163 @@
+/**
+ * AOSP vision-describe backend contract (WS2).
+ *
+ * The bun:ffi llama.cpp binding in `@elizaos/plugin-aosp-local-inference`
+ * already exposes the embedding helpers (`llama_set_embeddings`,
+ * `llama_get_embeddings_seq`) and the model/context lifecycle. mtmd
+ * (multi-modal definition) is part of upstream llama.cpp from b8198+
+ * but the libeliza-llama-shim that the AOSP binding loads does NOT
+ * yet export the matching `eliza_llama_mtmd_*` symbols.
+ *
+ * This file is the JS contract for the FFI binding the AOSP plugin
+ * will add when the native side ships. It lives in
+ * `plugin-local-inference` (not in `plugin-aosp-local-inference`) so
+ * cross-plugin consumers can compile against the same interface
+ * regardless of platform. When the AOSP shim ships the native
+ * symbols, the implementation in `plugin-aosp-local-inference/src/
+ * aosp-llama-vision.ts` (to be added) will satisfy this contract.
+ *
+ * Required native symbols (libeliza-llama-shim):
+ *
+ *   eliza_llama_mtmd_init_from_file(
+ *     mmproj_path: const char *,
+ *     out_handle: void **
+ *   ) -> int32  // 0 = ok; non-zero = error code
+ *
+ *   eliza_llama_mtmd_free(mtmd_handle: void *) -> void
+ *
+ *   eliza_llama_mtmd_encode(
+ *     mtmd_handle: void *,
+ *     image_bytes: const uint8_t *,
+ *     image_len: size_t,
+ *     out_tokens_ptr: float **,   // owned by mtmd; valid until next encode
+ *     out_token_count: int32 *,
+ *     out_hidden_size: int32 *
+ *   ) -> int32
+ *
+ *   eliza_llama_decode_with_mmproj(
+ *     ctx: void *,                  // existing llama_context
+ *     mtmd_tokens: const float *,
+ *     mtmd_token_count: int32,
+ *     mtmd_hidden_size: int32,
+ *     prompt: const char *,
+ *     prompt_len: size_t,
+ *     max_tokens: int32,
+ *     temperature: float,
+ *     out_text_buf: char *,         // caller-allocated
+ *     out_text_buf_cap: size_t,
+ *     out_text_written: size_t *
+ *   ) -> int32
+ *
+ * Optional fast path: if the shim adds
+ *
+ *   eliza_llama_mtmd_describe(
+ *     model: void *,                // existing llama_model
+ *     ctx: void *,                  // existing llama_context
+ *     mtmd_handle: void *,
+ *     image_bytes: const uint8_t *,
+ *     image_len: size_t,
+ *     prompt: const char *,
+ *     prompt_len: size_t,
+ *     max_tokens: int32,
+ *     temperature: float,
+ *     out_buf: char *,
+ *     out_buf_cap: size_t,
+ *     out_written: size_t *
+ *   ) -> int32
+ *
+ * that single-call wrapper is preferred — it lets the shim fuse the
+ * encode+decode steps internally and avoids the round-trip of token
+ * pointers across the FFI boundary (which bun:ffi handles, but at the
+ * cost of two extra pointer dereferences per frame).
+ *
+ * Until the native side exports those symbols, this module's `loadAospVisionBackend`
+ * throws a structured error that the arbiter / handler can surface as
+ * "vision not available on this platform". It does NOT register
+ * silently — silent unavailability would let the runtime fall back to
+ * the cloud path on a mobile device that explicitly disabled it.
+ */
+
+import { existsSync } from "node:fs";
+import { VisionBackendUnavailableError } from "./capacitor-llama";
+import type { VisionDescribeBackend, VisionDescribeLoadArgs } from "./types";
+
+/**
+ * The AOSP binding's mtmd surface, when present. The AOSP plugin
+ * registers an instance under the runtime service name
+ * `"aosp-llama-mtmd"` once the native shim exports the symbols above.
+ */
+export interface AospLlamaMtmdBinding {
+	/** True when libeliza-llama-shim.so was loaded and exports the mtmd symbols. */
+	hasMtmd(): boolean;
+	/** Initialize an mtmd handle for the given mmproj path. */
+	initMtmd(args: { mmprojPath: string }): Promise<AospMtmdHandle>;
+}
+
+export interface AospMtmdHandle {
+	/**
+	 * Single-call describe — wraps mtmd_encode + decode_with_chunks. The
+	 * AOSP shim's `eliza_llama_mtmd_describe` lands here. Backends that
+	 * only have the split encode/decode symbols implement this on top
+	 * of two FFI calls; backends with the fused symbol use one.
+	 */
+	describe(args: {
+		imageBytes: Uint8Array;
+		prompt: string;
+		maxTokens?: number;
+		temperature?: number;
+		signal?: AbortSignal;
+	}): Promise<string>;
+	/** Free the mtmd handle (and any cached encode buffers). */
+	dispose(): Promise<void>;
+}
+
+export interface LoadAospVisionBackendOptions {
+	loadArgs: VisionDescribeLoadArgs;
+	mtmdBinding?: AospLlamaMtmdBinding;
+}
+
+export async function loadAospVisionBackend(
+	opts: LoadAospVisionBackendOptions,
+): Promise<VisionDescribeBackend> {
+	const { loadArgs, mtmdBinding } = opts;
+	if (!mtmdBinding?.hasMtmd()) {
+		throw new VisionBackendUnavailableError(
+			"aosp",
+			"binding_missing_mtmd",
+			"[vision/aosp] libeliza-llama-shim does not export the mtmd symbols. The AOSP shim needs eliza_llama_mtmd_init_from_file / _encode / _describe / _free. Until the native side exports them, vision-describe on AOSP falls back to the cloud path (or stays disabled when the user opted out of cloud).",
+		);
+	}
+	if (!existsSync(loadArgs.mmprojPath)) {
+		throw new VisionBackendUnavailableError(
+			"aosp",
+			"mmproj_missing",
+			`[vision/aosp] mmproj GGUF not found: ${loadArgs.mmprojPath}`,
+		);
+	}
+	const handle = await mtmdBinding.initMtmd({
+		mmprojPath: loadArgs.mmprojPath,
+	});
+	return {
+		id: "aosp",
+		async describe(request) {
+			const { resolveImageBytes } = await import("./hash");
+			const { bytes } = resolveImageBytes(request.image);
+			const text = await handle.describe({
+				imageBytes: bytes,
+				prompt: request.prompt ?? "Describe what is in this image.",
+				maxTokens: request.maxTokens,
+				temperature: request.temperature,
+				signal: request.signal,
+			});
+			const trimmed = text.trim();
+			if (!trimmed) {
+				throw new Error("[vision/aosp] empty text from mtmd_describe");
+			}
+			const title = trimmed.split(/[.!?]/, 1)[0]?.trim() || "Image";
+			return { title, description: trimmed, cacheHit: false };
+		},
+		async dispose() {
+			await handle.dispose();
+		},
+	};
+}

package/src/services/vision/capacitor-llama.ts

@@ -0,0 +1,255 @@
+/**
+ * Capacitor-llama vision-describe backend (WS2).
+ *
+ * Wraps the in-process capacitor-llama binding's multimodal projector
+ * (mtmd) surface and exposes the WS2 `VisionDescribeBackend` contract.
+ *
+ * State of the binding (2026-05-19):
+ *   `llama-cpp-capacitor`'s `LlamaContext` exposes `initMultimodal` and
+ *   `getMultimodalSupport`, which load an mmproj alongside the chat
+ *   target. The desktop bun:ffi shim does not yet bind those symbols —
+ *   the desktop FFI path returns `binding_missing_mtmd` until the shim
+ *   adds `mtmd_init_from_file` + the encode/decode helpers.
+ *
+ * What this module does today:
+ *   - Provides the WS2-shaped backend so plugin-vision / plugin-image-gen /
+ *     computer-use can compile against a stable contract.
+ *   - When the binding exposes the mtmd API, the backend dispatches
+ *     through it.
+ *   - Otherwise, the backend falls back to an injected
+ *     `VisionManagerLike` implementation when one is supplied (kept as a
+ *     pluggable seam for tests and out-of-tree integrations).
+ *   - When neither path is wired, `describe()` throws a structured
+ *     `VisionBackendUnavailableError` the arbiter surfaces upward.
+ *
+ * GPU validation status (this host has neither GPU):
+ *   The mtmd encode path is GPU-accelerated when the underlying llama.cpp
+ *   build dispatches `llama_image_t` through the model's batch path. We
+ *   document the on-device validation that's required for each GPU
+ *   family at the bottom of this file's tests (see
+ *   `__tests__/vision-describe.test.ts`). Until those run on real
+ *   hardware, GPU-backed vision is "implementation present, not
+ *   validated".
+ */
+
+import { existsSync, promises as fs } from "node:fs";
+import { resolveImageBytes } from "./hash";
+import type {
+	VisionDescribeBackend,
+	VisionDescribeBackendOptions,
+	VisionDescribeLoadArgs,
+	VisionDescribeRequest,
+	VisionDescribeResult,
+} from "./types";
+
+export class VisionBackendUnavailableError extends Error {
+	readonly code = "VISION_BACKEND_UNAVAILABLE";
+	constructor(
+		readonly backendId: string,
+		readonly reason:
+			| "binding_missing_mtmd"
+			| "no_fallback_present"
+			| "mmproj_missing",
+		message: string,
+	) {
+		super(message);
+		this.name = "VisionBackendUnavailableError";
+	}
+}
+
+/**
+ * Optional shape the Capacitor-llama binding exposes once the mtmd typed
+ * wrappers land in the shared adapter. The backend only consumes
+ * `describeWithMmproj`, which wraps `LlamaContext.initMultimodal` +
+ * `completion(...)` with `media_paths`. Backends that don't satisfy this
+ * shape are treated as "binding without mtmd support" and the fallback
+ * path is used.
+ */
+export interface CapacitorLlamaMtmdBinding {
+	loadVisionModel(args: {
+		modelPath: string;
+		mmprojPath: string;
+		gpuLayers?: number | "auto" | "max";
+		contextSize?: number;
+	}): Promise<CapacitorLlamaMtmdHandle>;
+}
+
+export interface CapacitorLlamaMtmdHandle {
+	describeWithMmproj(args: {
+		imageBytes: Uint8Array;
+		mimeType?: string;
+		prompt: string;
+		maxTokens?: number;
+		temperature?: number;
+		signal?: AbortSignal;
+		projectedTokens?: VisionDescribeBackendOptions["projectedTokens"];
+	}): Promise<{ text: string; projectorMs?: number; decodeMs?: number }>;
+	dispose(): Promise<void>;
+}
+
+/**
+ * Optional VisionManager-shape fallback. Kept available as a pluggable
+ * injection point for tests and out-of-tree integrations that want to
+ * supply their own image captioning implementation.
+ */
+export interface VisionManagerLike {
+	processImage(
+		dataUrl: string,
+	): Promise<{ title: string; description: string }>;
+}
+
+export interface CapacitorLlamaVisionBackendOptions {
+	loadArgs: VisionDescribeLoadArgs;
+	/**
+	 * Injected by tests and by the shared mtmd typed wrappers. When
+	 * provided the backend uses the mtmd path.
+	 */
+	mtmd?: CapacitorLlamaMtmdBinding;
+	/**
+	 * Caption-only fallback. Optional — when present the backend uses it
+	 * as last resort, after mtmd. Backends that have neither throw a
+	 * structured `VisionBackendUnavailableError`.
+	 */
+	visionManager?: VisionManagerLike;
+}
+
+const DEFAULT_PROMPT = "Describe what is in this image.";
+
+export async function loadCapacitorLlamaVisionBackend(
+	opts: CapacitorLlamaVisionBackendOptions,
+): Promise<VisionDescribeBackend> {
+	const { loadArgs, mtmd, visionManager } = opts;
+
+	if (mtmd) {
+		// Validate mmproj presence here so we surface a clean error before
+		// burning a load (the binding's own error would be cryptic).
+		if (!existsSync(loadArgs.mmprojPath)) {
+			throw new VisionBackendUnavailableError(
+				"capacitor-llama",
+				"mmproj_missing",
+				`[vision/capacitor-llama] mmproj GGUF not found: ${loadArgs.mmprojPath}`,
+			);
+		}
+		const handle = await mtmd.loadVisionModel({
+			modelPath: loadArgs.modelPath,
+			mmprojPath: loadArgs.mmprojPath,
+			gpuLayers: loadArgs.gpuLayers,
+			contextSize: loadArgs.contextSize,
+		});
+		return {
+			id: "capacitor-llama",
+			async describe(
+				request: VisionDescribeRequest,
+				args?: VisionDescribeBackendOptions,
+			): Promise<VisionDescribeResult> {
+				const { bytes, mimeType } = resolveImageBytes(request.image);
+				const result = await handle.describeWithMmproj({
+					imageBytes: bytes,
+					mimeType,
+					prompt: request.prompt ?? DEFAULT_PROMPT,
+					maxTokens: request.maxTokens,
+					temperature: request.temperature,
+					signal: request.signal,
+					projectedTokens: args?.projectedTokens,
+				});
+				return shapeResult(result.text, {
+					projectorMs: result.projectorMs,
+					decodeMs: result.decodeMs,
+					cacheHit: Boolean(args?.projectedTokens),
+				});
+			},
+			async dispose() {
+				await handle.dispose();
+			},
+		};
+	}
+
+	if (visionManager) {
+		return {
+			id: "capacitor-llama",
+			async describe(
+				request: VisionDescribeRequest,
+			): Promise<VisionDescribeResult> {
+				const dataUrl = await imageInputToDataUrl(request.image);
+				const result = await visionManager.processImage(dataUrl);
+				return {
+					title: result.title,
+					description: result.description,
+					cacheHit: false,
+				};
+			},
+			async dispose() {
+				// VisionManager is a process-singleton owned by LocalAIManager;
+				// its lifetime is decoupled from the WS2 backend. Disposing the
+				// backend here is a no-op — the manager stays warm for legacy
+				// callers that haven't moved off LocalAIManager.describeImage yet.
+			},
+		};
+	}
+
+	throw new VisionBackendUnavailableError(
+		"capacitor-llama",
+		"binding_missing_mtmd",
+		"[vision/capacitor-llama] no mtmd binding and no VisionManager fallback was provided. Wire up the Capacitor-llama mtmd adapter (initMultimodal + media_paths completion) or pass a VisionManager fallback in options.",
+	);
+}
+
+function shapeResult(
+	text: string,
+	telemetry: { projectorMs?: number; decodeMs?: number; cacheHit?: boolean },
+): VisionDescribeResult {
+	const trimmed = text.trim();
+	if (!trimmed) {
+		throw new Error("[vision/capacitor-llama] backend returned empty text");
+	}
+	const title = trimmed.split(/[.!?]/, 1)[0]?.trim() || "Image";
+	return {
+		title,
+		description: trimmed,
+		...telemetry,
+	};
+}
+
+async function imageInputToDataUrl(
+	input: VisionDescribeRequest["image"],
+): Promise<string> {
+	switch (input.kind) {
+		case "dataUrl":
+			return input.dataUrl;
+		case "base64":
+			return `data:${input.mimeType ?? "image/png"};base64,${input.base64}`;
+		case "bytes": {
+			const mimeType = input.mimeType ?? "image/png";
+			const base64 = Buffer.from(input.bytes).toString("base64");
+			return `data:${mimeType};base64,${base64}`;
+		}
+		case "url": {
+			const url = input.url;
+			if (url.startsWith("data:")) return url;
+			if (url.startsWith("file://") || url.startsWith("/")) {
+				const filePath = url.startsWith("file://") ? url.slice(7) : url;
+				const bytes = await fs.readFile(filePath);
+				const mimeType = input.mimeType ?? guessMimeFromPath(filePath);
+				return `data:${mimeType};base64,${bytes.toString("base64")}`;
+			}
+			const res = await fetch(url);
+			if (!res.ok) {
+				throw new Error(
+					`[vision/capacitor-llama] failed to fetch image: ${res.status} ${res.statusText}`,
+				);
+			}
+			const buf = new Uint8Array(await res.arrayBuffer());
+			const mimeType =
+				input.mimeType ?? res.headers.get("content-type") ?? "image/png";
+			return `data:${mimeType};base64,${Buffer.from(buf).toString("base64")}`;
+		}
+	}
+}
+
+function guessMimeFromPath(p: string): string {
+	const lower = p.toLowerCase();
+	if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
+	if (lower.endsWith(".webp")) return "image/webp";
+	if (lower.endsWith(".gif")) return "image/gif";
+	return "image/png";
+}

package/src/services/vision/cloud-fallback.test.ts

@@ -0,0 +1,243 @@
+/**
+ * IMAGE_DESCRIPTION fallback chain tests.
+ *
+ * Exercises the local→cloud→vast wrappers in isolation. The wrappers are
+ * pure functions over an injected `fetch`, so we never touch global env
+ * here — every knob is passed in via options.
+ *
+ * What we assert:
+ *  - Local success: cloud `fetch` is never called.
+ *  - Local fallback: cloud `fetch` is invoked with the right URL/body/auth.
+ *  - Cloud 5xx: the cloud-wrapped handler re-emits a `{kind:"fallback"}` so
+ *    the vast layer can take over; vast `fetch` is then invoked.
+ *  - Both unavailable (no token / no key): the original local fallback
+ *    propagates unchanged so an outer layer (or the runtime) can act.
+ */
+
+import type {
+	ImageDescriptionParams,
+	ImageDescriptionResult,
+} from "@elizaos/core";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+	type LocalImageDescriptionHandler,
+	type LocalVisionOutcome,
+	wrapImageDescriptionHandlerWithCloudFallback,
+} from "./cloud-fallback";
+import { wrapImageDescriptionHandlerWithVastFallback } from "./vast-fallback";
+
+// Quarantine the env vars the wrappers read so a developer machine that
+// happens to have ELIZA_CLOUD_TOKEN / ELIZA_VAST_* exported doesn't make the
+// "unconfigured" assertions flake into a real outbound HTTP call.
+const ENV_KEYS = [
+	"ELIZA_CLOUD_TOKEN",
+	"ELIZA_CLOUD_API_KEY",
+	"ELIZA_CLOUD_BASE_URL",
+	"ELIZA_VAST_BASE_URL",
+	"ELIZA_VAST_API_KEY",
+] as const;
+const savedEnv: Record<string, string | undefined> = {};
+
+beforeEach(() => {
+	for (const key of ENV_KEYS) {
+		savedEnv[key] = process.env[key];
+		delete process.env[key];
+	}
+});
+
+afterEach(() => {
+	for (const key of ENV_KEYS) {
+		if (savedEnv[key] === undefined) delete process.env[key];
+		else process.env[key] = savedEnv[key];
+	}
+});
+
+const PNG_URL = "https://example.invalid/cat.png";
+
+function jsonResponse(body: unknown, status = 200): Response {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "content-type": "application/json" },
+	});
+}
+
+function textResponse(body: string, status = 500): Response {
+	return new Response(body, {
+		status,
+		headers: { "content-type": "text/plain" },
+	});
+}
+
+function okLocal(result: ImageDescriptionResult): LocalImageDescriptionHandler {
+	return async () => result;
+}
+
+function fallbackLocal(
+	reason: LocalVisionOutcome extends { kind: "fallback"; reason: infer R }
+		? R
+		: never,
+): LocalImageDescriptionHandler {
+	return async () =>
+		({
+			kind: "fallback",
+			reason,
+		}) satisfies LocalVisionOutcome;
+}
+
+describe("wrapImageDescriptionHandlerWithCloudFallback", () => {
+	it("returns local result without invoking cloud when local succeeds", async () => {
+		const fetchMock = vi.fn();
+		const wrapped = wrapImageDescriptionHandlerWithCloudFallback(
+			okLocal({ title: "Cat", description: "A small ginger cat." }),
+			{ token: "tk_test", baseUrl: "https://cloud.test", fetch: fetchMock },
+		);
+		const result = await wrapped({
+			imageUrl: PNG_URL,
+		} as ImageDescriptionParams);
+		expect(result).toEqual({
+			title: "Cat",
+			description: "A small ginger cat.",
+		});
+		expect(fetchMock).not.toHaveBeenCalled();
+	});
+
+	it("invokes cloud /v1/vision/describe with bearer + body when local falls back", async () => {
+		const fetchMock = vi.fn(async () =>
+			jsonResponse({
+				title: "Cloud title",
+				description: "Cloud description.",
+			}),
+		);
+		const wrapped = wrapImageDescriptionHandlerWithCloudFallback(
+			fallbackLocal("local-unavailable"),
+			{ token: "tk_test", baseUrl: "https://cloud.test", fetch: fetchMock },
+		);
+		const result = await wrapped({
+			imageUrl: PNG_URL,
+			prompt: "describe",
+		} as ImageDescriptionParams);
+		expect(result).toEqual({
+			title: "Cloud title",
+			description: "Cloud description.",
+		});
+		expect(fetchMock).toHaveBeenCalledTimes(1);
+		const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+		expect(url).toBe("https://cloud.test/v1/vision/describe");
+		expect(init.method).toBe("POST");
+		expect((init.headers as Record<string, string>).authorization).toBe(
+			"Bearer tk_test",
+		);
+		const body = JSON.parse(init.body as string) as {
+			image: { kind: string; url: string };
+			prompt: string;
+		};
+		expect(body.image).toEqual({ kind: "url", url: PNG_URL });
+		expect(body.prompt).toBe("describe");
+	});
+
+	it("forwards URL inputs as-is (no local fetch first)", async () => {
+		const fetchMock = vi.fn(async () =>
+			jsonResponse({ title: "T", description: "D" }),
+		);
+		const wrapped = wrapImageDescriptionHandlerWithCloudFallback(
+			fallbackLocal("local-unavailable"),
+			{ token: "tk_test", baseUrl: "https://cloud.test", fetch: fetchMock },
+		);
+		await wrapped({ imageUrl: PNG_URL } as ImageDescriptionParams);
+		// Only one outbound call — to the cloud describe endpoint, not to the URL.
+		expect(fetchMock).toHaveBeenCalledTimes(1);
+		const [url] = fetchMock.mock.calls[0] as [string];
+		expect(url).toBe("https://cloud.test/v1/vision/describe");
+	});
+
+	it("propagates fallback when no cloud token is configured", async () => {
+		const fetchMock = vi.fn();
+		const wrapped = wrapImageDescriptionHandlerWithCloudFallback(
+			fallbackLocal("local-unavailable"),
+			{ baseUrl: "https://cloud.test", fetch: fetchMock },
+		);
+		const out = await wrapped({ imageUrl: PNG_URL } as ImageDescriptionParams);
+		expect(fetchMock).not.toHaveBeenCalled();
+		expect(out).toMatchObject({
+			kind: "fallback",
+			reason: "local-unavailable",
+		});
+	});
+
+	it("propagates fallback when cloud responds with 5xx", async () => {
+		const fetchMock = vi.fn(async () => textResponse("upstream down", 503));
+		const wrapped = wrapImageDescriptionHandlerWithCloudFallback(
+			fallbackLocal("local-error"),
+			{ token: "tk_test", baseUrl: "https://cloud.test", fetch: fetchMock },
+		);
+		const out = await wrapped({ imageUrl: PNG_URL } as ImageDescriptionParams);
+		expect(fetchMock).toHaveBeenCalledTimes(1);
+		expect(out).toMatchObject({ kind: "fallback", reason: "local-error" });
+		expect((out as { cause?: Error }).cause?.message ?? "").toContain("503");
+	});
+});
+
+describe("wrapImageDescriptionHandlerWithVastFallback", () => {
+	it("invokes vast when inner handler returns fallback and vast is configured", async () => {
+		const innerFetch = vi.fn(async () => textResponse("cloud sad", 503));
+		const inner = wrapImageDescriptionHandlerWithCloudFallback(
+			fallbackLocal("local-unavailable"),
+			{ token: "tk_test", baseUrl: "https://cloud.test", fetch: innerFetch },
+		);
+		const vastFetch = vi.fn(async () =>
+			jsonResponse({ title: "VTitle", description: "VDescription" }),
+		);
+		const wrapped = wrapImageDescriptionHandlerWithVastFallback(inner, {
+			baseUrl: "https://vast.test",
+			apiKey: "vast_key",
+			fetch: vastFetch,
+		});
+		const result = await wrapped({
+			imageUrl: PNG_URL,
+		} as ImageDescriptionParams);
+		expect(innerFetch).toHaveBeenCalledTimes(1);
+		expect(vastFetch).toHaveBeenCalledTimes(1);
+		const [url, init] = vastFetch.mock.calls[0] as [string, RequestInit];
+		expect(url).toBe("https://vast.test/v1/vision/describe");
+		expect(init.method).toBe("POST");
+		expect((init.headers as Record<string, string>).authorization).toBe(
+			"Bearer vast_key",
+		);
+		expect(result).toEqual({ title: "VTitle", description: "VDescription" });
+	});
+
+	it("does not call vast when inner handler succeeds", async () => {
+		const inner = wrapImageDescriptionHandlerWithCloudFallback(
+			okLocal({ title: "Local", description: "Local desc." }),
+			{ token: "tk_test", baseUrl: "https://cloud.test", fetch: vi.fn() },
+		);
+		const vastFetch = vi.fn();
+		const wrapped = wrapImageDescriptionHandlerWithVastFallback(inner, {
+			baseUrl: "https://vast.test",
+			apiKey: "vast_key",
+			fetch: vastFetch,
+		});
+		const result = await wrapped({
+			imageUrl: PNG_URL,
+		} as ImageDescriptionParams);
+		expect(vastFetch).not.toHaveBeenCalled();
+		expect(result).toEqual({ title: "Local", description: "Local desc." });
+	});
+
+	it("propagates fallback when both cloud and vast are unconfigured", async () => {
+		const inner = wrapImageDescriptionHandlerWithCloudFallback(
+			fallbackLocal("local-unavailable"),
+			{ fetch: vi.fn() },
+		);
+		const vastFetch = vi.fn();
+		const wrapped = wrapImageDescriptionHandlerWithVastFallback(inner, {
+			fetch: vastFetch,
+		});
+		const out = await wrapped({ imageUrl: PNG_URL } as ImageDescriptionParams);
+		expect(vastFetch).not.toHaveBeenCalled();
+		expect(out).toMatchObject({
+			kind: "fallback",
+			reason: "local-unavailable",
+		});
+	});
+});