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

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.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Soft cloud fallback wrapper for local IMAGE_DESCRIPTION handlers.
+ *
+ * The local vision path can report recoverable unavailability without forcing
+ * callers to know which remote provider is paired. The wrapper keeps that
+ * state explicit: handlers return a normal image description or a typed
+ * fallback outcome that the next layer can handle.
+ */
+import type { ImageDescriptionParams, ImageDescriptionResult } from "@elizaos/core";
+export type VisionFallbackReason = "local-unavailable" | "local-overloaded" | "local-error" | "local-aborted-pre-completion" | "local-not-registered" | "cloud-unavailable" | "cloud-error" | "vast-unavailable" | "vast-error";
+export type LocalVisionOutcome = ImageDescriptionResult | string | {
+    kind: "ok";
+    result: ImageDescriptionResult | string;
+} | {
+    kind: "fallback";
+    reason: VisionFallbackReason;
+    cause?: Error;
+};
+export type LocalVisionResult = Exclude<LocalVisionOutcome, {
+    kind: "fallback";
+    reason: VisionFallbackReason;
+    cause?: Error;
+}>;
+export type LocalImageDescriptionHandler = (params: ImageDescriptionParams | string) => Promise<LocalVisionOutcome>;
+export type WrappedImageDescriptionHandler = LocalImageDescriptionHandler;
+export interface VisionCloudFallbackOptions {
+    enabled?: boolean;
+    token?: string;
+    apiKey?: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    handler?: (params: ImageDescriptionParams | string, reason: VisionFallbackReason) => Promise<LocalVisionOutcome>;
+    log?: (message: string, detail?: Record<string, unknown>) => void;
+}
+export declare function classifyLocalVisionError(error: unknown): {
+    fallback: boolean;
+    reason: VisionFallbackReason;
+    cause?: Error;
+};
+export declare function isVisionFallbackOutcome(outcome: LocalVisionOutcome): outcome is {
+    kind: "fallback";
+    reason: VisionFallbackReason;
+    cause?: Error;
+};
+export declare function normalizeVisionDescription(result: LocalVisionResult): ImageDescriptionResult;
+export declare function wrapImageDescriptionHandlerWithCloudFallback(local: LocalImageDescriptionHandler, options?: VisionCloudFallbackOptions): WrappedImageDescriptionHandler;
+//# sourceMappingURL=cloud-fallback.d.ts.map

package/src/services/vision/cloud-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-fallback.d.ts","sourceRoot":"","sources":["cloud-fallback.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACX,sBAAsB,EACtB,sBAAsB,EACtB,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,oBAAoB,GAC7B,mBAAmB,GACnB,kBAAkB,GAClB,aAAa,GACb,8BAA8B,GAC9B,sBAAsB,GACtB,mBAAmB,GACnB,aAAa,GACb,kBAAkB,GAClB,YAAY,CAAC;AAEhB,MAAM,MAAM,kBAAkB,GAC3B,sBAAsB,GACtB,MAAM,GACN;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,oBAAoB,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAErE,MAAM,MAAM,iBAAiB,GAAG,OAAO,CACtC,kBAAkB,EAClB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,oBAAoB,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,CACjE,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG,CAC1C,MAAM,EAAE,sBAAsB,GAAG,MAAM,KACnC,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAEjC,MAAM,MAAM,8BAA8B,GAAG,4BAA4B,CAAC;AAE1E,MAAM,WAAW,0BAA0B;IAC1C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,OAAO,CAAC,EAAE,CACT,MAAM,EAAE,sBAAsB,GAAG,MAAM,EACvC,MAAM,EAAE,oBAAoB,KACxB,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACjC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CAClE;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG;IACzD,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,oBAAoB,CAAC;IAC7B,KAAK,CAAC,EAAE,KAAK,CAAC;CACd,CA2CA;AAED,wBAAgB,uBAAuB,CACtC,OAAO,EAAE,kBAAkB,GACzB,OAAO,IAAI;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,oBAAoB,CAAC;IAC7B,KAAK,CAAC,EAAE,KAAK,CAAC;CACd,CAOA;AAED,wBAAgB,0BAA0B,CACzC,MAAM,EAAE,iBAAiB,GACvB,sBAAsB,CAiCxB;AAqED,wBAAgB,4CAA4C,CAC3D,KAAK,EAAE,4BAA4B,EACnC,OAAO,GAAE,0BAA+B,GACtC,8BAA8B,CAyChC"}

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",
+		});
+	});
+});