pi-openai-toolkit 0.18.0 → 0.19.0

package/src/runtime.ts

@@ -1,5 +1,6 @@
-import type { Api, Model, ProviderHeaders } from "@earendil-works/pi-ai";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { convertToLlm, type AgentMessage } from "@earendil-works/pi-agent-core";
+import type { Api, Message, Model, ModelThinkingLevel, ProviderHeaders } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isExactModelAllowed } from "./model-scope";
 import {
 	CODEX_AFFINITY_SCOPE,
@@ -9,9 +10,13 @@ import { RESPONSES_COMPACT_CAPABLE_APIS } from "./types";
 
 const OPENAI_RESPONSES_PATH = "responses";
 const CODEX_RESPONSES_PATH = "codex/responses";
+const AZURE_RESPONSES_PATH = "responses";
 const OPENAI_COMPACT_PATH = "responses/compact";
 const CODEX_COMPACT_PATH = "codex/responses/compact";
+const AZURE_COMPACT_PATH = "responses/compact";
+const AZURE_DEFAULT_API_VERSION = "v1";
 const ALPHA_SEARCH_PATH = "alpha/search";
+export const VIRTUAL_MODEL_API = "pi-virtual" as const;
 
 export type ResponsesApi = (typeof RESPONSES_COMPACT_CAPABLE_APIS)[number];
 
@@ -26,10 +31,12 @@ export type ParsedModelSpec = {
 export type NativeCompactionFailureReason =
 	| "disabled"
 	| "missing-model"
+	| "virtual-model-unresolved"
 	| "invalid-model-spec"
 	| "model-not-found"
 	| "unsupported-api"
 	| "missing-base-url"
+	| "invalid-base-url"
 	| "missing-session-id"
 	| "missing-api-key"
 	| "auth-resolution-failed"
@@ -57,9 +64,13 @@ export type ResponsesCompatibleRequestPayload = {
 export type ResponsesRuntime = {
 	provider: string;
 	api: ResponsesApi;
+	/** Logical Pi model id. */
 	model: string;
+	/** Wire model/deployment id; usually the same as `model`. */
+	requestModel?: string;
 	baseUrl: string;
 	apiKey: string;
+	env?: Record<string, string>;
 	headers?: ProviderHeaders;
 	responsesPath: string;
 	responsesUrl: string;
@@ -131,9 +142,157 @@ type ResolvedRequestAuth =
 			apiKey?: string;
 			headers?: ProviderHeaders;
 			baseUrl?: string;
+			env?: Record<string, string>;
 	  }
 	| { ok: false; error: string };
 
+type VirtualModelRuntime = {
+	resolveModel?: (
+		model: RuntimeModel,
+		messages: readonly Message[],
+		options: {
+			reason: "direct";
+			thinkingLevel: ModelThinkingLevel;
+			signal?: AbortSignal;
+			state?: unknown;
+		},
+	) => Promise<{ model: RuntimeModel; thinkingLevel: ModelThinkingLevel; state?: unknown }>;
+	getPhysicalModel?: (provider: string, modelId: string) => RuntimeModel | undefined;
+};
+
+type ModelRegistryRuntimeBridge = {
+	runtime?: VirtualModelRuntime;
+};
+
+export type EffectiveModelResolution =
+	| { ok: true; model: RuntimeModel; virtual: boolean }
+	| { ok: false; reason: "missing-model" | "virtual-model-unresolved"; errorMessage?: string };
+
+const physicalModelCache = new WeakMap<object, Map<string, RuntimeModel>>();
+const physicalModelObserverApis = new WeakSet<object>();
+
+function modelKey(model: RuntimeModel): string {
+	return `${model.provider}/${model.id}`;
+}
+
+function getPhysicalModelCache(ctx: ExtensionContext): Map<string, RuntimeModel> {
+	const registry = ctx.modelRegistry as object;
+	let cache = physicalModelCache.get(registry);
+	if (!cache) {
+		cache = new Map<string, RuntimeModel>();
+		physicalModelCache.set(registry, cache);
+	}
+	return cache;
+}
+
+function sessionModelKey(ctx: ExtensionContext, model: RuntimeModel): string | undefined {
+	try {
+		const sessionId = ctx.sessionManager.getSessionId();
+		return sessionId ? `${sessionId}\u0000${modelKey(model)}` : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function isAssistantModelMessage(message: AgentMessage): message is AgentMessage & {
+	provider: string;
+	api: string;
+	model: string;
+} {
+	if (message.role !== "assistant") return false;
+	const candidate = message as unknown as Record<string, unknown>;
+	return typeof candidate.provider === "string" &&
+		typeof candidate.api === "string" &&
+		typeof candidate.model === "string";
+}
+
+/** Remember the physical model Pi actually used as a fallback for a virtual selection. */
+export function rememberPhysicalModel(ctx: ExtensionContext, message: AgentMessage): void {
+	const selected = ctx.model as RuntimeModel | undefined;
+	if (!selected || selected.api !== VIRTUAL_MODEL_API || !isAssistantModelMessage(message)) return;
+	const physical = ctx.modelRegistry.find(message.provider, message.model);
+	const key = sessionModelKey(ctx, selected);
+	if (physical && physical.api !== VIRTUAL_MODEL_API && key) {
+		getPhysicalModelCache(ctx).set(key, physical);
+	}
+}
+
+/**
+ * Register the fallback cache observer used by feature extensions. Pi 0.99
+ * exposes a resolver for fresh routes; the assistant message cache only helps
+ * when a host cannot expose that resolver after a physical response exists.
+ */
+export function registerPhysicalModelObserver(pi: ExtensionAPI): void {
+	if (physicalModelObserverApis.has(pi)) return;
+	physicalModelObserverApis.add(pi);
+	pi.on("message_end", (event, ctx) => {
+		rememberPhysicalModel(ctx, event.message);
+	});
+}
+
+async function resolveVirtualModel(ctx: ExtensionContext, model: RuntimeModel): Promise<EffectiveModelResolution> {
+	const cache = getPhysicalModelCache(ctx);
+	const key = sessionModelKey(ctx, model);
+	const bridge = ctx.modelRegistry as unknown as ModelRegistryRuntimeBridge;
+	const runtime = bridge.runtime;
+	if (typeof runtime?.resolveModel !== "function") {
+		const cached = key ? cache.get(key) : undefined;
+		if (cached) return { ok: true, model: cached, virtual: true };
+		return {
+			ok: false,
+			reason: "virtual-model-unresolved",
+			errorMessage: "Pi does not expose virtual-model routing to extensions.",
+		};
+	}
+
+	let messages: Message[];
+	try {
+		messages = convertToLlm(ctx.sessionManager.buildSessionProjection().messages);
+	} catch (error) {
+		return {
+			ok: false,
+			reason: "virtual-model-unresolved",
+			errorMessage: error instanceof Error ? error.message : String(error),
+		};
+	}
+
+	try {
+		const route = await runtime.resolveModel(model, messages, {
+			reason: "direct",
+			thinkingLevel: (ctx.thinkingLevel ?? "off") as ModelThinkingLevel,
+			signal: ctx.signal,
+		});
+		const physical = runtime.getPhysicalModel?.(route.model.provider, route.model.id)
+			?? ctx.modelRegistry.find(route.model.provider, route.model.id)
+			?? route.model;
+		if (!physical || physical.api === VIRTUAL_MODEL_API) {
+			return {
+				ok: false,
+				reason: "virtual-model-unresolved",
+				errorMessage: "Pi virtual-model routing did not return a physical model.",
+			};
+		}
+		if (key) cache.set(key, physical);
+		return { ok: true, model: physical, virtual: true };
+	} catch (error) {
+		return {
+			ok: false,
+			reason: "virtual-model-unresolved",
+			errorMessage: error instanceof Error ? error.message : String(error),
+		};
+	}
+}
+
+export async function resolveEffectiveModel(
+	ctx: ExtensionContext,
+	model: ExtensionContext["model"] = ctx.model,
+): Promise<EffectiveModelResolution> {
+	if (!model) return { ok: false, reason: "missing-model" };
+	const runtimeModel = model as RuntimeModel;
+	if (runtimeModel.api !== VIRTUAL_MODEL_API) return { ok: true, model: runtimeModel, virtual: false };
+	return resolveVirtualModel(ctx, runtimeModel);
+}
+
 function normalizeConfiguredApis(values: readonly string[] | undefined): Set<string> {
 	if (values === undefined) {
 		return new Set(RESPONSES_COMPACT_CAPABLE_APIS);
@@ -144,8 +303,12 @@ function normalizeConfiguredApis(values: readonly string[] | undefined): Set<str
 function resolveCodexGatewayAffinity(
 	model: RuntimeModel,
 	gatewayModels: readonly string[] | undefined,
+	logicalModel?: RuntimeModel,
 ): CodexAffinity | undefined {
-	if (model.api !== "openai-responses" || !isExactModelAllowed(model, gatewayModels ?? [])) {
+	const allowlist = gatewayModels ?? [];
+	const allowed = isExactModelAllowed(model, allowlist) ||
+		(logicalModel?.api === VIRTUAL_MODEL_API && isExactModelAllowed(logicalModel, allowlist));
+	if (model.api !== "openai-responses" || !allowed) {
 		return undefined;
 	}
 	return {
@@ -200,20 +363,81 @@ function buildCodexCompactUrl(baseUrl: string): string {
 	return `${buildCodexResponsesUrl(baseUrl)}/compact`;
 }
 
-export function buildResponsesUrl(baseUrl: string, api: ResponsesCompactApi): string {
-	return api === "openai-codex-responses" ? buildCodexResponsesUrl(baseUrl) : buildOpenAIResponsesUrl(baseUrl);
+function envValue(env: Record<string, string> | undefined, name: string): string | undefined {
+	const value = env?.[name]?.trim();
+	return value || undefined;
+}
+
+function buildAzureBaseUrl(baseUrl: string | undefined, env: Record<string, string> | undefined): string | undefined {
+	const configured = envValue(env, "AZURE_OPENAI_BASE_URL") ?? normalizeBaseUrl(baseUrl);
+	if (configured) return configured;
+	const resource = envValue(env, "AZURE_OPENAI_RESOURCE_NAME");
+	return resource ? `https://${resource}.openai.azure.com/openai/v1` : undefined;
+}
+
+function normalizeAzureBaseUrl(baseUrl: string): string {
+	const url = new URL(baseUrl);
+	const pathname = url.pathname.replace(/\/+$/, "");
+	if (pathname === "" || pathname === "/" || pathname === "/openai") url.pathname = "/openai/v1";
+	else if (pathname.endsWith("/responses")) url.pathname = pathname.slice(0, -"/responses".length);
+	url.search = "";
+	url.hash = "";
+	return url.toString().replace(/\/$/, "");
+}
+
+function appendAzureApiVersion(urlValue: string, env: Record<string, string> | undefined): string {
+	const url = new URL(urlValue);
+	if (!url.searchParams.has("api-version")) {
+		url.searchParams.set("api-version", envValue(env, "AZURE_OPENAI_API_VERSION") ?? AZURE_DEFAULT_API_VERSION);
+	}
+	return url.toString();
+}
+
+export function resolveAzureDeploymentName(modelId: string, env: Record<string, string> | undefined): string {
+	const mapping = envValue(env, "AZURE_OPENAI_DEPLOYMENT_NAME_MAP");
+	if (mapping) {
+		for (const entry of mapping.split(",")) {
+			const separator = entry.indexOf("=");
+			if (separator <= 0) continue;
+			if (entry.slice(0, separator).trim() === modelId) {
+				const deployment = entry.slice(separator + 1).trim();
+				if (deployment) return deployment;
+			}
+		}
+	}
+	return modelId;
+}
+
+export function buildResponsesUrl(
+	baseUrl: string,
+	api: ResponsesCompactApi,
+	env?: Record<string, string>,
+): string {
+	if (api === "openai-codex-responses") return buildCodexResponsesUrl(baseUrl);
+	if (api === "azure-openai-responses") {
+		return appendAzureApiVersion(`${normalizeAzureBaseUrl(baseUrl)}/${AZURE_RESPONSES_PATH}`, env);
+	}
+	return buildOpenAIResponsesUrl(baseUrl);
 }
 
 export function buildResponsesPath(api: ResponsesCompactApi): string {
-	return api === "openai-codex-responses" ? CODEX_RESPONSES_PATH : OPENAI_RESPONSES_PATH;
+	return api === "openai-codex-responses" ? CODEX_RESPONSES_PATH : AZURE_RESPONSES_PATH;
 }
 
-export function buildCompactUrl(baseUrl: string, api: ResponsesCompactApi): string {
-	return api === "openai-codex-responses" ? buildCodexCompactUrl(baseUrl) : buildOpenAICompactUrl(baseUrl);
+export function buildCompactUrl(
+	baseUrl: string,
+	api: ResponsesCompactApi,
+	env?: Record<string, string>,
+): string {
+	if (api === "openai-codex-responses") return buildCodexCompactUrl(baseUrl);
+	if (api === "azure-openai-responses") {
+		return appendAzureApiVersion(`${normalizeAzureBaseUrl(baseUrl)}/${AZURE_COMPACT_PATH}`, env);
+	}
+	return buildOpenAICompactUrl(baseUrl);
 }
 
 export function buildCompactPath(api: ResponsesCompactApi): string {
-	return api === "openai-codex-responses" ? CODEX_COMPACT_PATH : OPENAI_COMPACT_PATH;
+	return api === "openai-codex-responses" ? CODEX_COMPACT_PATH : AZURE_COMPACT_PATH;
 }
 
 /**
@@ -332,8 +556,27 @@ async function resolveNativeCompactionEnvironmentForModel(
 		};
 	}
 
-	const descriptor = getRuntimeModelDescriptor(currentModel);
-	if (!currentModel || !descriptor.provider || !descriptor.api || !descriptor.model) {
+	const originalDescriptor = getRuntimeModelDescriptor(currentModel);
+	if (!currentModel || !originalDescriptor.provider || !originalDescriptor.api || !originalDescriptor.model) {
+		return {
+			ok: false,
+			reason: "missing-model",
+			...originalDescriptor,
+		};
+	}
+
+	const effective = await resolveEffectiveModel(ctx, currentModel);
+	if (!effective.ok) {
+		return {
+			ok: false,
+			reason: effective.reason,
+			errorMessage: effective.errorMessage,
+			...originalDescriptor,
+		};
+	}
+	const effectiveModel = effective.model;
+	const descriptor = getRuntimeModelDescriptor(effectiveModel);
+	if (!descriptor.provider || !descriptor.api || !descriptor.model) {
 		return {
 			ok: false,
 			reason: "missing-model",
@@ -342,8 +585,8 @@ async function resolveNativeCompactionEnvironmentForModel(
 	}
 
 	// The compact endpoint is selected purely by API family: any provider speaking
-	// openai-responses/openai-codex-responses gets a native compact attempt and fails
-	// open (to the fallback model or pi's default) when the endpoint is missing.
+	// a validated Responses API gets a native compact attempt and fails open (to
+	// the fallback model or pi's default) when the endpoint is missing.
 	const configuredApis = normalizeConfiguredApis(options.responsesApis);
 	if (!configuredApis.has(descriptor.api) || !isSupportedApi(descriptor.api)) {
 		return {
@@ -362,21 +605,12 @@ async function resolveNativeCompactionEnvironmentForModel(
 				...descriptor,
 			};
 		}
-
-		if (payload.model !== descriptor.model) {
-			return {
-				ok: false,
-				reason: "payload-model-mismatch",
-				...descriptor,
-			};
-		}
-
 		requestPayload = payload;
 	}
 
 	let auth: ResolvedRequestAuth;
 	try {
-		auth = await resolveRequestAuth(ctx, currentModel);
+		auth = await resolveRequestAuth(ctx, effectiveModel);
 	} catch (error) {
 		return {
 			ok: false,
@@ -395,7 +629,11 @@ async function resolveNativeCompactionEnvironmentForModel(
 		};
 	}
 
-	const baseUrl = normalizeBaseUrl(auth.baseUrl) ?? descriptor.baseUrl;
+	const rawBaseUrl = normalizeBaseUrl(auth.baseUrl) ?? descriptor.baseUrl;
+	let baseUrl = rawBaseUrl;
+	if (descriptor.api === "azure-openai-responses") {
+		baseUrl = buildAzureBaseUrl(rawBaseUrl, auth.env);
+	}
 	if (!baseUrl) {
 		return {
 			ok: false,
@@ -403,8 +641,33 @@ async function resolveNativeCompactionEnvironmentForModel(
 			...descriptor,
 		};
 	}
+	if (descriptor.api === "azure-openai-responses") {
+		try {
+			baseUrl = normalizeAzureBaseUrl(baseUrl);
+		} catch (error) {
+			return {
+				ok: false,
+				reason: "invalid-base-url",
+				errorMessage: error instanceof Error ? error.message : String(error),
+				...descriptor,
+				baseUrl,
+			};
+		}
+	}
+
+	const requestModel = descriptor.api === "azure-openai-responses"
+		? resolveAzureDeploymentName(descriptor.model, auth.env)
+		: descriptor.model;
+	if (requestPayload && requestPayload.model !== descriptor.model && requestPayload.model !== requestModel) {
+		return {
+			ok: false,
+			reason: "payload-model-mismatch",
+			...descriptor,
+			baseUrl,
+		};
+	}
 
-	const codexAffinity = resolveCodexGatewayAffinity(currentModel, options.codexGatewayModels);
+	const codexAffinity = resolveCodexGatewayAffinity(effectiveModel, options.codexGatewayModels, currentModel);
 	const sessionId = resolveRuntimeSessionId(ctx);
 	if (codexAffinity && !sessionId) {
 		return {
@@ -430,17 +693,19 @@ async function resolveNativeCompactionEnvironmentForModel(
 			provider: descriptor.provider,
 			api: descriptor.api,
 			model: descriptor.model,
+			requestModel,
 			baseUrl,
 			apiKey: auth.apiKey,
+			env: auth.env,
 			headers: auth.headers,
 			responsesPath: buildResponsesPath(descriptor.api),
-			responsesUrl: buildResponsesUrl(baseUrl, descriptor.api),
+			responsesUrl: buildResponsesUrl(baseUrl, descriptor.api, auth.env),
 			compactPath: buildCompactPath(descriptor.api),
-			compactUrl: buildCompactUrl(baseUrl, descriptor.api),
+			compactUrl: buildCompactUrl(baseUrl, descriptor.api, auth.env),
 			sessionId,
 			codexAffinity,
 			payload: requestPayload,
-			currentModel,
+			currentModel: effectiveModel,
 		},
 	};
 }
@@ -459,8 +724,10 @@ export async function resolveResponsesEnvironment(
 			provider: runtime.provider,
 			api: runtime.api,
 			model: runtime.model,
+			requestModel: runtime.requestModel,
 			baseUrl: runtime.baseUrl,
 			apiKey: runtime.apiKey,
+			env: runtime.env,
 			headers: runtime.headers,
 			responsesPath: runtime.responsesPath,
 			responsesUrl: runtime.responsesUrl,

package/src/serializer.ts

@@ -178,6 +178,24 @@ export function serializeMessagesToCompactRequest<TApi extends Api>(args: {
 	};
 }
 
+/**
+ * Async compaction serializer used by live synthetic requests. Pi exposes model
+ * image limits and newer versions expose a public resize helper; keep the
+ * historical sync API for callers/tests while applying those limits only at the
+ * actual request edge.
+ */
+export async function serializeMessagesToCompactRequestWithLimits<TApi extends Api>(args: {
+	model: Model<TApi>;
+	messages: AgentMessage[];
+	instructions: string;
+}): Promise<NativeCompactionRequestBody> {
+	return {
+		model: args.model.id,
+		input: await serializeMessagesToResponsesInputWithLimits(args.model, args.messages),
+		instructions: sanitizeSurrogates(args.instructions),
+	};
+}
+
 export function serializeMessagesToResponsesInput<TApi extends Api>(
 	model: Model<TApi>,
 	messages: AgentMessage[],
@@ -186,6 +204,28 @@ export function serializeMessagesToResponsesInput<TApi extends Api>(
 	return serializeLlmMessagesToResponsesInput(model, convertToLlm(messages), options);
 }
 
+export async function serializeMessagesToResponsesInputWithLimits<TApi extends Api>(
+	model: Model<TApi>,
+	messages: AgentMessage[],
+	options: SerializeResponsesMessagesOptions = {},
+): Promise<ResponsesInputItem[]> {
+	return applyModelImageInputLimits(
+		model,
+		serializeMessagesToResponsesInput(model, messages, options),
+	);
+}
+
+export async function serializeLlmMessagesToResponsesInputWithLimits<TApi extends Api>(
+	model: Model<TApi>,
+	messages: Message[],
+	options: SerializeResponsesMessagesOptions = {},
+): Promise<ResponsesInputItem[]> {
+	return applyModelImageInputLimits(
+		model,
+		serializeLlmMessagesToResponsesInput(model, messages, options),
+	);
+}
+
 /**
  * Serialize Pi's normalized LLM message union without running `convertToLlm` again.
  * This keeps the system-message boundary directly testable while preserving the public
@@ -253,6 +293,180 @@ export function serializeLlmMessagesToResponsesInput<TApi extends Api>(
 	return input;
 }
 
+type ImageResizeOptions = {
+	maxWidth?: number;
+	maxHeight?: number;
+	maxBytes?: number;
+	jpegQuality?: number;
+};
+
+type ModelImageInputLimits = {
+	resize?: ImageResizeOptions;
+	maxPerMessage?: number;
+	maxPerRequest?: number;
+};
+
+type ResizeImageResult = {
+	data: string;
+	mimeType: string;
+};
+
+type ResizeImageFunction = (
+	inputBytes: Uint8Array,
+	mimeType: string,
+	options?: ImageResizeOptions,
+) => Promise<ResizeImageResult | null>;
+
+let resizeImageLoader: Promise<ResizeImageFunction | undefined> | undefined;
+
+function getModelImageInputLimits(model: Model<Api>): ModelImageInputLimits | undefined {
+	return (model as Model<Api> & { inputLimits?: { images?: ModelImageInputLimits } }).inputLimits?.images;
+}
+
+function readNonNegativeLimit(value: unknown, name: string): number | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+		throw new Error(`Model image input limit ${name} is invalid.`);
+	}
+	return value;
+}
+
+function normalizeResizeOptions(value: unknown): ImageResizeOptions | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const candidate = value as Record<string, unknown>;
+	const options: ImageResizeOptions = {};
+	for (const key of ["maxWidth", "maxHeight", "maxBytes"] as const) {
+		const number = candidate[key];
+		if (number === undefined) continue;
+		if (typeof number !== "number" || !Number.isFinite(number) || number <= 0) {
+			throw new Error(`Model image resize option ${key} is invalid.`);
+		}
+		options[key] = Math.floor(number);
+	}
+	if (candidate.jpegQuality !== undefined) {
+		if (
+			typeof candidate.jpegQuality !== "number" ||
+			!Number.isFinite(candidate.jpegQuality) ||
+			candidate.jpegQuality <= 0 ||
+			candidate.jpegQuality > 100
+		) {
+			throw new Error("Model image resize option jpegQuality is invalid.");
+		}
+		options.jpegQuality = candidate.jpegQuality;
+	}
+	return Object.keys(options).length > 0 ? options : undefined;
+}
+
+async function loadResizeImage(): Promise<ResizeImageFunction | undefined> {
+	resizeImageLoader ??= (async () => {
+		try {
+			const module = await import("@earendil-works/pi-coding-agent") as {
+				resizeImage?: ResizeImageFunction;
+			};
+			return typeof module.resizeImage === "function" ? module.resizeImage : undefined;
+		} catch {
+			// Pi 0.87 does not export the helper. The request must fail closed when
+			// a newer model explicitly requires a resize rather than sending a
+			// potentially oversized image unchanged.
+			return undefined;
+		}
+	})();
+	return resizeImageLoader;
+}
+
+function inputContentArray(item: ResponsesInputItem): ResponsesInputContentItem[] | undefined {
+	if (!item || typeof item !== "object" || Array.isArray(item)) return undefined;
+	const candidate = item as Record<string, unknown>;
+	if (candidate.type === "function_call_output") {
+		return Array.isArray(candidate.output) ? candidate.output as ResponsesInputContentItem[] : undefined;
+	}
+	return Array.isArray(candidate.content) ? candidate.content as ResponsesInputContentItem[] : undefined;
+}
+
+function isInputImage(item: ResponsesInputContentItem): item is ResponsesImageInputItem {
+	return item.type === "input_image";
+}
+
+function decodeDataImage(imageUrl: string): { mimeType: string; bytes: Uint8Array } {
+	const separator = imageUrl.indexOf(",");
+	const prefix = separator >= 0 ? imageUrl.slice(0, separator) : "";
+	if (!prefix.startsWith("data:") || !prefix.endsWith(";base64") || separator < 0) {
+		throw new Error("Model image input has an invalid data URL.");
+	}
+	const mimeType = prefix.slice("data:".length, -";base64".length);
+	if (!mimeType) throw new Error("Model image input has no MIME type.");
+	return { mimeType, bytes: Buffer.from(imageUrl.slice(separator + 1), "base64") };
+}
+
+async function resizeInputImage(
+	image: ResponsesImageInputItem,
+	options: ImageResizeOptions,
+): Promise<ResponsesImageInputItem> {
+	const resizeImage = await loadResizeImage();
+	if (!resizeImage) {
+		throw new Error("The active Pi version cannot resize an image required by model input limits.");
+	}
+	const source = decodeDataImage(image.image_url);
+	const resized = await resizeImage(source.bytes, source.mimeType, options);
+	if (!resized || typeof resized.data !== "string" || typeof resized.mimeType !== "string") {
+		throw new Error("Model image input could not be resized within the provider limits.");
+	}
+	return {
+		...image,
+		image_url: `data:${resized.mimeType};base64,${resized.data}`,
+	};
+}
+
+/** Enforce Pi's per-message/request image limits without mutating serialized input. */
+export async function applyModelImageInputLimits<TApi extends Api>(
+	model: Model<TApi>,
+	input: ResponsesInputItem[],
+): Promise<ResponsesInputItem[]> {
+	const limits = getModelImageInputLimits(model);
+	if (!limits) return input;
+
+	const maxPerMessage = readNonNegativeLimit(limits.maxPerMessage, "maxPerMessage");
+	const maxPerRequest = readNonNegativeLimit(limits.maxPerRequest, "maxPerRequest");
+	const resizeOptions = normalizeResizeOptions(limits.resize);
+	let requestImageCount = 0;
+	const output: ResponsesInputItem[] = [];
+
+	for (const item of input) {
+		const content = inputContentArray(item);
+		if (!content) {
+			output.push(item);
+			continue;
+		}
+		const imageCount = content.filter(isInputImage).length;
+		if (maxPerMessage !== undefined && imageCount > maxPerMessage) {
+			throw new Error(`Model accepts at most ${maxPerMessage} image(s) per message.`);
+		}
+		if (maxPerRequest !== undefined && requestImageCount + imageCount > maxPerRequest) {
+			throw new Error(`Model accepts at most ${maxPerRequest} image(s) per request.`);
+		}
+		requestImageCount += imageCount;
+
+		if (!resizeOptions || imageCount === 0) {
+			output.push(item);
+			continue;
+		}
+		const resizedContent: ResponsesInputContentItem[] = [];
+		for (const contentItem of content) {
+			resizedContent.push(isInputImage(contentItem)
+				? await resizeInputImage(contentItem, resizeOptions)
+				: contentItem);
+		}
+		const itemRecord = item as Record<string, unknown>;
+		if (itemRecord.type === "function_call_output") {
+			output.push({ ...item, output: resizedContent } as ResponsesInputItem);
+		} else {
+			output.push({ ...item, content: resizedContent } as ResponsesInputItem);
+		}
+	}
+
+	return output;
+}
+
 export function createResponsesInputParitySignature(input: readonly unknown[]): string[] {
 	return input.map(describeResponsesInputItem);
 }