ima2-gen 3.13.1 → 3.14.0

package/lib/providers/adapters/grokMultimodeOperations.js

@@ -0,0 +1,83 @@
+import { errInfo } from "../../errInfo.js";
+import { imageEditPayload, imagePayload, postGrokImages, grokError, downloadGrokImageUrl, } from "../../grokImageCore.js";
+import { planGrokImage } from "../../grokImagePlanner.js";
+import { getGrokProxyBaseUrl } from "../../grokRuntime.js";
+import { logEvent } from "../../logger.js";
+/**
+ * Representative-error policy for a multimode run.
+ *
+ * Items are attempted in order and a mixed-cause run has no principled winner,
+ * so the last failure is chosen by construction. The result is only meaningful
+ * when every item failed: with any image returned the run is a success and
+ * callers must not report an error (lib/multimodePipeline.ts consults it solely
+ * under `returned === 0`).
+ */
+export function representativeItemError(errors, returnedImages) {
+    if (returnedImages > 0)
+        return undefined;
+    return errors.length > 0 ? errors[errors.length - 1] : undefined;
+}
+export async function generateMultimodeViaGrok(prompt, ctx, options = {}) {
+    const model = options.model || ctx.config.grokProvider?.defaultImageModel || "grok-imagine-image-quality";
+    const maxGeneratedImages = Math.max(1, Math.trunc(Number(ctx.config.limits?.maxGeneratedImages) || 24));
+    const maxImages = Math.min(maxGeneratedImages, Math.max(1, Math.trunc(Number(options.maxImages) || 4)));
+    const references = options.references || [];
+    const images = [];
+    const originalIndexes = [];
+    let totalCost = 0;
+    let totalWebSearchCalls = 0;
+    const itemErrors = [];
+    logEvent("grok", "multimode:start", { requestId: options.requestId, model, maxImages, refs: references.length });
+    for (let i = 0; i < maxImages; i++) {
+        if (options.signal?.aborted)
+            throw grokError("Generation canceled", 499, "GENERATION_CANCELED");
+        const indexedPrompt = maxImages > 1 ? `[Image ${i + 1} of ${maxImages}] ${prompt}` : prompt;
+        const plan = await planGrokImage(indexedPrompt, ctx, {
+            model,
+            size: options.size,
+            signal: options.signal,
+            requestId: options.requestId,
+            references,
+            directApiKey: options.directApiKey,
+            webSearchEnabled: options.webSearchEnabled,
+        });
+        totalWebSearchCalls += plan.webSearchCalls;
+        const endpoint = references.length > 0 ? "/v1/images/edits" : "/v1/images/generations";
+        const payload = references.length > 0
+            ? imageEditPayload(model, plan.prompt, references, options.size)
+            : imagePayload(model, plan.prompt, options.size);
+        try {
+            logEvent("grok", "multimode:item-start", {
+                requestId: options.requestId,
+                index: i,
+                endpoint,
+                refs: references.length,
+                promptChars: plan.prompt.length,
+            });
+            const result = await postGrokImages(ctx, payload, options.signal, endpoint, options.directApiKey);
+            const imgUrl = result.data?.[0]?.url;
+            if (imgUrl) {
+                const dl = await downloadGrokImageUrl(imgUrl, options.signal, undefined, {
+                    trustedProxyOrigin: options.directApiKey
+                        ? undefined : new URL(getGrokProxyBaseUrl(ctx)).origin,
+                });
+                const img = { b64: dl.b64, mime: dl.mime, revisedPrompt: plan.prompt, providerUrl: imgUrl };
+                images.push(img);
+                originalIndexes.push(i);
+                if (result.usage?.cost_in_usd_ticks)
+                    totalCost += result.usage.cost_in_usd_ticks;
+                await options.onFinalImage?.(img, i);
+            }
+        }
+        catch (e) {
+            if (e.code === "GENERATION_CANCELED")
+                throw e;
+            logEvent("grok", "multimode:item-error", { requestId: options.requestId, index: i, error: errInfo(e) });
+            itemErrors.push(e);
+        }
+    }
+    logEvent("grok", "multimode:done", { requestId: options.requestId, model, returned: images.length, requested: maxImages, refs: references.length });
+    const usage = totalCost > 0 ? { grok_cost_usd_ticks: totalCost } : null;
+    const representative = representativeItemError(itemErrors, images.length);
+    return { images, originalIndexes, usage, webSearchCalls: totalWebSearchCalls, extraIgnored: 0, ...(representative !== undefined ? { error: representative } : {}) };
+}

package/lib/providers/adapters/grokOperations.js

@@ -0,0 +1,63 @@
+import { logEvent } from "../../logger.js";
+import { detectImageMimeFromB64 } from "../../refs.js";
+import { mapSizeToGrokImageParams } from "../../grokSizeMapper.js";
+import { getGrokProxyBaseUrl } from "../../grokRuntime.js";
+import { planGrokImage } from "../../grokImagePlanner.js";
+import { grokError, imagePayload, imageEditPayload, postGrokImages, downloadGrokImageUrl, } from "../../grokImageCore.js";
+export async function generateViaGrok(prompt, ctx, options = {}) {
+    const model = options.model || ctx.config.grokProvider?.defaultImageModel || "grok-imagine-image-quality";
+    const references = options.references || [];
+    const plan = options.plannedPrompt
+        ? { prompt: options.plannedPrompt, model, webSearchCalls: options.webSearchCalls ?? 1 }
+        : await planGrokImage(prompt, ctx, { ...options, referenceCount: references.length, directApiKey: options.directApiKey, webSearchEnabled: options.webSearchEnabled });
+    const hasReferences = references.length > 0;
+    const payload = hasReferences
+        ? imageEditPayload(model, plan.prompt, references, options.size)
+        : imagePayload(model, plan.prompt, options.size);
+    const endpoint = hasReferences ? "/v1/images/edits" : "/v1/images/generations";
+    const logStage = hasReferences ? "generate:edit-start" : "generate:start";
+    logEvent("grok", logStage, {
+        requestId: options.requestId,
+        model,
+        promptChars: plan.prompt.length,
+        size: options.size,
+        refs: references.length,
+    });
+    const result = await postGrokImages(ctx, payload, options.signal, endpoint, options.directApiKey);
+    const imageUrl = result.data?.[0]?.url;
+    if (!imageUrl) {
+        throw grokError("Grok returned no image URL", 502, "GROK_EMPTY_RESPONSE");
+    }
+    const downloaded = await downloadGrokImageUrl(imageUrl, options.signal, undefined, {
+        trustedProxyOrigin: options.directApiKey
+            ? undefined : new URL(getGrokProxyBaseUrl(ctx)).origin,
+    });
+    const usage = result.usage ? { grok_cost_usd_ticks: result.usage.cost_in_usd_ticks ?? 0 } : null;
+    logEvent("grok", "generate:done", {
+        requestId: options.requestId,
+        model,
+        endpoint,
+        refs: references.length,
+        b64Len: downloaded.b64.length,
+    });
+    return { b64: downloaded.b64, providerUrl: imageUrl, usage, webSearchCalls: plan.webSearchCalls, mime: downloaded.mime, revisedPrompt: plan.prompt };
+}
+export async function editViaGrok(prompt, imageB64, ctx, options = {}) {
+    const model = options.model || ctx.config.grokProvider?.defaultImageModel || "grok-imagine-image-quality";
+    const detectedInputMime = detectImageMimeFromB64(imageB64) || "image/png";
+    const imageUrl = imageB64.startsWith("data:") ? imageB64 : `data:${detectedInputMime};base64,${imageB64}`;
+    const payload = { model, prompt, n: 1, response_format: "url", image: { type: "image_url", url: imageUrl }, ...mapSizeToGrokImageParams(options.size) };
+    logEvent("grok", "edit:start", { requestId: options.requestId, model, promptChars: prompt.length });
+    const result = await postGrokImages(ctx, payload, options.signal, "/v1/images/edits", options.directApiKey);
+    const editResultUrl = result.data?.[0]?.url;
+    if (!editResultUrl) {
+        throw grokError("Grok edit returned no image URL", 502, "GROK_EMPTY_RESPONSE");
+    }
+    const downloaded = await downloadGrokImageUrl(editResultUrl, options.signal, undefined, {
+        trustedProxyOrigin: options.directApiKey
+            ? undefined : new URL(getGrokProxyBaseUrl(ctx)).origin,
+    });
+    const usage = result.usage ? { grok_cost_usd_ticks: result.usage.cost_in_usd_ticks ?? 0 } : null;
+    logEvent("grok", "edit:done", { requestId: options.requestId, model, b64Len: downloaded.b64.length });
+    return { b64: downloaded.b64, providerUrl: editResultUrl, usage, webSearchCalls: 0, mime: downloaded.mime, revisedPrompt: result.data[0]?.revised_prompt || prompt };
+}

package/lib/providers/adapters/openaiExecution.js

@@ -0,0 +1,118 @@
+import { isNonRetryableGenerationError, normalizeGenerationFailure } from "../../generationErrors.js";
+import { throwIfJobCanceled } from "../../generationCancel.js";
+import { logEvent } from "../../logger.js";
+import { generateViaResponses, editViaResponses, generateMultimodeViaResponses } from "./openaiOperations.js";
+export function isOpenaiRequest(request) {
+    return request.provider === "oauth" || request.provider === "api";
+}
+function prepareOpenaiClassic(ctx, request, _progress) {
+    const { provider: activeProvider, prompt: generationPrompt, requestId, background: backgroundParams } = request;
+    const { model: imageModel, quality, size: effectiveSize, moderation, mode: normalizedPromptMode, reasoningEffort, webSearchEnabled } = request.options;
+    // Scalars are captured at prepare; references, signal and ctx stay live per attempt.
+    const generateOne = async () => {
+        const MAX_RETRIES = 1;
+        let lastErr;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const r = await generateViaResponses(activeProvider, generationPrompt, quality, effectiveSize, moderation, request.references, requestId, normalizedPromptMode, ctx, {
+                    model: imageModel,
+                    reasoningEffort,
+                    webSearchEnabled,
+                    signal: request.signal,
+                    allowPromptOnlyOAuthFallback: activeProvider !== "api",
+                    ...(backgroundParams ? { background: backgroundParams.background } : {}),
+                    ...(backgroundParams?.outputFormat ? { outputFormat: backgroundParams.outputFormat } : {}),
+                });
+                throwIfJobCanceled(requestId);
+                if (r.b64)
+                    return r;
+                lastErr = new Error("Empty response (safety refusal)");
+            }
+            catch (e) {
+                lastErr = e;
+                if (isNonRetryableGenerationError(e))
+                    break;
+            }
+            if (attempt < MAX_RETRIES) {
+                const errCode = (lastErr && typeof lastErr === "object" && "code" in lastErr)
+                    ? lastErr.code
+                    : undefined;
+                logEvent("generate", "retry", { requestId, attempt: attempt + 1, errorCode: errCode });
+            }
+        }
+        throw normalizeGenerationFailure(lastErr, {
+            safetyMessage: "Content generation refused after retries",
+        });
+    };
+    return { execute: async () => {
+            try {
+                return { kind: "single", value: await generateOne() };
+            }
+            catch (error) {
+                throw error;
+            } // Caller owns lifecycle and the existing error envelope.
+        } };
+}
+async function executeOpenaiNode(ctx, request, progress) {
+    const { provider, sourceImage: parentB64, prompt: generationPrompt, references, requestId, signal, searchMode, options } = request;
+    const { model, size, quality, moderation, mode, reasoningEffort, webSearchEnabled } = options;
+    const refsForRequest = request.contextMode === "parent-only" ? [] : references;
+    return parentB64
+        ? await editViaResponses(provider, generationPrompt, parentB64, quality, size, moderation, mode, ctx, requestId, {
+            model, references: refsForRequest, searchMode, reasoningEffort, webSearchEnabled, signal,
+        })
+        : await generateViaResponses(provider, generationPrompt, quality, size, moderation, refsForRequest, requestId, mode, ctx, {
+            model, reasoningEffort, webSearchEnabled, signal,
+            partialImages: request.partialImages,
+            onPartialImage: progress?.onPartialImage ?? null,
+        });
+}
+async function executeOpenaiEdit(ctx, request) {
+    const { provider, rawPrompt, sourceImage, signal, requestId, options } = request;
+    const result = await editViaResponses(provider, rawPrompt, sourceImage, options.quality, options.size, options.moderation, options.mode, ctx, requestId, { model: options.model, reasoningEffort: options.reasoningEffort,
+        webSearchEnabled: options.webSearchEnabled,
+        ...(request.mask !== null ? { mask: request.mask } : {}), signal });
+    // Preserve native retry metadata; only Responses had these caller defaults.
+    return { ...result, usage: result.usage ?? null, webSearchCalls: result.webSearchCalls ?? 0 };
+}
+async function executeOpenaiMultimode(ctx, request, progress) {
+    const { provider, prompt, references, signal, requestId, options, maxImages } = request;
+    return generateMultimodeViaResponses(provider, prompt, options.quality, options.size, options.moderation, references, requestId, options.mode, ctx, { model: options.model, maxImages, reasoningEffort: options.reasoningEffort,
+        webSearchEnabled: options.webSearchEnabled,
+        ...(progress.onPartialImage !== undefined ? { onPartialImage: progress.onPartialImage } : {}),
+        ...(progress.onFinalImage !== undefined ? { onFinalImage: progress.onFinalImage } : {}), signal });
+}
+export async function prepareOpenaiExecution(ctx, request, progress = {}) {
+    try {
+        switch (request.surface) {
+            case "classic": return prepareOpenaiClassic(ctx, request, progress);
+            case "node": return { execute: async () => {
+                    try {
+                        return { kind: "single", value: await executeOpenaiNode(ctx, request, progress) };
+                    }
+                    catch (error) {
+                        throw error;
+                    } // Caller owns retries and normalization.
+                } };
+            case "edit": return { execute: async () => {
+                    try {
+                        return { kind: "single", value: await executeOpenaiEdit(ctx, request) };
+                    }
+                    catch (error) {
+                        throw error;
+                    } // Route owns failure normalization and job cleanup.
+                } };
+            case "multimode": return { execute: async () => {
+                    try {
+                        return { kind: "sequence", value: await executeOpenaiMultimode(ctx, request, progress) };
+                    }
+                    catch (error) {
+                        throw error;
+                    } // Caller owns partial-timeout recovery.
+                } };
+        }
+    }
+    catch (error) {
+        throw error;
+    }
+}

package/lib/providers/adapters/openaiOperations.js

@@ -0,0 +1,201 @@
+import { compressReferenceB64ForOAuth } from "../../referenceImageCompress.js";
+import { detectImageMimeFromB64 } from "../../refs.js";
+import { requireRuntimeContext } from "../../runtimeContext.js";
+import { imageToolChoice, imageToolChoiceKind, tools, toolTypes, } from "../../responsesTools.js";
+import { emptyResponseError } from "../../responsesErrors.js";
+import { retryPromptOnlyJsonImage } from "../../responsesFallback.js";
+import { AUTO_PROMPT_FIDELITY_SUFFIX, DIRECT_PROMPT_FIDELITY_SUFFIX, EDIT_DEVELOPER_PROMPT, EDIT_NO_SEARCH_DEVELOPER_PROMPT, GENERATE_DEVELOPER_PROMPT, GENERATE_NO_SEARCH_DEVELOPER_PROMPT, MULTIMODE_DEVELOPER_PROMPT, MULTIMODE_NO_SEARCH_DEVELOPER_PROMPT, buildEditTextPrompt, buildMultimodeSequencePrompt, buildUserTextPrompt, } from "../../oauthProxy.js";
+import { postResponses } from "../../responsesTransport.js";
+function normalizeRef(ref) {
+    const b64 = typeof ref === "string" ? ref : ref?.b64;
+    const detectedMime = typeof ref === "object" && ref?.detectedMime
+        ? ref.detectedMime
+        : detectImageMimeFromB64(b64);
+    const declaredMime = typeof ref === "object" ? ref?.declaredMime : null;
+    const mime = ["image/png", "image/jpeg", "image/webp"].includes(detectedMime)
+        ? detectedMime
+        : ["image/png", "image/jpeg", "image/webp"].includes(declaredMime)
+            ? declaredMime
+            : "image/png";
+    return { type: "input_image", image_url: `data:${mime};base64,${b64}` };
+}
+export async function generateViaResponses(provider, prompt, quality, size, moderation = "low", references = [], requestId = null, mode = "auto", ctxRaw = {}, options = {}) {
+    const ctx = requireRuntimeContext(ctxRaw);
+    const model = options.model || ctx.config?.imageModels?.default || "gpt-5.6-luna";
+    const webSearchEnabled = options.webSearchEnabled !== false && options.searchMode !== "off";
+    const requestTools = tools(webSearchEnabled, {
+        quality,
+        size,
+        moderation,
+        ...(options.partialImages ? { partial_images: options.partialImages } : {}),
+        ...(options.background ? { background: options.background } : {}),
+        ...(options.outputFormat ? { output_format: options.outputFormat } : {}),
+    });
+    const toolChoice = imageToolChoice(options.forceImageToolChoice ?? ctx.config?.oauth?.forceImageToolChoice !== false);
+    const toolChoiceKind = imageToolChoiceKind(toolChoice);
+    const referenceInputs = references.map(normalizeRef);
+    const userContent = referenceInputs.length
+        ? [...referenceInputs, { type: "input_text", text: buildUserTextPrompt(prompt, mode, { webSearchEnabled, size }) }]
+        : buildUserTextPrompt(prompt, mode, { webSearchEnabled, size });
+    const result = await postResponses({
+        ctx,
+        provider,
+        scope: provider === "api" ? "api-generate" : "oauth",
+        requestId,
+        maxImages: 1,
+        ...(options.signal !== undefined ? { signal: options.signal } : {}),
+        ...(options.onPartialImage !== undefined ? { onPartialImage: options.onPartialImage } : {}),
+        ...(options.onFinalImage !== undefined ? { onFinalImage: options.onFinalImage } : {}),
+        payload: {
+            model,
+            input: [
+                { role: "developer", content: webSearchEnabled ? GENERATE_DEVELOPER_PROMPT : GENERATE_NO_SEARCH_DEVELOPER_PROMPT },
+                { role: "user", content: userContent },
+            ],
+            tools: requestTools,
+            tool_choice: toolChoice,
+            reasoning: { effort: options.reasoningEffort || "low" },
+            stream: true,
+        },
+    });
+    const image = result.images[0];
+    if (!image?.b64) {
+        if (options.allowPromptOnlyOAuthFallback === true) {
+            const fallback = await retryPromptOnlyJsonImage({
+                postResponses,
+                ctx,
+                provider,
+                prompt,
+                mode,
+                model,
+                quality,
+                size,
+                moderation,
+                requestId,
+                ...(options.signal !== undefined ? { signal: options.signal } : {}),
+                initial: result,
+                referenceInputs,
+                webSearchDroppedOnRetry: webSearchEnabled,
+                ...(options.reasoningEffort !== undefined ? { reasoningEffort: options.reasoningEffort } : {}),
+                ...(options.background !== undefined ? { background: options.background } : {}),
+                ...(options.outputFormat !== undefined ? { outputFormat: options.outputFormat } : {}),
+            });
+            if (fallback)
+                return fallback;
+        }
+        throw emptyResponseError("No image data received from Responses API", result, {
+            provider,
+            model,
+            quality,
+            size,
+            moderation,
+            webSearchEnabled,
+            refsCount: referenceInputs.length,
+            inputImageCount: referenceInputs.length,
+            promptChars: typeof prompt === "string" ? prompt.length : 0,
+            toolTypes: toolTypes(requestTools),
+            toolChoiceKind,
+        });
+    }
+    return { b64: image.b64, usage: result.usage, webSearchCalls: result.webSearchCalls, revisedPrompt: image.revisedPrompt, text: result.text };
+}
+export async function generateMultimodeViaResponses(provider, prompt, quality, size, moderation = "low", references = [], requestId = null, mode = "auto", ctxRaw = {}, options = {}) {
+    const ctx = requireRuntimeContext(ctxRaw);
+    const maxGeneratedImages = Math.max(1, Math.trunc(Number(ctx.config.limits.maxGeneratedImages) || 24));
+    const maxImages = Math.min(maxGeneratedImages, Math.max(1, Math.trunc(Number(options.maxImages) || 1)));
+    const model = options.model || ctx.config?.imageModels?.default || "gpt-5.6-luna";
+    const webSearchEnabled = options.webSearchEnabled !== false && options.searchMode !== "off";
+    const requestTools = tools(webSearchEnabled, { quality, size, moderation, ...(options.partialImages ? { partial_images: options.partialImages } : {}) });
+    const userText = buildMultimodeSequencePrompt(mode === "direct"
+        ? `${prompt}${DIRECT_PROMPT_FIDELITY_SUFFIX}`
+        : `${prompt}${webSearchEnabled ? "" : ""}${AUTO_PROMPT_FIDELITY_SUFFIX}`, maxImages, { webSearchEnabled, size });
+    const referenceInputs = references.map(normalizeRef);
+    const userContent = referenceInputs.length
+        ? [...referenceInputs, { type: "input_text", text: userText }]
+        : userText;
+    return await postResponses({
+        ctx,
+        provider,
+        scope: provider === "api" ? "api-multimode" : "oauth-multimode",
+        requestId,
+        maxImages,
+        ...(options.signal !== undefined ? { signal: options.signal } : {}),
+        ...(options.onPartialImage !== undefined ? { onPartialImage: options.onPartialImage } : {}),
+        ...(options.onFinalImage !== undefined ? { onFinalImage: options.onFinalImage } : {}),
+        payload: {
+            model,
+            input: [
+                { role: "developer", content: webSearchEnabled ? MULTIMODE_DEVELOPER_PROMPT : MULTIMODE_NO_SEARCH_DEVELOPER_PROMPT },
+                { role: "user", content: userContent },
+            ],
+            tools: requestTools,
+            tool_choice: "required",
+            reasoning: { effort: options.reasoningEffort || "low" },
+            stream: true,
+        },
+    });
+}
+export async function editViaResponses(provider, prompt, imageB64, quality, size, moderation = "low", mode = "auto", ctxRaw = {}, requestId = null, options = {}) {
+    const ctx = requireRuntimeContext(ctxRaw);
+    const model = options.model || ctx.config?.imageModels?.default || "gpt-5.6-luna";
+    const webSearchEnabled = options.webSearchEnabled !== false && options.searchMode !== "off";
+    const requestTools = tools(webSearchEnabled, { quality, size, moderation });
+    const toolChoice = imageToolChoice(options.forceImageToolChoice ?? ctx.config?.oauth?.forceImageToolChoice !== false);
+    const toolChoiceKind = imageToolChoiceKind(toolChoice);
+    const imageForRequest = await compressReferenceB64ForOAuth(imageB64, {
+        maxB64Bytes: ctx.config?.limits?.maxRefB64Bytes,
+        force: true,
+    });
+    const referenceImages = await Promise.all((Array.isArray(options.references) ? options.references : []).map((ref) => compressReferenceB64ForOAuth(typeof ref === "string" ? ref : ref?.b64, {
+        maxB64Bytes: ctx.config?.limits?.maxRefB64Bytes,
+        force: true,
+    })));
+    const maskContent = typeof options.mask === "string" && options.mask.length > 0
+        ? [
+            { type: "input_image", image_url: `data:image/png;base64,${options.mask}` },
+            { type: "input_text", text: "The previous image is an edit mask guide. Use it as prompt guidance for where the edit should apply; it is not a visible final image element." },
+        ]
+        : [];
+    const userContent = [
+        { type: "input_image", image_url: `data:image/jpeg;base64,${imageForRequest.b64}` },
+        ...referenceImages.map(({ b64 }) => ({ type: "input_image", image_url: `data:image/jpeg;base64,${b64}` })),
+        ...maskContent,
+        { type: "input_text", text: buildEditTextPrompt(prompt, mode, { webSearchEnabled, size }) },
+    ];
+    const result = await postResponses({
+        ctx,
+        provider,
+        scope: provider === "api" ? "api-edit" : "oauth-edit",
+        requestId,
+        maxImages: 1,
+        signal: options.signal,
+        payload: {
+            model,
+            input: [
+                { role: "developer", content: webSearchEnabled ? EDIT_DEVELOPER_PROMPT : EDIT_NO_SEARCH_DEVELOPER_PROMPT },
+                { role: "user", content: userContent },
+            ],
+            tools: requestTools,
+            tool_choice: toolChoice,
+            reasoning: { effort: options.reasoningEffort || "low" },
+            stream: true,
+        },
+    });
+    const image = result.images[0];
+    if (!image?.b64) {
+        throw emptyResponseError("No image data received from Responses edit", result, {
+            provider,
+            model,
+            quality,
+            size,
+            moderation,
+            webSearchEnabled,
+            refsCount: referenceImages.length,
+            inputImageCount: 1 + referenceImages.length + (maskContent.length ? 1 : 0),
+            promptChars: typeof prompt === "string" ? prompt.length : 0,
+            toolTypes: toolTypes(requestTools),
+            toolChoiceKind,
+        });
+    }
+    return { b64: image.b64, usage: result.usage, revisedPrompt: image.revisedPrompt, webSearchCalls: result.webSearchCalls };
+}

package/lib/providers/adapters/openaiTypes.js

@@ -0,0 +1 @@
+export {};

package/lib/providers/derive.js

@@ -2,7 +2,11 @@
 // in deriveCore.ts; this module binds it to REGISTRY and keeps the narrow
 // CoreProviderId typing consumers rely on.
 import { REGISTRY } from "./registry.js";
+import { deriveProviderSurfaceSupportFrom } from "./surfaceSupport.js";
 import { deriveCliImageModelSetFrom, deriveIdsFrom, deriveImageModelSetFrom, deriveModelsFrom, deriveReferenceLimitFrom, deriveReferenceLimitMapFrom, deriveSupportedImageModelsFrom, deriveUnsupportedImageModelsFrom, } from "./deriveCore.js";
+export function getProviderSurfaceSupport(providerId, surface) {
+    return deriveProviderSurfaceSupportFrom(REGISTRY, providerId, surface);
+}
 export function deriveProviderIds(registry = REGISTRY) {
     return deriveIdsFrom(registry);
 }

package/lib/providers/deriveCore.js

@@ -7,10 +7,10 @@ export function deriveModelsFrom(registry, providerId, kind) {
 }
 export function deriveSupportedImageModelsFrom(registry, providerId) {
     const provider = registry.find((entry) => entry.id === providerId);
-    return new Set(provider?.models.filter((model) => model.kind === "image" && supportsAnything(model.supports)).map((model) => model.id) ?? []);
+    return new Set(provider?.models.filter((model) => model.kind === "image" && model.supports.generate).map((model) => model.id) ?? []);
 }
 export function deriveUnsupportedImageModelsFrom(registry) {
-    return new Set(registry.flatMap((provider) => provider.models.filter((model) => model.kind === "image" && !supportsAnything(model.supports)).map((model) => model.id)));
+    return new Set(registry.flatMap((provider) => provider.models.filter((model) => model.kind === "image" && !model.supports.generate).map((model) => model.id)));
 }
 export function deriveImageModelSetFrom(registry) {
     return new Set(registry.flatMap((provider) => provider.models.filter((model) => model.kind === "image").map((model) => model.id)));
@@ -27,8 +27,3 @@ export function deriveReferenceLimitMapFrom(registry, mode) {
 export function deriveReferenceLimitFrom(registry, providerId, mode) {
     return registry.find((entry) => entry.id === providerId)?.referenceLimits[mode];
 }
-// A model with no capability at all is an explicitly unsupported entry
-// (gpt-5.3-codex-spark), which lib/imageModels.ts rejects by name.
-function supportsAnything(supports) {
-    return Boolean(supports.edit || supports.mask || supports.streaming);
-}

package/lib/providers/execution/admission.js

@@ -0,0 +1,25 @@
+import { getProviderSurfaceSupport } from "../derive.js";
+function directKeyFailure(ctx, provider) {
+    if (provider !== "grok-api" || (typeof ctx.xaiApiKey === "string" && ctx.xaiApiKey.trim()))
+        return null;
+    return { status: 401, code: "GROK_API_KEY_MISSING",
+        message: "Grok API key is required for grok-api image generation" };
+}
+export function checkImageExecutionAdmission(ctx, input) {
+    const missingKey = directKeyFailure(ctx, input.provider);
+    if (missingKey)
+        return missingKey;
+    const surface = input.surface === "classic" ? "generate" : input.surface;
+    if (input.provider === "nai" && surface === "multimode" && input.referenceCount > 0
+        && getProviderSurfaceSupport(input.provider, surface)?.references === false) {
+        return { status: 400, code: "NAI_REF_UNSUPPORTED",
+            message: "NovelAI image generation does not accept reference images yet" };
+    }
+    return null;
+}
+/** Recheck mutable direct credentials without changing the provider or captured key. */
+export function assertDirectGrokKey(ctx, provider) {
+    const failure = directKeyFailure(ctx, provider);
+    if (failure)
+        throw Object.assign(new Error(failure.message), { status: failure.status, code: failure.code });
+}

package/lib/providers/execution/index.js

@@ -0,0 +1,34 @@
+import { assertDirectGrokKey } from "./admission.js";
+import { isLegacyExecutionRequest, prepareLegacyImageExecution } from "./legacy.js";
+import { isOpenaiRequest, prepareOpenaiExecution } from "../adapters/openaiExecution.js";
+import { isGrokRequest, prepareGrokExecution } from "../adapters/grokExecution.js";
+import { isGoogleRequest, prepareGoogleExecution } from "../adapters/googleExecution.js";
+function prepareSelected(ctx, request, progress) {
+    if (isOpenaiRequest(request))
+        return prepareOpenaiExecution(ctx, request, progress);
+    if (isGrokRequest(request))
+        return prepareGrokExecution(ctx, request, progress);
+    if (isGoogleRequest(request))
+        return prepareGoogleExecution(ctx, request, progress);
+    if (isLegacyExecutionRequest(request))
+        return prepareLegacyImageExecution(ctx, request, progress);
+    throw new Error("Unreachable image execution provider");
+}
+export async function prepareImageExecution(ctx, request, progress) {
+    try {
+        assertDirectGrokKey(ctx, request.provider);
+        const prepared = await prepareSelected(ctx, request, progress);
+        return { execute: async () => {
+                try {
+                    assertDirectGrokKey(ctx, request.provider);
+                    return await prepared.execute();
+                }
+                catch (error) {
+                    throw error;
+                } // Preserve transport identity; callers own normalization.
+            } };
+    }
+    catch (error) {
+        throw error;
+    }
+}

package/lib/providers/execution/legacy.js

@@ -0,0 +1,17 @@
+import { prepareLegacyClassic } from "./legacyClassic.js";
+import { prepareLegacyNode } from "./legacyNode.js";
+import { prepareLegacyEdit } from "./legacyEdit.js";
+import { prepareLegacyMultimode } from "./legacyMultimode.js";
+export function isLegacyExecutionRequest(request) {
+    return request.provider !== "oauth" && request.provider !== "api"
+        && request.provider !== "grok" && request.provider !== "grok-api"
+        && request.provider !== "agy" && request.provider !== "gemini-api";
+}
+export function prepareLegacyImageExecution(ctx, request, progress) {
+    switch (request.surface) {
+        case "classic": return prepareLegacyClassic(ctx, request, progress);
+        case "node": return prepareLegacyNode(ctx, request, progress);
+        case "edit": return prepareLegacyEdit(ctx, request, progress);
+        case "multimode": return prepareLegacyMultimode(ctx, request, progress);
+    }
+}

package/lib/providers/execution/legacyClassic.js

@@ -0,0 +1,66 @@
+import { generateViaAtlasCloud } from "../../atlasCloudImageAdapter.js";
+import { generateViaMinimax } from "../../minimaxImageAdapter.js";
+import { generateViaNai } from "../../naiImageAdapter.js";
+import { generateViaComfy } from "../../comfyImageAdapter.js";
+import { requireRuntimeContext } from "../../runtimeContext.js";
+function captureClassicRequest(request) {
+    const { provider: activeProvider, prompt: generationPrompt, requestId, background: backgroundParams } = request;
+    const { model: imageModel, quality, size: effectiveSize } = request.options;
+    return { activeProvider, generationPrompt, requestId, backgroundParams, imageModel, quality, effectiveSize };
+}
+async function executeLegacyClassic(ctx, request, progress, captured) {
+    try {
+        const { activeProvider, generationPrompt, requestId, backgroundParams, imageModel, quality, effectiveSize } = captured;
+        if (activeProvider === "atlascloud") {
+            return await generateViaAtlasCloud(generationPrompt, requireRuntimeContext(ctx), {
+                model: imageModel, size: effectiveSize, quality, signal: request.signal,
+                requestId, references: request.references,
+                ...(backgroundParams ? { background: backgroundParams.background } : {}),
+                // The caller's resolveImageBackgroundParams validates this alpha-only format.
+                ...(backgroundParams?.outputFormat ? { outputFormat: backgroundParams.outputFormat } : {}),
+            });
+        }
+        if (activeProvider === "minimax") {
+            return await generateViaMinimax(generationPrompt, requireRuntimeContext(ctx), {
+                model: imageModel, size: effectiveSize, signal: request.signal,
+                requestId, references: request.references,
+            });
+        }
+        if (activeProvider === "nai") {
+            // Text-to-image only: the caller already refused references.
+            return await generateViaNai(generationPrompt, requireRuntimeContext(ctx), {
+                model: imageModel, size: effectiveSize, signal: request.signal, requestId,
+                // Reuse the same normalized options as node and multimode.
+                ...request.nai,
+            });
+        }
+        if (activeProvider === "comfy") {
+            return await generateViaComfy(generationPrompt, requireRuntimeContext(ctx), {
+                model: imageModel, size: effectiveSize, signal: request.signal,
+                requestId, references: request.references,
+                ...request.comfy, onQueue: progress.onQueue,
+            });
+        }
+        throw new Error(`Unsupported classic execution provider: ${activeProvider}`);
+    }
+    catch (error) {
+        throw error;
+    }
+}
+export async function prepareLegacyClassic(ctx, request, progress = {}) {
+    try {
+        // Preserve scalar/background capture; ctx, refs, signal and lane options stay live.
+        const captured = captureClassicRequest(request);
+        return { execute: async () => {
+                try {
+                    return { kind: "single", value: await executeLegacyClassic(ctx, request, progress, captured) };
+                }
+                catch (error) {
+                    throw error;
+                } // Caller owns lifecycle and the existing error envelope.
+            } };
+    }
+    catch (error) {
+        throw error;
+    }
+}