pi-openai-toolkit 0.18.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openai-toolkit",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "private": false,
   "type": "module",
   "engines": {
@@ -38,7 +38,8 @@
       "./src/web-search/extension.ts",
       "./src/image-generation/extension.ts",
       "./src/auto-mode/extension.ts",
-      "./src/codex-astra/extension.ts"
+      "./src/codex-astra/extension.ts",
+      "./src/responses-websocket/extension.ts"
     ]
   },
   "files": [
@@ -89,6 +90,8 @@
     "src/auto-mode/types.ts",
     "src/codex-astra/effort-planner.ts",
     "src/codex-astra/extension.ts",
+    "src/responses-websocket/extension.ts",
+    "src/responses-websocket/transport.ts",
     "src/model-scope.ts",
     "src/native-fallback.ts",
     "src/payload-rewrite.ts",
@@ -126,10 +129,10 @@
     "@earendil-works/pi-tui": ">=0.87.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.87.0",
-    "@earendil-works/pi-ai": "0.87.0",
-    "@earendil-works/pi-coding-agent": "0.87.0",
-    "@earendil-works/pi-tui": "0.87.0",
+    "@earendil-works/pi-agent-core": "0.99.1",
+    "@earendil-works/pi-ai": "0.99.1",
+    "@earendil-works/pi-coding-agent": "0.99.1",
+    "@earendil-works/pi-tui": "0.99.1",
     "@types/node": "24.12.4",
     "bun": "1.2.23",
     "typescript": "5.9.3"

package/src/config/policy.ts

@@ -8,7 +8,7 @@ import {
 	type RemoteV2ContextSource,
 } from "../types";
 
-export type ConfigFeature = "context" | "webSearch" | "imageGeneration" | "autoMode" | "compatibility" | "diagnostics";
+export type ConfigFeature = "context" | "webSearch" | "imageGeneration" | "autoMode" | "compatibility" | "responsesWebSocket" | "diagnostics";
 export type SearchRoute = "unmanaged" | "local" | "hosted" | "standalone-alpha";
 export type DiagnosticsConfig = {
 	level: "error" | "warn" | "info" | "debug";
@@ -42,6 +42,7 @@ export type EffectiveToolkitPolicy = {
 	context: ContextPolicy;
 	webSearch: { route: SearchRoute };
 	imageGeneration: { enabled: boolean; defaultModel: string; allowedModels: string[] };
+	responsesWebSocket: { enabled: boolean };
 	autoMode: AutoModePolicy;
 	compatibility: { transport: "standard" | "codex-gateway" };
 	diagnostics: DiagnosticsConfig;
@@ -74,7 +75,7 @@ export type ConfigDocumentSnapshot = {
 	issues: ConfigIssue[];
 };
 export const CONFIG_FEATURES: readonly ConfigFeature[] = [
-	"context", "webSearch", "imageGeneration", "autoMode", "compatibility", "diagnostics",
+	"context", "webSearch", "imageGeneration", "autoMode", "compatibility", "responsesWebSocket", "diagnostics",
 ];
 
 /** Independent per-operation defaults, preserving the existing shipped policy. */
@@ -103,6 +104,7 @@ export function createPolicyDefaults(): EffectiveToolkitPolicy {
 			defaultModel: DEFAULT_IMAGE_GENERATION_MODEL,
 			allowedModels: [DEFAULT_IMAGE_GENERATION_MODEL],
 		},
+		responsesWebSocket: { enabled: false },
 		autoMode: {
 			...autoOptions,
 			available: false,

package/src/config/v2.ts

@@ -13,7 +13,7 @@
  * {
  *   "schemaVersion": 2,
  *   "$schema": "…metadata only…",
- *   "defaults": { "context": …, "webSearch": …, "imageGeneration": …, "autoMode": … },
+ *   "defaults": { "context": …, "webSearch": …, "imageGeneration": …, "responsesWebSocket": …, "autoMode": … },
  *   "models": { "provider/model-id": { "context": …, "webSearch": …, "autoMode": …, "compatibility": … } },
  *   "diagnostics": { … }
  * }
@@ -29,7 +29,8 @@
  *   raw values and unknown subtrees are never copied into diagnostics.
  * - `defaults.compatibility` is not a recognized scope: the standard transport is internal and
  *   the Codex gateway transport stays an exact-model opt-in.
- * - Image output settings (`defaults.imageGeneration`) and `diagnostics` are global only.
+ * - Image output settings (`defaults.imageGeneration`), Responses WebSocket transport
+ *   (`defaults.responsesWebSocket`), and `diagnostics` are global only.
  * - Exact model keys and model references use the legacy `provider/model-id` grammar: no
  *   whitespace, globs or bracket patterns. Keys are trimmed like the legacy decoder, and two
  *   raw keys that normalize to the same key are rejected instead of resolved last-wins.
@@ -120,7 +121,7 @@ const DIAGNOSTIC_LEVELS = ["error", "warn", "info", "debug"] as const;
 const LEGACY_ROOT_KEYS = ["compaction", "webSearch", "imageGeneration", "autoMode"] as const;
 
 const ROOT_KEYS = new Set(["$schema", "schemaVersion", "defaults", "models", "diagnostics"]);
-const DEFAULTS_KEYS = new Set(["context", "webSearch", "imageGeneration", "autoMode"]);
+const DEFAULTS_KEYS = new Set(["context", "webSearch", "imageGeneration", "responsesWebSocket", "autoMode"]);
 const MODEL_OVERRIDE_KEYS = new Set(["context", "webSearch", "autoMode", "compatibility"]);
 const CONTEXT_KEYS = new Set(["mode", "remoteCompaction", "nativeFallback", "remoteWindows"]);
 const REMOTE_COMPACTION_KEYS = new Set(["model", "inputSource", "allowContinuityBreak", "apis"]);
@@ -128,6 +129,7 @@ const NATIVE_FALLBACK_KEYS = new Set(["enabled", "model", "thinkingLevel"]);
 const REMOTE_WINDOWS_KEYS = new Set(["leaveManagedMode", "reminderThresholdPercent"]);
 const WEB_SEARCH_KEYS = new Set(["route"]);
 const IMAGE_GENERATION_KEYS = new Set(["enabled", "defaultModel", "allowedModels"]);
+const RESPONSES_WEBSOCKET_KEYS = new Set(["enabled"]);
 const AUTO_MODE_KEYS = new Set([
 	"available",
 	"reviewerModel",
@@ -170,6 +172,7 @@ const FEATURE_NAMES: ReadonlyMap<string, ConfigFeature> = new Map<string, Config
 	["compaction", "context"],
 	["webSearch", "webSearch"],
 	["imageGeneration", "imageGeneration"],
+	["responsesWebSocket", "responsesWebSocket"],
 	["autoMode", "autoMode"],
 	["compatibility", "compatibility"],
 	["diagnostics", "diagnostics"],
@@ -194,6 +197,7 @@ const POLICY_LEAVES: readonly { leaf: string; feature: ConfigFeature }[] = [
 	{ leaf: "imageGeneration.enabled", feature: "imageGeneration" },
 	{ leaf: "imageGeneration.defaultModel", feature: "imageGeneration" },
 	{ leaf: "imageGeneration.allowedModels", feature: "imageGeneration" },
+	{ leaf: "responsesWebSocket.enabled", feature: "responsesWebSocket" },
 	{ leaf: "autoMode.available", feature: "autoMode" },
 	{ leaf: "autoMode.reviewerModel", feature: "autoMode" },
 	{ leaf: "autoMode.gate", feature: "autoMode" },
@@ -841,6 +845,25 @@ function applyImageGenerationSettings(
 	);
 }
 
+function applyResponsesWebSocketSettings(
+	raw: Record<string, unknown>,
+	scope: Scope,
+	state: ResolutionState,
+): void {
+	reportUnknownKeys(raw, RESPONSES_WEBSOCKET_KEYS, scope, state, "responsesWebSocket");
+
+	applyField(
+		raw,
+		{ key: "enabled", leaf: "responsesWebSocket.enabled", feature: "responsesWebSocket" },
+		scope,
+		state,
+		readBoolean,
+		(value) => {
+			state.policy.responsesWebSocket.enabled = value;
+		},
+	);
+}
+
 function applyAutoModeSettings(
 	raw: Record<string, unknown>,
 	scope: Scope,
@@ -1149,6 +1172,15 @@ function applyImageGenerationScope(
 	if (group) applyImageGenerationSettings(group.raw, group.scope, state);
 }
 
+function applyResponsesWebSocketScope(
+	container: Record<string, unknown>,
+	scope: Scope,
+	state: ResolutionState,
+): void {
+	const group = openGroup(container, "responsesWebSocket", scope, state, "responsesWebSocket");
+	if (group) applyResponsesWebSocketSettings(group.raw, group.scope, state);
+}
+
 function applyAutoModeScope(
 	container: Record<string, unknown>,
 	scope: Scope,
@@ -1190,6 +1222,7 @@ function applyDefaults(doc: Record<string, unknown>, state: ResolutionState): vo
 	applyContextScope(raw, scope, state);
 	applyWebSearchScope(raw, scope, state);
 	applyImageGenerationScope(raw, scope, state);
+	applyResponsesWebSocketScope(raw, scope, state);
 	applyAutoModeScope(raw, scope, state);
 }
 

package/src/config.ts

@@ -208,6 +208,7 @@ function fromLegacy(loaded: LoadedToolkitConfig, model: WebSearchModel | undefin
 		defaultModel: config.imageGeneration.models[0],
 		allowedModels: [...config.imageGeneration.models],
 	};
+	policy.responsesWebSocket = { enabled: false };
 	const { enabled, models, reviewerModel, classifier, ...auto } = config.autoMode;
 	policy.autoMode = {
 		...structuredClone(auto),

package/src/context-management/codex-provider.ts

@@ -9,7 +9,7 @@ import {
 	filterCodexGatewayHeaders,
 } from "../responses-headers";
 export { CODEX_AFFINITY_SCOPE } from "../responses-headers";
-import { normalizeBaseUrl } from "../runtime";
+import { normalizeBaseUrl, resolveEffectiveModel, VIRTUAL_MODEL_API } from "../runtime";
 import { isExactModelAllowed } from "../model-scope";
 import {
 	isNonEmptyString,
@@ -172,17 +172,27 @@ export async function resolveCodexContextProvider(
 	modelOverride: ExtensionContext["model"] = ctx.model,
 	gatewayModels: readonly string[] = [],
 ): Promise<CodexContextProviderResolution> {
-	const model = modelOverride;
+	const selectedModel = modelOverride;
+	const selectedDescriptor = {
+		provider: selectedModel?.provider,
+		api: selectedModel?.api,
+		model: selectedModel?.id,
+		baseUrl: normalizeBaseUrl(selectedModel?.baseUrl),
+	};
+	const effective = await resolveEffectiveModel(ctx, selectedModel);
+	if (!effective.ok) return { ok: false, reason: "unsupported-model", ...selectedDescriptor };
+	const model = effective.model;
 	const descriptor = {
-		provider: model?.provider,
-		api: model?.api,
-		model: model?.id,
-		baseUrl: normalizeBaseUrl(model?.baseUrl),
+		provider: model.provider,
+		api: model.api,
+		model: model.id,
+		baseUrl: normalizeBaseUrl(model.baseUrl),
 	};
-	if (!model) return { ok: false, reason: "unsupported-model" };
 
 	const isNative = isNativeCodexModel(model);
-	const isGateway = isCodexGatewayModel(model, gatewayModels);
+	const isLogicalVirtualGateway = selectedModel?.api === VIRTUAL_MODEL_API && isExactModelAllowed(selectedModel, gatewayModels);
+	const isGateway = isCodexGatewayModel(model, gatewayModels) ||
+		(isLogicalVirtualGateway && model.api === GATEWAY_API);
 	if (!isNative && !isGateway) {
 		return { ok: false, reason: "unsupported-model", ...descriptor };
 	}

package/src/extension-runtime.ts

@@ -53,20 +53,22 @@ import {
 	rewriteResponsesPayloadWithNativeReplay,
 	hasInvalidatedCompactionContext,
 	removeNativeCompactionRetainedMessages,
-	serializeLiveTailToResponsesInput,
+	serializeLiveTailToResponsesInputWithLimits,
 } from "./payload-rewrite";
 import { getCompactionRequestExtras, rememberRequestContext } from "./request-context-cache";
 import { resolveWebSearchRoute } from "./web-search/types";
 import { executeRemoteV2Compaction } from "./remote-v2-client";
 import {
+	rememberPhysicalModel,
+	resolveEffectiveModel,
 	resolveNativeCompactionEnvironment,
 	resolveRemoteCompactionExecution,
 	parseModelSpec,
 	type RemoteCompactionExecution,
 } from "./runtime";
 import {
-	serializeMessagesToCompactRequest,
-	serializeMessagesToResponsesInput,
+	serializeMessagesToCompactRequestWithLimits,
+	serializeMessagesToResponsesInputWithLimits,
 	type NativeCompactionRequestBody,
 	type ResponsesInputItem,
 } from "./serializer";
@@ -183,6 +185,14 @@ function notifyWarning(ctx: ExtensionContext, message: string): void {
 	}
 }
 
+async function resolveContextCapabilityModel(
+	ctx: ExtensionContext,
+	model: ExtensionContext["model"] = ctx.model,
+): Promise<ExtensionContext["model"]> {
+	const effective = await resolveEffectiveModel(ctx, model);
+	return effective.ok ? effective.model : undefined;
+}
+
 async function isRemoteContextActive(
 	ctx: ExtensionContext,
 	config: CompactionConfig,
@@ -362,14 +372,14 @@ async function runResponsesNativeCompact(
 			}
 			const input: ResponsesInputItem[] = [
 				...(cloneOpaqueWindow(details.compactedWindow) as ResponsesInputItem[]),
-				...serializeMessagesToResponsesInput(
+				...(await serializeMessagesToResponsesInputWithLimits(
 					compactor.currentModel,
 					[...projection.messages.slice(summaryIndex + 1)],
 					{ firstSystemMessageIsUpdate: true },
-				),
+				)),
 			];
 			request = {
-				model: compactor.model,
+				model: compactor.requestModel ?? compactor.model,
 				input,
 				instructions,
 			};
@@ -377,10 +387,10 @@ async function runResponsesNativeCompact(
 			const liveTailEntries = branchEntries.slice(latestNativeCompaction.index + 1);
 			const input: ResponsesInputItem[] = [
 				...(cloneOpaqueWindow(details.compactedWindow) as ResponsesInputItem[]),
-				...serializeLiveTailToResponsesInput({ model: compactor.currentModel, entries: liveTailEntries }),
+				...(await serializeLiveTailToResponsesInputWithLimits({ model: compactor.currentModel, entries: liveTailEntries })),
 			];
 			request = {
-				model: compactor.model,
+				model: compactor.requestModel ?? compactor.model,
 				input,
 				instructions,
 			};
@@ -397,17 +407,19 @@ async function runResponsesNativeCompact(
 			if (!projection.ok) {
 				return { outcome: "unprojected-input", reason: projection.reason };
 			}
-			request = serializeMessagesToCompactRequest({
+			const serialized = await serializeMessagesToCompactRequestWithLimits({
 				model: compactor.currentModel,
 				messages: [...projection.messages],
 				instructions,
 			});
+			request = { ...serialized, model: compactor.requestModel ?? serialized.model };
 		} else {
-			request = serializeMessagesToCompactRequest({
+			const serialized = await serializeMessagesToCompactRequestWithLimits({
 				model: compactor.currentModel,
 				messages: getLegacySessionContextMessages(event, ctx),
 				instructions,
 			});
+			request = { ...serialized, model: compactor.requestModel ?? serialized.model };
 		}
 	} else {
 		writeDebugArtifact(
@@ -441,7 +453,7 @@ async function runResponsesNativeCompact(
 	const extras = getCompactionRequestExtras({
 		provider: consumer.provider,
 		api: consumer.api,
-		model: consumer.model,
+		model: consumer.requestModel ?? consumer.model,
 		baseUrl: consumer.baseUrl,
 		sessionId: getSessionId(ctx),
 	}, compactor.currentModel);
@@ -591,8 +603,9 @@ async function handleSessionBeforeCompact(
 
 	// Remote Context management owns this eligible Codex session. It persists a
 	// no-summary boundary and deliberately never calls remote_compaction_v2.
-	if (isCodexContextModel(ctx.model, config)) {
-		if (await remoteContextActive(ctx, config)) {
+	const contextModel = await resolveContextCapabilityModel(ctx);
+	if (isCodexContextModel(contextModel, config)) {
+		if (await remoteContextActive(ctx, config, contextModel)) {
 			try {
 				dependencies.contextWindows.synchronize(ctx);
 				if (event.reason === "manual" && dependencies.manualCompact && !dependencies.manualCompact.isMaintenance) {
@@ -864,6 +877,7 @@ async function handleContextInternal(
 	}
 
 	if (config.contextManagement === "remote") {
+		const contextModel = await resolveContextCapabilityModel(ctx);
 		try {
 			contextWindows.synchronize(ctx);
 		} catch {
@@ -873,7 +887,7 @@ async function handleContextInternal(
 			return undefined;
 		}
 
-		const remoteActive = await remoteContextActive(ctx, config);
+		const remoteActive = await remoteContextActive(ctx, config, contextModel);
 		if (remoteActive) {
 			try {
 				// Measure the provider-visible current window, not Pi's durable transcript.
@@ -902,8 +916,8 @@ async function handleContextInternal(
 		// older compaction-replay path. Gateway traffic must also fail closed when
 		// its transport capability is unavailable; otherwise Pi could send an
 		// ordinary unscoped request and lose CPA OAuth/session affinity.
-		if (isCodexContextModel(ctx.model, config)) {
-			if (isCodexGatewayModel(ctx.model, config.gatewayContextModels)) {
+		if (isCodexContextModel(contextModel, config)) {
+			if (isCodexGatewayModel(contextModel, config.gatewayContextModels)) {
 				notifyRemoteContextFailure(ctx, "codex-context-unavailable");
 				reportPiContextHookFailure(ctx, "codex-context-unavailable");
 				ctx.abort();
@@ -982,6 +996,9 @@ async function handleBeforeProviderRequest(
 		return undefined;
 	}
 
+	const contextModel = config.contextManagement === "remote"
+		? await resolveContextCapabilityModel(ctx)
+		: undefined;
 	if (config.contextManagement === "remote") {
 		try {
 			contextWindows.synchronize(ctx);
@@ -991,7 +1008,7 @@ async function handleBeforeProviderRequest(
 			return undefined;
 		}
 	}
-	if (config.contextManagement === "remote" && await remoteContextActive(ctx, config)) {
+	if (config.contextManagement === "remote" && await remoteContextActive(ctx, config, contextModel)) {
 		try {
 			return contextWindows.rewritePayload(event.payload, ctx);
 		} catch {
@@ -1000,12 +1017,12 @@ async function handleBeforeProviderRequest(
 			return undefined;
 		}
 	}
-	if (isCodexContextModel(ctx.model, config)) {
+	if (isCodexContextModel(contextModel, config)) {
 		// Keep Codex Remote mutually exclusive with the legacy replay pipeline
 		// when authentication or tool ownership is unavailable. Gateway traffic
 		// cannot continue as an ordinary Responses request because that would
 		// silently lose the required CPA session/account selection.
-		if (isCodexGatewayModel(ctx.model, config.gatewayContextModels)) {
+		if (isCodexGatewayModel(contextModel, config.gatewayContextModels)) {
 			notifyRemoteContextFailure(ctx, "codex-context-unavailable");
 			ctx.abort();
 		}
@@ -1057,7 +1074,7 @@ async function handleBeforeProviderRequest(
 		{
 			provider: runtime.provider,
 			api: runtime.api,
-			model: runtime.model,
+			model: runtime.requestModel ?? runtime.model,
 			baseUrl: runtime.baseUrl,
 			sessionId: getSessionId(ctx),
 		},
@@ -1255,11 +1272,12 @@ export default function registerCompactionExtension(
 		const config = resolved.config.compaction;
 		if (resolved.invalidFeatures.length > 0) return;
 		if (!config.enabled) return;
+		const contextModel = await resolveContextCapabilityModel(ctx);
 
 		let activationReason: string | undefined;
 		// Only models the built-in Remote Context coverage targets may activate or
 		// warn; everything else silently runs Pi's normal compaction path.
-		if (config.contextManagement === "remote" && isCodexContextModel(ctx.model, config) && !active) {
+		if (config.contextManagement === "remote" && isCodexContextModel(contextModel, config) && !active) {
 			if (syncOutcome.registrationState === "conflict") {
 				activationReason = "tool-name-conflict";
 				notifyRemoteContextFailure(ctx, activationReason);
@@ -1361,10 +1379,11 @@ export default function registerCompactionExtension(
 		const resolved = contextOperation(dependencies.loadConfig, ctx);
 		requireContextPolicy(resolved, ctx);
 		const config = resolved.config.compaction;
-		if (!isCodexContextModel(ctx.model, config)) return;
-		const active = await remoteContextActive(ctx, config);
+		const contextModel = await resolveContextCapabilityModel(ctx);
+		if (!isCodexContextModel(contextModel, config)) return;
+		const active = await remoteContextActive(ctx, config, contextModel);
 		if (!active) {
-			if (isCodexGatewayModel(ctx.model, config.gatewayContextModels)) {
+			if (isCodexGatewayModel(contextModel, config.gatewayContextModels)) {
 				notifyRemoteContextFailure(ctx, "codex-context-unavailable");
 				ctx.abort();
 			}
@@ -1402,11 +1421,13 @@ export default function registerCompactionExtension(
 		contextWindows.rewriteHeaders(event.headers, ctx);
 	});
 	pi.on("message_end", async (event, ctx) => {
+		rememberPhysicalModel(ctx, event.message);
 		const resolved = contextOperation(dependencies.loadConfig, ctx);
 		requireContextPolicy(resolved, ctx);
 		const config = resolved.config.compaction;
-		if (!isCodexContextModel(ctx.model, config) || !tools.isRegistered) return undefined;
-		if (!(await remoteContextActive(ctx, config))) return undefined;
+		const contextModel = await resolveContextCapabilityModel(ctx);
+		if (!isCodexContextModel(contextModel, config) || !tools.isRegistered) return undefined;
+		if (!(await remoteContextActive(ctx, config, contextModel))) return undefined;
 		const message = routeContextNamespaceToolMessage(event.message);
 		return message === event.message ? undefined : { message };
 	});

package/src/image-generation/artifacts.ts

@@ -20,13 +20,17 @@ import {
 } from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
+	IMAGE_GENERATION_MIME_TYPE,
 	MAX_IMAGE_PATH_CHARS,
 	ImageGenerationError,
+	imageFileExtension,
 	sanitizeImageDiagnostic,
+	type ImageGenerationMimeType,
 } from "./types";
 
 export type ExplicitOutputPlan = {
 	path: string;
+	extension?: string;
 };
 
 function isPathInsideOrEqual(root: string, candidate: string): boolean {
@@ -105,10 +109,15 @@ export async function prepareExplicitOutputPath(args: {
 }): Promise<ExplicitOutputPlan | undefined> {
 	if (args.rawPath === undefined) return undefined;
 	const trimmed = args.rawPath.trim();
-	if (!trimmed || trimmed.length > MAX_IMAGE_PATH_CHARS || extname(trimmed).toLowerCase() !== ".png") {
+	const extension = extname(trimmed).toLowerCase();
+	if (
+		!trimmed ||
+		trimmed.length > MAX_IMAGE_PATH_CHARS ||
+		![".png", ".jpg", ".jpeg", ".webp"].includes(extension)
+	) {
 		throw new ImageGenerationError(
 			"output-path-invalid",
-			"outputPath must be a non-empty .png file path.",
+			"outputPath must be a non-empty .png, .jpg, .jpeg, or .webp file path.",
 		);
 	}
 
@@ -127,7 +136,7 @@ export async function prepareExplicitOutputPath(args: {
 		realDirectory(args.agentDir),
 		realDirectory(args.ctx.cwd),
 	]);
-	if (isPathInsideOrEqual(agentRoot, target)) return { path: target };
+	if (isPathInsideOrEqual(agentRoot, target)) return { path: target, extension };
 
 	if (isPathInsideOrEqual(projectRoot, target)) {
 		if (!args.ctx.isProjectTrusted()) {
@@ -136,7 +145,7 @@ export async function prepareExplicitOutputPath(args: {
 				"Writing generated images inside an untrusted project is not allowed.",
 			);
 		}
-		return { path: target };
+		return { path: target, extension };
 	}
 
 	if (!args.ctx.hasUI) {
@@ -148,7 +157,7 @@ export async function prepareExplicitOutputPath(args: {
 	const approved = await args.ctx.ui.confirm(
 		"Write generated image outside safe roots?",
 		[
-			"The generated PNG will be copied to this external path without overwriting an existing file:",
+			"The generated image will be copied to this external path without overwriting an existing file:",
 			"",
 			target,
 			"",
@@ -160,7 +169,7 @@ export async function prepareExplicitOutputPath(args: {
 	if (!approved) {
 		throw new ImageGenerationError("output-path-declined", "External output path was declined.");
 	}
-	return { path: target };
+	return { path: target, extension };
 }
 
 async function publishBytesNoOverwrite(bytes: Uint8Array, target: string): Promise<void> {
@@ -190,15 +199,18 @@ export async function saveCanonicalImage(args: {
 	agentDir: string;
 	sessionId: string;
 	imageCallId: string;
+	mimeType?: ImageGenerationMimeType;
 }): Promise<string> {
 	const root = getGeneratedImagesRoot(args.agentDir);
+	const mimeType = args.mimeType ?? IMAGE_GENERATION_MIME_TYPE;
+	const extension = imageFileExtension(mimeType);
 	const sessionPart = sanitizePathPart(args.sessionId, "session");
 	const imagePart = sanitizePathPart(args.imageCallId, "image_generation");
 	const directory = join(root, sessionPart);
 
 	for (let index = 1; index <= 1000; index += 1) {
 		const suffix = index === 1 ? "" : `-${index}`;
-		const target = join(directory, `${imagePart}${suffix}.png`);
+		const target = join(directory, `${imagePart}${suffix}.${extension}`);
 		try {
 			await publishBytesNoOverwrite(args.bytes, target);
 			return target;
@@ -222,7 +234,16 @@ export async function saveCanonicalImage(args: {
 export async function copyImageToExplicitPath(args: {
 	bytes: Uint8Array;
 	plan: ExplicitOutputPlan;
+	mimeType?: ImageGenerationMimeType;
 }): Promise<void> {
+	const mimeType = args.mimeType ?? IMAGE_GENERATION_MIME_TYPE;
+	const extension = args.plan.extension ?? extname(args.plan.path).toLowerCase();
+	const expectedExtension = `.${imageFileExtension(mimeType)}`;
+	const extensionMatches = extension === expectedExtension ||
+		(mimeType === "image/jpeg" && extension === ".jpeg");
+	if (!extensionMatches) {
+		throw new Error(`Output path extension ${extension || "(none)"} does not match generated ${mimeType} data.`);
+	}
 	const currentTarget = await resolveWriteTarget(args.plan.path);
 	if (currentTarget !== args.plan.path) {
 		throw new Error("Output path changed after approval.");

package/src/image-generation/client.ts

@@ -60,13 +60,15 @@ function dataUrl(reference: PreparedReferenceImage): string {
 }
 
 function jsonRequestBody(runtime: ResponsesRuntime, body: ImageGenerationRequestBody): Record<string, unknown> {
-	const common = {
+	const common: Record<string, unknown> = {
 		model: body.model,
 		prompt: body.prompt,
 		n: body.n,
 		size: body.size,
-		quality: body.quality,
 	};
+	// `auto` is the Images API default, but some compatible gateways (including
+	// Grok image routes) reject the literal value instead of treating it as default.
+	if (body.quality !== "auto") common.quality = body.quality;
 	if (body.action === "edit") {
 		return {
 			...common,
@@ -84,7 +86,7 @@ function multipartRequestBody(body: ImageGenerationRequestBody): FormData {
 	form.append("prompt", body.prompt);
 	form.append("n", String(body.n));
 	form.append("size", body.size);
-	form.append("quality", body.quality);
+	if (body.quality !== "auto") form.append("quality", body.quality);
 	form.append("output_format", "png");
 	form.append("response_format", "b64_json");
 	for (const [index, reference] of body.references.entries()) {

package/src/image-generation/eligibility.ts

@@ -1,3 +1,4 @@
+import { VIRTUAL_MODEL_API } from "../runtime";
 import type { ImageGenerationConfig } from "../types";
 import { IMAGE_GENERATION_CAPABLE_APIS, type ImageGenerationModel } from "./types";
 
@@ -9,10 +10,14 @@ import { IMAGE_GENERATION_CAPABLE_APIS, type ImageGenerationModel } from "./type
 export function isImageGenerationEnabledForModel(
 	model: ImageGenerationModel | undefined,
 	config: ImageGenerationConfig,
+	effectiveModel: ImageGenerationModel | undefined = model,
 ): boolean {
-	return (
-		config.enabled &&
-		typeof model?.api === "string" &&
-		(IMAGE_GENERATION_CAPABLE_APIS as readonly string[]).includes(model.api)
-	);
+	if (!config.enabled) return false;
+	// A virtual model is only a candidate until execution resolves its physical
+	// model. The service performs that resolution and fails closed if it is not
+	// available; this keeps the tool discoverable instead of silently hiding a
+	// valid virtual route at startup.
+	if (model?.api === VIRTUAL_MODEL_API && effectiveModel === model) return true;
+	return typeof effectiveModel?.api === "string" &&
+		(IMAGE_GENERATION_CAPABLE_APIS as readonly string[]).includes(effectiveModel.api);
 }

package/src/image-generation/extension.ts

@@ -2,6 +2,7 @@ import { StringEnum, Type, type Static } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { loadToolkitConfig, resolveToolkitConfig } from "../config";
 import { notifyConfigIssues } from "../config/notifications";
+import { registerPhysicalModelObserver } from "../runtime";
 import { executeImageGeneration } from "./service";
 import { isImageGenerationEnabledForModel } from "./eligibility";
 import { renderImageGenerationResult } from "./render";
@@ -54,13 +55,13 @@ const GenerateImageParameters = Type.Object(
 				],
 				{
 					description:
-						"Use null when the user did not explicitly request a destination; otherwise provide the requested explicit .png file path.",
+						"Use null when the user did not explicitly request a destination; otherwise provide an explicit .png, .jpg, .jpeg, or .webp file path matching the provider output format.",
 				},
 			),
 		),
 		size: Type.Optional(
 			StringEnum(IMAGE_GENERATION_SIZES, {
-				description: "Requested PNG dimensions, or auto.",
+				description: "Requested raster-image dimensions, or auto.",
 			}),
 		),
 		quality: Type.Optional(
@@ -123,13 +124,14 @@ export function registerImageGenerationExtension(
 ): void {
 	if (registeredApis.has(pi)) return;
 	registeredApis.add(pi);
+	registerPhysicalModelObserver(pi);
 
 	pi.registerTool<typeof GenerateImageParameters, ImageGenerationToolDetails, Record<string, never>>({
 		name: IMAGE_GENERATION_TOOL_NAME,
 		label: "OpenAI Generate Image",
 		description:
-			"Generate PNG images, or edit from one to five user-approved local reference images, through an independent Images API request using a configured image model. This is a paid provider operation; batchSize runs independent requests concurrently.",
-		promptSnippet: "Generate or edit PNG images through an independent Images API request and a configured imageGeneration.allowedModels entry.",
+			"Generate raster images, or edit from one to five user-approved local reference images, through an independent Images API request using a configured image model. PNG, JPEG, and WebP responses are validated and saved in their actual format. This is a paid provider operation; batchSize runs independent requests concurrently.",
+		promptSnippet: "Generate or edit raster images through an independent Images API request and a configured imageGeneration.allowedModels entry.",
 		promptGuidelines: [
 			"Use openai_generate_image when the user explicitly asks to create, draw, render, or edit a raster image and the active model speaks a Responses API.",
 			"Do not call openai_generate_image speculatively: it consumes the user's provider or gateway image quota.",