@linxiraos/pi-ai 1.2.0 → 1.3.0

package/src/judgment/native.ts

@@ -4,8 +4,8 @@
  *
  * Each judgment API is one wire dialect: TypeSafe's System One route
  * (`POST /v1/systemone`), OpenRouter Decisions (`POST /api/alpha/decisions`,
- * same body), Cloudflare Workers AI decision models (`POST /ai/run/{model}`,
- * same body in Cloudflare's envelope; `systemone.ts`), and OpenAI Decisions
+ * same body), Cloudflare Workers AI (`POST /ai/run/{model}`, same body plus
+ * top-level data URL images; `systemone.ts`), and OpenAI Decisions
  * (`POST /v1/decisions`, translated both ways; `openai-decisions.ts`).
  * Credentials flow through {@link withAuth}, so a stored key rotates on
  * 401/403 exactly like chat providers; transient 429/5xx responses retry with
@@ -19,16 +19,18 @@
  * (`rules/auth/typesafe.kdl`), `TYPESAFE_BASE_URL` overrides the API root,
  * `TYPESAFE_DEFAULT_MODEL` the model.
  */
+import { resolveJudgmentImageInput, type JudgmentImageInput } from "@linxiraos/pi-catalog/compat/judgment-images";
 import { resolveJudgmentQuestionsMax } from "@linxiraos/pi-catalog/compat/judgment-questions";
 import { TYPESAFE_DEFAULT_BASE_URL } from "@linxiraos/pi-catalog/discovery";
 import type { Api, FetchImpl } from "@linxiraos/pi-catalog/types";
-import { $env, isRecord } from "@linxiraos/pi-utils";
+import { $env, isRecord, parseImageMetadata } from "@linxiraos/pi-utils";
 import { type ApiKey, withAuth } from "../auth-retry";
 import * as AIError from "../error";
-import type { Model, Usage } from "../types";
+import { validateImageInput } from "../images/shared";
+import type { ImageContent, Model, Usage } from "../types";
 import { getRetryAfterMsFromHeaders } from "../utils/retry-after";
 import { openaiDecisionsWire } from "./openai-decisions";
-import { openrouterDecisionsWire, typesafeWire, workersAiWire } from "./systemone";
+import { openrouterDecisionsWire, referencedImageAssets, typesafeWire, workersAiWire } from "./systemone";
 import {
 	type Answer,
 	type Judge,
@@ -38,7 +40,8 @@ import {
 	type Questions,
 	tokenUsage,
 } from "./types";
-import type { JudgmentWire } from "./wire";
+import type { JudgmentImageAssets, JudgmentWire } from "./wire";
+export type { JudgmentImageAssets } from "./wire";
 
 export const TYPESAFE_PROVIDER = "typesafe";
 export const TYPESAFE_DEFAULT_MODEL = "jev-latest";
@@ -58,6 +61,48 @@ export function isJudgmentApi(api: Api): api is JudgmentApi {
 	return Object.hasOwn(JUDGMENT_WIRES, api);
 }
 
+/** Whether both the native protocol and catalog model support image input. */
+export function nativeJudgmentSupportsImages(model: Model): boolean {
+	return isJudgmentApi(model.api) && JUDGMENT_WIRES[model.api].images !== undefined && model.input.includes("image");
+}
+
+/**
+ * Whether `model`'s native judgment API takes these exact images: image support plus every documented
+ * transport and catalog bound. A judge chain skips a candidate that would refuse them instead of failing on it.
+ */
+export function nativeJudgmentAcceptsImages(model: Model, images: readonly ImageContent[]): boolean {
+	if (!isJudgmentApi(model.api) || !model.input.includes("image")) return false;
+	const wireLimits = JUDGMENT_WIRES[model.api].images;
+	if (wireLimits === undefined || imageLimitViolation(images, wireLimits) !== undefined) return false;
+	const modelLimits = resolveJudgmentImageInput(model);
+	return modelLimits === undefined || imageLimitViolation(images, modelLimits) === undefined;
+}
+
+/**
+ * Reject images that `model`'s native judgment API cannot take — no image support, an unsupported or
+ * unreferenced asset, or a transport or catalog bound exceeded — before any credential or upstream work.
+ * @throws {AIError.ValidationError} naming the reason.
+ */
+export function checkNativeJudgmentImages(
+	model: Model,
+	request: JudgmentRequest,
+	imageAssets?: JudgmentImageAssets,
+): void {
+	const label = `${model.provider}/${model.id}`;
+	if (isJudgmentApi(model.api)) {
+		checkJudgmentImages(
+			label,
+			JUDGMENT_WIRES[model.api],
+			model.input.includes("image"),
+			request,
+			imageAssets,
+			resolveJudgmentImageInput(model),
+		);
+	} else if ((request.images?.length ?? 0) > 0 || Object.keys(imageAssets ?? {}).length > 0) {
+		throw new AIError.ValidationError(`Native judgment backend ${label} does not support image inputs`);
+	}
+}
+
 /** `TYPESAFE_BASE_URL` when set, else the public API root; trailing slashes stripped. */
 export function typesafeBaseUrl(): string {
 	return ($env.TYPESAFE_BASE_URL?.trim() || TYPESAFE_DEFAULT_BASE_URL).replace(/\/+$/, "");
@@ -92,10 +137,19 @@ export interface NativeJudgeOptions extends NativeJudgeConnection {
 	 * requests are split. Unset: no cap.
 	 */
 	maxQuestions?: number;
+	/**
+	 * Whether images are enabled for this judge. `false` disables image input; `true` enables
+	 * dialects that require explicit opt-in but cannot enable a wire without image support.
+	 */
+	supportsImages?: boolean;
+	/** Catalog-selected image bounds, applied in addition to the wire's transport constraints. */
+	imageInput?: JudgmentImageInput;
 }
 
 /** Per-call options for {@link NativeJudge.judge}. */
 export interface NativeJudgeCallOptions extends JudgeOptions {
+	/** Assets keyed by their existing references; wires without asset transport reject them. */
+	imageAssets?: JudgmentImageAssets;
 	/**
 	 * Called before a split judgment rejects, with the summed usage of the chunks that had already
 	 * succeeded: billed upstream, but their answers are discarded with the failure. Not called when
@@ -128,8 +182,94 @@ function isAnswerOf(value: unknown, type: Answer["type"]): value is Answer {
 	return isRecord(value) && value.type === type;
 }
 
+/** The first documented cap `images` exceed, phrased to follow the backend label; `undefined` when within every cap. */
+function imageLimitViolation(images: readonly ImageContent[], limits: JudgmentImageInput): string | undefined {
+	if (limits.maxCount !== undefined && images.length > limits.maxCount) {
+		return `accepts at most ${limits.maxCount} images, got ${images.length}`;
+	}
+	let totalBytes = 0;
+	const { minPixels, maxPixels, minSide, maxSide } = limits;
+	const checkDimensions =
+		minPixels !== undefined || maxPixels !== undefined || minSide !== undefined || maxSide !== undefined;
+	const needsBytes = limits.maxBytes !== undefined || limits.maxTotalBytes !== undefined;
+	for (const [index, image] of images.entries()) {
+		const mimeType = image.mimeType.toLowerCase();
+		if (limits.mimeTypes && !limits.mimeTypes.includes(mimeType)) {
+			return `does not accept ${mimeType} images (images[${index}]); use ${limits.mimeTypes.join(", ")}`;
+		}
+		if (!needsBytes && !checkDimensions) continue;
+		const bytes = Buffer.from(image.data, "base64");
+		totalBytes += bytes.length;
+		if (limits.maxBytes !== undefined && bytes.length > limits.maxBytes) {
+			return `accepts images up to ${limits.maxBytes} bytes; images[${index}] is ${bytes.length} bytes`;
+		}
+		if (!checkDimensions) continue;
+		const metadata = parseImageMetadata(bytes);
+		if (!metadata?.width || !metadata.height) continue;
+		const { width, height } = metadata;
+		const size = `images[${index}] is ${width}x${height}`;
+		if (maxPixels !== undefined && width * height > maxPixels)
+			return `accepts images up to ${maxPixels} pixels; ${size}`;
+		if (minPixels !== undefined && width * height < minPixels) {
+			return `accepts images of at least ${minPixels} pixels; ${size}`;
+		}
+		if (maxSide !== undefined && Math.max(width, height) > maxSide) {
+			return `accepts images up to ${maxSide} pixels per side; ${size}`;
+		}
+		if (minSide !== undefined && Math.min(width, height) < minSide) {
+			return `accepts images of at least ${minSide} pixels per side; ${size}`;
+		}
+	}
+	if (limits.maxTotalBytes !== undefined && totalBytes > limits.maxTotalBytes) {
+		return `accepts at most ${limits.maxTotalBytes} image bytes per request, got ${totalBytes}`;
+	}
+	return undefined;
+}
+
+/**
+ * Reject images `wire` would refuse: assets on a wire without asset transport, images when they are
+ * disabled, an asset `request` never references (TypeSafe refuses those), malformed data, or a
+ * documented cap exceeded.
+ * @throws {AIError.ValidationError} naming the first problem.
+ */
+function checkJudgmentImages(
+	label: string,
+	wire: JudgmentWire,
+	imagesEnabled: boolean,
+	request: JudgmentRequest,
+	imageAssets: JudgmentImageAssets | undefined,
+	modelImageInput?: JudgmentImageInput,
+): void {
+	const assets = Object.values(imageAssets ?? {});
+	if (assets.length > 0 && wire.supportsImageAssets !== true) {
+		throw new AIError.ValidationError(`Native judgment backend ${label} does not support image assets`);
+	}
+	const images = [...(request.images ?? []), ...assets];
+	if (images.length === 0) return;
+	if (!imagesEnabled || wire.images === undefined) {
+		throw new AIError.ValidationError(`Native judgment backend ${label} does not support image inputs`);
+	}
+	if (imageAssets !== undefined && assets.length > 0) {
+		const referenced = referencedImageAssets(request, imageAssets);
+		for (const reference in imageAssets) {
+			if (Object.hasOwn(referenced, reference)) continue;
+			throw new AIError.ValidationError(
+				`Native judgment backend ${label}: image asset ${JSON.stringify(reference)} is not referenced in state, instructions, or criteria`,
+			);
+		}
+	}
+	for (const image of images) validateImageInput(image);
+	for (const limits of [wire.images, modelImageInput]) {
+		if (limits === undefined) continue;
+		const violation = imageLimitViolation(images, limits);
+		if (violation !== undefined) throw new AIError.ValidationError(`Native judgment backend ${label} ${violation}`);
+	}
+}
+
 export class NativeJudge implements Judge {
 	readonly label: string;
+	/** True when the selected native wire and model or direct-call option permit image input. */
+	readonly supportsImages?: boolean;
 	readonly api: JudgmentApi;
 	readonly provider: string;
 	/** Wire model id sent with every request. */
@@ -141,6 +281,7 @@ export class NativeJudge implements Judge {
 	readonly #fetch: FetchImpl;
 	readonly #timeoutMs: number;
 	readonly #maxQuestions: number | undefined;
+	readonly #imageInput: JudgmentImageInput | undefined;
 
 	constructor(options: NativeJudgeOptions) {
 		this.#apiKey = options.apiKey;
@@ -156,6 +297,9 @@ export class NativeJudge implements Judge {
 			throw new RangeError(`NativeJudge maxQuestions must be a positive integer, got ${options.maxQuestions}`);
 		}
 		this.#maxQuestions = options.maxQuestions;
+		this.#imageInput = options.imageInput;
+		const optedIntoImages = options.supportsImages ?? this.#wire.imagesRequireOptIn !== true;
+		if (this.#wire.images !== undefined && optedIntoImages) this.supportsImages = true;
 		this.label = `${this.provider}/${this.model}`;
 	}
 
@@ -163,12 +307,25 @@ export class NativeJudge implements Judge {
 		request: JudgmentRequest<Q>,
 		options?: NativeJudgeCallOptions,
 	): Promise<JudgmentResult<Q>> {
+		checkJudgmentImages(
+			this.label,
+			this.#wire,
+			this.supportsImages === true,
+			request,
+			options?.imageAssets,
+			this.#imageInput,
+		);
 		const ids = Object.keys(request.questions);
 		const cap = this.#maxQuestions;
 		if (cap !== undefined && ids.length > cap) return this.#judgeChunked(request, ids, cap, options);
 		return this.#judgeOnce(request, options);
 	}
 
+	/** Effective image detail for cache identity after applying this wire's forwarding behavior. */
+	effectiveImageDetail(detail: ImageContent["detail"]): ImageContent["detail"] {
+		return this.#wire.ignoresImageDetail ? undefined : detail;
+	}
+
 	/**
 	 * Answer `request` in requests of at most `cap` questions each, {@link CHUNK_PARALLEL} at a time;
 	 * answers merge and usage sums. The first failing chunk aborts its in-flight siblings and stops
@@ -189,14 +346,17 @@ export class NativeJudge implements Judge {
 		}
 		const failed = new AbortController();
 		const signal = options?.signal ? AbortSignal.any([options.signal, failed.signal]) : failed.signal;
-		const chunkOptions = { signal };
+		const imageAssets = options?.imageAssets;
 		const results: JudgmentResult[] = [];
 		let next = 0;
 		const drain = async (): Promise<void> => {
 			while (next < chunks.length && !signal.aborted) {
 				const index = next++;
+				const chunk = { ...request, questions: chunks[index] };
+				// TypeSafe refuses unreferenced assets: a chunk carries only those its own questions or the state use.
+				const chunkAssets = imageAssets === undefined ? undefined : referencedImageAssets(chunk, imageAssets);
 				try {
-					results[index] = await this.#judgeOnce({ state: request.state, questions: chunks[index] }, chunkOptions);
+					results[index] = await this.#judgeOnce(chunk, { signal, imageAssets: chunkAssets });
 				} catch (error) {
 					failed.abort(error);
 					throw error;
@@ -234,11 +394,13 @@ export class NativeJudge implements Judge {
 
 	async #judgeOnce<Q extends Questions>(
 		request: JudgmentRequest<Q>,
-		options: JudgeOptions | undefined,
+		options: NativeJudgeCallOptions | undefined,
 	): Promise<JudgmentResult<Q>> {
-		const body = JSON.stringify(this.#wire.encode(request, this.model));
+		const body = JSON.stringify(this.#wire.encode(request, this.model, options?.imageAssets));
+		const hasImages = (request.images?.length ?? 0) > 0 || Object.keys(options?.imageAssets ?? {}).length > 0;
+		const requestHeaders = hasImages ? this.#wire.imageHeaders : undefined;
 		const signal = options?.signal;
-		const payload = await withAuth(this.#apiKey, key => this.#attempt(body, key, signal), { signal });
+		const payload = await withAuth(this.#apiKey, key => this.#attempt(body, key, signal, requestHeaders), { signal });
 		const decoded = this.#wire.decode(payload);
 		if (!decoded) {
 			throw new AIError.ProviderResponseError(`${this.label} returned a malformed judgment response`, {
@@ -274,10 +436,16 @@ export class NativeJudge implements Judge {
 		};
 	}
 
-	async #attempt(body: string, key: string, signal: AbortSignal | undefined): Promise<unknown> {
+	async #attempt(
+		body: string,
+		key: string,
+		signal: AbortSignal | undefined,
+		requestHeaders: Readonly<Record<string, string>> | undefined,
+	): Promise<unknown> {
 		const target = this.#wire.target(this.baseUrl, this.model, key);
 		const headers: Record<string, string> = {
 			...this.#headers,
+			...requestHeaders,
 			Authorization: `Bearer ${target.token}`,
 			Accept: "application/json",
 			"Content-Type": "application/json",
@@ -329,5 +497,7 @@ export function createNativeJudge(model: Model, connection: NativeJudgeConnectio
 		model: model.requestModelId ?? model.id,
 		baseUrl: model.baseUrl,
 		maxQuestions: resolveJudgmentQuestionsMax(model),
+		supportsImages: nativeJudgmentSupportsImages(model),
+		imageInput: resolveJudgmentImageInput(model),
 	});
 }

package/src/judgment/openai-decisions.ts

@@ -7,7 +7,8 @@
  *
  * | System One                                  | Decisions                                     |
  * | ------------------------------------------- | --------------------------------------------- |
- * | `state` (text or JSON)                      | `input` (text; JSON state is serialized)      |
+ * | `state` (text or JSON)                      | `input` text (JSON serialized), or `input_text` for images |
+ * | separate images                            | ordered `input_image` data URLs in user input |
  * | question id                                 | `name`, echoed on its answer                  |
  * | `noul` + optional yes/no `criteria`         | `predicate`; criteria fold into instructions  |
  * | `choice` `criteria` option → rubric         | `choices: [{ value, description? }]`          |
@@ -19,6 +20,7 @@
  * tokens only, so cost is priced from the catalog model.
  */
 import { isRecord, prompt } from "@linxiraos/pi-utils";
+import { embeddedImageDataUrl } from "../images/shared";
 import predicateTemplate from "./openai-decisions-predicate.md" with { type: "text" };
 import { type Answer, type Question, tokenUsage } from "./types";
 import { finiteNumber, type JudgmentWire } from "./wire";
@@ -99,12 +101,31 @@ function decodeAnswer(entry: Record<string, unknown>): Answer | undefined {
 
 /** OpenAI's `/v1/decisions` route. */
 export const openaiDecisionsWire: JudgmentWire = {
+	// https://developers.openai.com/api/reference/resources/decisions/methods/create/
+	images: { maxCount: 128 },
 	target: (baseUrl, _model, key) => ({ url: `${baseUrl}/decisions`, token: key }),
-	encode: (request, model) => ({
-		model,
-		input: typeof request.state === "string" ? request.state : JSON.stringify(request.state),
-		questions: Object.entries(request.questions).map(([name, question]) => encodeQuestion(name, question)),
-	}),
+	encode: (request, model) => {
+		const state = typeof request.state === "string" ? request.state : JSON.stringify(request.state);
+		return {
+			model,
+			input: request.images?.length
+				? [
+						{
+							role: "user",
+							content: [
+								{ type: "input_text", text: state },
+								...request.images.map(image => ({
+									type: "input_image",
+									image_url: embeddedImageDataUrl(image),
+									...(image.detail !== undefined ? { detail: image.detail } : {}),
+								})),
+							],
+						},
+					]
+				: state,
+			questions: Object.entries(request.questions).map(([name, question]) => encodeQuestion(name, question)),
+		};
+	},
 	decode(payload) {
 		if (!isRecord(payload) || !Array.isArray(payload.answers)) return undefined;
 		const answers: Record<string, Answer> = {};

package/src/judgment/systemone.ts

@@ -1,6 +1,8 @@
 /**
- * TypeSafe System One dialects. The request body (`{ model, state, questions }`)
- * and answer map are TypeSafe's own, forwarded verbatim:
+ * TypeSafe and OpenRouter use the `{ model, state, questions }` body. Images
+ * join `state` without replacing it (see {@link stateWithImages}): TypeSafe as
+ * references to a top-level `assets` map, OpenRouter as `image_url` data URL
+ * parts. Cloudflare optionally accepts image data URLs in its envelope.
  *
  * - `typesafe`: `POST {baseUrl}/v1/systemone` — TypeSafe and every System One
  *   server (OpenJEV, Kev, self-hosted Clef, OpenCode Zen, Command Code).
@@ -8,15 +10,18 @@
  *   `/api/alpha`; usage adds the billed `cost` in USD.
  * - `workers-ai-systemone`: Cloudflare Workers AI's `POST {baseUrl}/{model}`
  *   (`/client/v4/accounts/<account>/ai/run/@cf/cloudflare/clef`). The body
- *   names the model by its last path segment (`clef`), the response arrives in
- *   Cloudflare's `{ result, success, errors }` envelope, and the credential is
- *   a Cloudflare API token plus the account id the URL needs.
+ *   names the model by its last path segment (`clef`), adds a top-level array
+ *   of base64 data URLs when images are supplied, and returns Cloudflare's
+ *   `{ result, success, errors }` envelope. The credential is a Cloudflare
+ *   API token plus the account id the URL needs.
  */
 import { parseCloudflareCredential } from "@linxiraos/pi-catalog/wire/cloudflare";
 import { $env, isRecord } from "@linxiraos/pi-utils";
 import * as AIError from "../error";
-import { tokenUsage } from "./types";
-import { type DecodedJudgment, finiteNumber, type JudgmentWire } from "./wire";
+import { embeddedImageDataUrl } from "../images/shared";
+import type { ImageContent } from "../types";
+import { type JsonValue, type JudgmentRequest, tokenUsage } from "./types";
+import { type DecodedJudgment, finiteNumber, type JudgmentImageAssets, type JudgmentWire } from "./wire";
 
 function decodeSystemOne(payload: unknown): DecodedJudgment | undefined {
 	if (!isRecord(payload) || !isRecord(payload.answers)) return undefined;
@@ -29,6 +34,63 @@ function decodeSystemOne(payload: unknown): DecodedJudgment | undefined {
 	};
 }
 
+/**
+ * `state` with `items` added and every original value kept: arrays gain them at the end, objects
+ * under the first free `__omp_judgment_images[_N]` key, and a string root becomes `[state, ...items]`.
+ */
+function stateWithImages(state: JudgmentRequest["state"], items: readonly JsonValue[]): JudgmentRequest["state"] {
+	if (Array.isArray(state)) return [...state, ...items];
+	if (!isRecord(state)) return [state, ...items];
+	const baseKey = "__omp_judgment_images";
+	let key = baseKey;
+	for (let suffix = 1; Object.hasOwn(state, key); suffix++) key = `${baseKey}_${suffix}`;
+	return { ...state, [key]: items };
+}
+
+function* jsonStrings(value: unknown): Generator<string> {
+	if (typeof value === "string") yield value;
+	else if (Array.isArray(value)) for (const item of value) yield* jsonStrings(item);
+	else if (isRecord(value)) for (const key in value) yield* jsonStrings(value[key]);
+}
+
+/**
+ * The subset of `assets` that `request` references. TypeSafe substitutes a reference wherever it
+ * occurs as text in a string of `state`, a question's `instructions`, or its `criteria` (never in
+ * object keys) and rejects a request carrying an unreferenced asset.
+ */
+export function referencedImageAssets(request: JudgmentRequest, assets: JudgmentImageAssets): JudgmentImageAssets {
+	const pending = new Set(Object.keys(assets));
+	const visit = (value: unknown): void => {
+		for (const text of jsonStrings(value)) {
+			if (pending.size === 0) return;
+			for (const reference of pending) if (text.includes(reference)) pending.delete(reference);
+		}
+	};
+	visit(request.state);
+	for (const id in request.questions) {
+		const question = request.questions[id];
+		visit(question.instructions);
+		visit(question.criteria);
+	}
+	// `fromEntries` defines own properties, so a `__proto__` reference stays an ordinary key.
+	return Object.fromEntries(Object.entries(assets).filter(([reference]) => !pending.has(reference)));
+}
+
+interface SystemOneImageAsset {
+	type: "image";
+	format: "png" | "jpeg";
+	data_base64: string;
+}
+
+function encodeSystemOneImage(image: ImageContent): SystemOneImageAsset {
+	const mimeType = image.mimeType.toLowerCase();
+	return {
+		type: "image",
+		format: mimeType === "image/png" ? "png" : "jpeg",
+		data_base64: Buffer.from(image.data, "base64").toString("base64"),
+	};
+}
+
 /** A System One dialect posting the verbatim request to `path` under the base URL with the key as bearer. */
 function systemOneWire(path: string): JudgmentWire {
 	return {
@@ -39,13 +101,71 @@ function systemOneWire(path: string): JudgmentWire {
 }
 
 /** TypeSafe's own route, shared by every System One server. */
-export const typesafeWire = systemOneWire("/v1/systemone");
+export const typesafeWire: JudgmentWire = {
+	...systemOneWire("/v1/systemone"),
+	images: { mimeTypes: ["image/png", "image/jpeg"] },
+	supportsImageAssets: true,
+	imagesRequireOptIn: true,
+	imageHeaders: { "TypeSafe-Danger-Zone-Images": "true" },
+	ignoresImageDetail: true,
+	encode(request, model, imageAssets) {
+		const suppliedAssets = Object.entries(imageAssets ?? {});
+		const images = request.images ?? [];
+		if (suppliedAssets.length === 0 && images.length === 0) {
+			return { state: request.state, model, questions: request.questions };
+		}
 
-/** OpenRouter Decisions: the System One body under `/api/alpha`. */
-export const openrouterDecisionsWire = systemOneWire("/decisions");
+		const assets: Record<string, SystemOneImageAsset> = Object.fromEntries(
+			suppliedAssets.map(([reference, image]) => [reference, encodeSystemOneImage(image)]),
+		);
+		const references: string[] = [];
+		for (const image of images) {
+			let reference = crypto.randomUUID();
+			while (Object.hasOwn(assets, reference)) reference = crypto.randomUUID();
+			assets[reference] = encodeSystemOneImage(image);
+			references.push(reference);
+		}
+
+		return {
+			state: references.length ? stateWithImages(request.state, references) : request.state,
+			model,
+			questions: request.questions,
+			assets,
+		};
+	},
+};
+
+/** OpenRouter Decisions: System One body under `/api/alpha`, with image parts preserved in state. */
+export const openrouterDecisionsWire: JudgmentWire = {
+	...systemOneWire("/decisions"),
+	images: {},
+	imagesRequireOptIn: true,
+	encode(request, model) {
+		const imageParts: JsonValue[] = (request.images ?? []).map(image => ({
+			type: "image_url",
+			image_url: {
+				url: embeddedImageDataUrl(image),
+				...(image.detail !== undefined ? { detail: image.detail === "original" ? "auto" : image.detail } : {}),
+			},
+		}));
+		return {
+			state: imageParts.length ? stateWithImages(request.state, imageParts) : request.state,
+			model,
+			questions: request.questions,
+		};
+	},
+};
 
 /** Cloudflare Workers AI decision models (Clef) through the account-scoped `ai/run` route. */
 export const workersAiWire: JudgmentWire = {
+	// Clef's `images` extension: https://developers.cloudflare.com/workers-ai/models/clef/
+	images: {
+		mimeTypes: ["image/png", "image/jpeg", "image/webp"],
+		maxCount: 4,
+		maxBytes: 4 * 1024 * 1024,
+		maxTotalBytes: 8 * 1024 * 1024,
+		maxPixels: 16_000_000,
+	},
 	target(baseUrl, model, key) {
 		const credential = parseCloudflareCredential(key);
 		const accountId = credential?.accountId ?? $env.CLOUDFLARE_ACCOUNT_ID?.trim();
@@ -60,6 +180,7 @@ export const workersAiWire: JudgmentWire = {
 		state: request.state,
 		model: model.slice(model.lastIndexOf("/") + 1),
 		questions: request.questions,
+		...(request.images?.length ? { images: request.images.map(embeddedImageDataUrl) } : {}),
 	}),
 	decode: payload => (isRecord(payload) ? decodeSystemOne(payload.result) : undefined),
 };

package/src/judgment/text.ts

@@ -2,8 +2,8 @@
  * Text bridge: answers {@link Questions} with any model that completes text.
  *
  * Questions render into one system prompt asking for keyword answers (an
- * option label, `yes`/`no`, or a level number); the state is the user message,
- * so the question part stays byte-identical across calls and prompt caches
+ * option label, `yes`/`no`, or a level number); the state is the user text block,
+ * with separate image content blocks beside it, so the question part stays byte-identical
  * hit. Several questions batch into a single completion answered one line per
  * question id. Answers are one-hot: a parsed keyword yields probability 1 and
  * confidence 1, since a text completion carries no distribution.
@@ -14,7 +14,8 @@
  */
 import { escapeXmlAttribute, escapeXmlText, prompt } from "@linxiraos/pi-utils";
 import { YAML } from "bun";
-import type { Usage } from "../types";
+import * as AIError from "../error";
+import type { ImageContent, Usage } from "../types";
 import textJudgeRetryTemplate from "./text-judge-retry.md" with { type: "text" };
 import textJudgeStateTemplate from "./text-judge-state.md" with { type: "text" };
 import textJudgeTemplate from "./text-judge.md" with { type: "text" };
@@ -35,6 +36,8 @@ import {
 export interface TextPrompt {
 	system: string;
 	user: string;
+	/** Images are kept as distinct content blocks, never rendered into JSON text. */
+	images?: readonly ImageContent[];
 	/** Format-correction attempt; chat backends may enforce tool suppression on the wire. */
 	retry?: boolean;
 }
@@ -50,6 +53,8 @@ export interface TextBackend {
 	readonly api: string;
 	readonly provider: string;
 	readonly model: string;
+	/** Whether this backend can send image content on the wire. */
+	readonly supportsImages?: boolean;
 	/** State guard for agent-tuned chat models; on-device classifier workers may disable it. */
 	readonly guardState?: boolean;
 	/** Format-correction retries after a completion cannot be parsed. */
@@ -107,10 +112,11 @@ function renderStateField(key: string, value: JsonValue): string {
 
 /**
  * Render a request: the system prompt carries the preamble and question
- * definitions (constant across states, so prompt caches hit); the user message
- * carries XML-field state followed by the answer-format cue. Small models act
- * on a bare request (answer it, emit tool calls) instead of classifying it —
- * explicit tags and the trailing cue keep them on task.
+ * definitions (constant across states, so prompt caches hit); the user text
+ * carries XML-field state followed by the answer-format cue. Images remain
+ * separate content blocks. Small models act on a bare request (answer it,
+ * emit tool calls) instead of classifying it — explicit tags and the trailing
+ * cue keep them on task.
  */
 export function renderJudgmentPrompt(request: JudgmentRequest, options: { guardState?: boolean } = {}): TextPrompt {
 	const questions: RenderedQuestion[] = [];
@@ -145,6 +151,7 @@ export function renderJudgmentPrompt(request: JudgmentRequest, options: { guardS
 			multi,
 			state: renderJudgmentState(request.state),
 		}),
+		...(request.images ? { images: request.images } : {}),
 	};
 }
 
@@ -262,11 +269,13 @@ export function parseAnswer(id: string, question: Question, reply: string): Answ
 }
 
 export class TextJudge implements Judge {
+	readonly supportsImages?: boolean;
 	readonly label: string;
 	readonly #backend: TextBackend;
 
 	constructor(backend: TextBackend) {
 		this.#backend = backend;
+		if (backend.supportsImages === true) this.supportsImages = true;
 		this.label = `${backend.provider}/${backend.model}`;
 	}
 
@@ -276,6 +285,9 @@ export class TextJudge implements Judge {
 	): Promise<JudgmentResult<Q>> {
 		const ids = Object.keys(request.questions);
 		if (ids.length === 0) throw new Error("judgment request has no questions");
+		if (request.images?.length && this.#backend.supportsImages !== true) {
+			throw new AIError.ValidationError(`Text judgment backend ${this.label} does not support image inputs`);
+		}
 		const rendered = renderJudgmentPrompt(request, { guardState: this.#backend.guardState });
 		const retries = this.#backend.parseRetries ?? 0;
 		for (let attempt = 0; ; attempt++) {
@@ -288,6 +300,7 @@ export class TextJudge implements Judge {
 								multi: ids.length > 1,
 							}),
 							user: rendered.user,
+							...(rendered.images ? { images: rendered.images } : {}),
 							retry: true,
 						};
 			const completion = await this.#backend.complete(textPrompt, options);

package/src/judgment/types.ts

@@ -11,7 +11,7 @@
  * bridge ({@link TextJudge}) renders the same questions into keyword prompts
  * for an ordinary chat model.
  */
-import type { Usage } from "../types";
+import type { ImageContent, Usage } from "../types";
 
 /** JSON-compatible value; readonly containers are accepted so `as const` state passes through. */
 export type JsonValue = string | number | boolean | null | readonly JsonValue[] | { readonly [key: string]: JsonValue };
@@ -80,6 +80,8 @@ export type AnswerFor<Q extends Question> =
 export interface JudgmentRequest<Q extends Questions = Questions> {
 	state: JudgmentState;
 	questions: Q;
+	/** Images evaluated alongside the state; never part of the JSON state itself. */
+	images?: readonly ImageContent[];
 }
 
 export interface JudgmentResult<Q extends Questions = Questions> {
@@ -97,6 +99,8 @@ export interface JudgeOptions {
 
 /** Answers typed questions about a state. Implementations are stateless and safe to share. */
 export interface Judge {
+	/** Whether this backend can consume separate image content blocks. */
+	readonly supportsImages?: boolean;
 	/** Backend description for logs, e.g. `typesafe/jev-latest`. */
 	readonly label: string;
 	judge<Q extends Questions>(request: JudgmentRequest<Q>, options?: JudgeOptions): Promise<JudgmentResult<Q>>;