pi-openai-toolkit 0.18.0 → 0.19.0

package/README.md

@@ -14,7 +14,7 @@ Add Codex context windows, Responses compaction, hosted tools, and tool-call rev
 | Codex Remote Context | Start new windows with the adapted Codex protocol and retrieve earlier work through `history`. |
 | Remote Compaction v2 | Continue Responses sessions with encrypted server checkpoints. |
 | Web Search | Choose local `pi-web-access`, Responses `web_search`, or experimental CPA `web_run` per model. |
-| Image generation | Generate or edit images with the hosted Responses image tool. |
+| Image generation | Generate or edit raster images through a separate Images API request. |
 | Tool-call review | Have a reviewer model approve selected calls through Toolkit's approval gate. |
 
 The package uses Pi's existing models, authentication, and sessions. It does not add a provider or model.
@@ -176,14 +176,14 @@ Requires an eligible Responses-capable session and may incur provider charges. T
   "defaults": {
     "imageGeneration": {
       "enabled": true,
-      "defaultModel": "gpt-image-2.5",
-      "allowedModels": ["gpt-image-2.5"]
+      "defaultModel": "grok-imagine-image-2.0",
+      "allowedModels": ["grok-imagine-image-2.0"]
     }
   }
 }
 ```
 
-Ask Pi to generate an image or edit explicitly supplied local references using `openai_generate_image`. The selected image model is sent in the independent request; the active conversation model remains the routing/auth model. Set the tool's optional `model` to another exact `allowedModels` entry, or use `batchSize` (1-10) for concurrent independent variants. Batch calls save canonical artifacts and cannot use a single-file `outputPath`; image settings are global. See [image configuration](docs/configuration.md#images).
+Ask Pi to generate an image or edit explicitly supplied local references using `openai_generate_image`. The selected image model is sent in the independent request; the active conversation model remains the routing/auth model. PNG, JPEG, and WebP responses are validated and saved in their actual format. Set the tool's optional `model` to another exact `allowedModels` entry, or use `batchSize` (1-10) for concurrent independent variants. Batch calls save canonical artifacts and cannot use a single-file `outputPath`; when `quality` is `auto`, the field is omitted so compatible gateways can apply their own default. Image settings are global. See [image configuration](docs/configuration.md#images).
 
 ### Review tool calls automatically
 

package/README.zh.md

@@ -14,7 +14,7 @@
 | Codex 远程上下文 | 通过适配的 Codex 协议切换窗口，用 `history` 找回较早的工作内容。 |
 | 远程压缩 v2 | 使用加密的服务端检查点继续 Responses 会话。 |
 | 联网搜索 | 按模型选择本地 `pi-web-access`、Responses `web_search` 或实验性的 CPA `web_run`。 |
-| 图像生成 | 使用 Responses 托管生图工具生成或编辑图片。 |
+| 图像生成 | 通过独立的 Images API 请求生成或编辑栅格图片。 |
 | 工具调用审查 | 通过 Toolkit 审批门禁，让审查模型判断指定调用是否可以执行。 |
 
 本包沿用 Pi 已有的模型、认证和会话，不新增提供商或模型。
@@ -176,14 +176,14 @@ Toolkit 不会在路由之间自动回退。后端要求见[搜索配置](docs/c
   "defaults": {
     "imageGeneration": {
       "enabled": true,
-      "defaultModel": "gpt-image-2.5",
-      "allowedModels": ["gpt-image-2.5"]
+      "defaultModel": "grok-imagine-image-2.0",
+      "allowedModels": ["grok-imagine-image-2.0"]
     }
   }
 }
 ```
 
-让 Pi 通过 `openai_generate_image` 生成图片，或编辑明确提供的本地参考图。选中的生图模型会写入独立请求；当前对话模型仍只负责路由和认证。工具的可选 `model` 必须精确匹配 `allowedModels`，也可以使用 `batchSize`（1-10）并发生成多个独立变体。批量调用会保存 canonical artifacts，不能同时指定单文件 `outputPath`；生图设置全局生效。详见[生图配置](docs/configuration.md#images)。
+让 Pi 通过 `openai_generate_image` 生成图片，或编辑明确提供的本地参考图。选中的生图模型会写入独立请求；当前对话模型仍只负责路由和认证。PNG、JPEG 和 WebP 响应会按实际格式校验并保存。工具的可选 `model` 必须精确匹配 `allowedModels`，也可以使用 `batchSize`（1-10）并发生成多个独立变体。批量调用会保存 canonical artifacts，不能同时指定单文件 `outputPath`；`quality` 为 `auto` 时会省略该字段，让兼容网关使用自己的默认值。生图设置全局生效。详见[生图配置](docs/configuration.md#images)。
 
 ### 启用工具调用自动审查
 

package/config.schema.json

@@ -57,7 +57,8 @@
       "items": {
         "enum": [
           "openai-responses",
-          "openai-codex-responses"
+          "openai-codex-responses",
+          "azure-openai-responses"
         ]
       }
     },

package/docs/configuration.md

@@ -18,8 +18,8 @@ Create the file and parent directory if absent. This example states the shipped
     "webSearch": { "route": "unmanaged" },
     "imageGeneration": {
       "enabled": false,
-      "defaultModel": "gpt-image-2.5",
-      "allowedModels": ["gpt-image-2.5"]
+      "defaultModel": "grok-imagine-image-2.0",
+      "allowedModels": ["grok-imagine-image-2.0"]
     },
     "autoMode": { "available": false }
   },
@@ -60,7 +60,7 @@ Place `context` under `defaults` or an exact `models` entry.
 | `remoteCompaction.model` | `null` | Exact producer reference; `null` uses the active model. In `remote-compaction`, it selects the synthetic checkpoint producer on the same effective base URL. In active `remote-windows`, manual `/compact` temporarily selects it for notes checkpoint duty on the same backend/account. |
 | `remoteCompaction.inputSource` | `"legacy"` | `"legacy"` preserves session/raw-branch input; `"pi-context-hook"` opts into Pi's ordered context projection. Checkpoint provenance must match. |
 | `remoteCompaction.allowContinuityBreak` | `false` | Allow restarting from Pi context after a foreign compaction entry. It does not make malformed opaque checkpoints replayable. |
-| `remoteCompaction.apis` | `["openai-responses", "openai-codex-responses"]` | May narrow this set; `[]` permits no remote-compaction API. Unsupported entries are errors. |
+| `remoteCompaction.apis` | `["openai-responses", "openai-codex-responses", "azure-openai-responses"]` | May narrow this set; `[]` permits no remote-compaction API. Azure uses Pi's resolved `AZURE_OPENAI_*` environment values for the `/openai/v1` Responses path, deployment mapping, and `api-version`; unsupported entries are errors. |
 | `nativeFallback.enabled` | `true` | Enable the existing native-method fallback tier. |
 | `nativeFallback.model` | `null` | Optional summary-model reference on the remote-ineligible path. After a remote attempt fails, the existing producer-first fallback order is retained. |
 | `nativeFallback.thinkingLevel` | `"off"` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`; actual model support still applies. |
@@ -81,7 +81,7 @@ The SDK native compact call reports its intentional cancellation; the visible ha
 
 Only `models["provider/model-id"].compatibility.transport` is configurable: `"standard"` is the internal baseline and `"codex-gateway"` is an exact opt-in. There is no global `defaults.compatibility` and no built-in gateway model list.
 
-This selects an existing Toolkit protocol profile, independently of context mode. It does not change Pi's provider, API, endpoint, or model. The same decoded document supplies compatibility for search, image generation, and a separately named compaction producer. A successful config resolution is not a backend capability test.
+This selects an existing Toolkit protocol profile, independently of context mode. It does not change Pi's provider, API, endpoint, or model. The same decoded document supplies compatibility for search, image generation, and a separately named compaction producer. A successful config resolution is not a backend capability test. When Pi selects a `pi-virtual` model, Toolkit uses Pi's runtime resolver (when available) to obtain the physical provider/model for capability, authentication, and endpoint checks; if that route cannot be verified, the feature fails closed instead of treating the virtual entry as an OpenAI model.
 
 ---
 
@@ -96,15 +96,15 @@ This selects an existing Toolkit protocol profile, independently of context mode
 | `hosted` | Use native Responses search with source annotations; suppress conflicting local and standalone tools. |
 | `standalone-alpha` | Experimental, explicit opt-in. Expose sequential `web_run` and call the provider-relative `/alpha/search` endpoint once per execution. |
 
-There is no v2 search master switch. `local` and `unmanaged` differ in payload cleanup and ownership. Missing auth, an unavailable route, a tool conflict, or invalid selected policy does not trigger another route. Standalone supports `search_query`, `image_query`, `open`, `click`, `find`, `screenshot`, `finance`, `weather`, `sports`, and `time`, with `response_length`. It sends a bounded command envelope rather than the full transcript; follow-up references depend on the provider's session/reference handling. The gateway must expose the endpoint and its standalone-search capability.
+There is no v2 search master switch. `local` and `unmanaged` differ in payload cleanup and ownership. Missing auth, an unavailable route, a tool conflict, or invalid selected policy does not trigger another route. Hosted Responses search also accepts Pi's Azure Responses API; standalone-alpha remains restricted to the verified OpenAI/Codex `/alpha/search` routes. Standalone supports `search_query`, `image_query`, `open`, `click`, `find`, `screenshot`, `finance`, `weather`, `sports`, and `time`, with `response_length`. It sends a bounded command envelope rather than the full transcript; follow-up references depend on the provider's session/reference handling. The gateway must expose the endpoint and its standalone-search capability.
 
 ---
 
 ### Images
 
-Image settings are global-only under `defaults.imageGeneration`. `enabled` defaults to `false`. `defaultModel` defaults to `"gpt-image-2.5"`; `allowedModels` defaults to `["gpt-image-2.5"]`.
+Image settings are global-only under `defaults.imageGeneration`. `enabled` defaults to `false`. `defaultModel` defaults to `"grok-imagine-image-2.0"`; `allowedModels` defaults to `["grok-imagine-image-2.0"]`.
 
-These are bare output-model IDs, not active-session model keys. Each normalized ID must contain 1-256 characters. The allowed list must remain nonempty after normalization and contain the explicit default. A caller's one-call `model` must be a member; policy and membership are checked before auth, local-reference preparation/upload, and paid dispatch. The active session remains the routing/auth model, while the selected image model is sent in a separate Images API request. Generation uses `/images/generations`; edits use `/images/edits` (Codex uses the corresponding `/codex/images/...` paths). The wrapper never injects a Responses `image_generation` tool. `batchSize` is a tool argument from 1-10; each item is an independent `n: 1` request, partial success preserves saved artifacts, and batch calls cannot use a single-file `outputPath`. Config does not grant permission to upload arbitrary local files or imply that a provider supports a particular image model.
+These are bare output-model IDs, not active-session model keys. Each normalized ID must contain 1-256 characters. The allowed list must remain nonempty after normalization and contain the explicit default. A caller's one-call `model` must be a member; policy and membership are checked before auth, local-reference preparation/upload, and paid dispatch. The active session remains the routing/auth model, while the selected image model is sent in a separate Images API request. Generation uses `/images/generations`; edits use `/images/edits` (Codex uses the corresponding `/codex/images/...` paths). The wrapper never injects a Responses `image_generation` tool. Responses are accepted only when they contain one validated PNG, JPEG, or WebP `data[].b64_json` image; the canonical artifact uses the detected format extension. A literal `quality: "auto"` is omitted from the wire request for compatibility gateways that reject it. `batchSize` is a tool argument from 1-10; each item is an independent `n: 1` request, partial success preserves saved artifacts, and batch calls cannot use a single-file `outputPath`. Config does not grant permission to upload arbitrary local files or imply that a provider supports a particular image model.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openai-toolkit",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "private": false,
   "type": "module",
   "engines": {
@@ -126,10 +126,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/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.",