ima2-gen 3.13.1 → 3.14.0

package/lib/providers/adapters/agyOperations.js

@@ -0,0 +1,179 @@
+import { rm, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomBytes } from "node:crypto";
+import { spawnAgy, agyError } from "../../agyProcess.js";
+import { parseAgyOutput, findRecentAgyArtifact } from "../../agyArtifact.js";
+import { readAgyArtifact, cleanupAgyArtifact } from "../../agyArtifactRead.js";
+import { logEvent } from "../../logger.js";
+import { SAFETY_INTENT_POLICY } from "../../promptSafetyPolicy.js";
+import { detectImageMimeFromB64 } from "../../refs.js";
+import { deriveReferenceLimit } from "../derive.js";
+const AGY_OUTPUT_RESOLUTION = "1024x1024";
+function buildAgyPrompt(userPrompt, referencePaths) {
+    const imagePathsJson = referencePaths.length > 0
+        ? JSON.stringify(referencePaths)
+        : "[]";
+    return [
+        "You are an image generation assistant inside a professional creative tool used by designers and artists. Users create content for legitimate creative, commercial, or educational purposes.",
+        SAFETY_INTENT_POLICY,
+        "",
+        "Generate one image by calling the tool default_api:generate_image once.",
+        "After the tool finishes, print one machine-readable result line so ima2-gen can copy the artifact.",
+        "",
+        "Tool parameters:",
+        `  Prompt: ${JSON.stringify(userPrompt)}`,
+        '  ImageName: "ima2_generated"',
+        `  ImagePaths: ${imagePathsJson}`,
+        '  toolSummary: "ima2 pipeline generation"',
+        '  toolAction: "Generating ima2 image"',
+        "",
+        `Reference count: ${referencePaths.length}. The output resolution is fixed at ${AGY_OUTPUT_RESOLUTION}.`,
+        "",
+        "PROMPT HANDLING:",
+        "- Preserve the user's prompt as-is for compliant requests. Do not translate, restyle, or soften benign adult clothing requests such as swimwear.",
+        "- If the user wrote in Korean, Japanese, or any non-English language, keep visible text and dialogue in that language.",
+        "- Do not sexualize, intensify exposure, or add sexualized/fetish framing to benign swimwear, sportswear, or catalog fashion prompts.",
+        "- Do not copy safety labels, refusal reasons, or negative safety constraints into the final image prompt.",
+        "- If the request includes minors, underage-looking subjects, explicit sexual activity, or fetish framing, do not rewrite it as a benign allowed prompt.",
+        "- Content moderation is still handled downstream by the provider.",
+        "",
+        "OUTPUT:",
+        "If generation succeeds, print: RESULT|<absolute_artifact_path>|<file_extension>",
+        "If generation fails, print: ERROR|<concise error message>",
+    ].join("\n");
+}
+const MIME_TO_EXT = {
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/webp": "webp",
+};
+async function writeRefsToTempFiles(refs) {
+    if (refs.length === 0)
+        return { paths: [], cleanup: async () => { } };
+    const dir = join(tmpdir(), `ima2-agy-refs-${randomBytes(6).toString("hex")}`);
+    const cleanup = async () => {
+        try {
+            await rm(dir, { recursive: true, force: true });
+        }
+        catch { /* best-effort: preserve the primary staging/operation error */ }
+    };
+    try {
+        await mkdir(dir, { recursive: true });
+        const paths = [];
+        for (let i = 0; i < refs.length; i++) {
+            const ref = refs[i];
+            if (!ref)
+                continue;
+            const mime = ref.detectedMime || ref.declaredMime || detectImageMimeFromB64(ref.b64) || "image/png";
+            const ext = MIME_TO_EXT[mime] || "png";
+            const p = join(dir, `ref_${i}.${ext}`);
+            await writeFile(p, Buffer.from(ref.b64, "base64"));
+            paths.push(p);
+        }
+        return { paths, cleanup };
+    }
+    catch (err) {
+        await cleanup();
+        throw err;
+    }
+}
+function throwIfAgyAborted(signal) {
+    if (signal?.aborted) {
+        throw agyError("Generation canceled", 499, "GENERATION_CANCELED");
+    }
+}
+async function resolveAgyArtifactPath(stdout, stderr, generationStartedAtMs, requestId) {
+    if (stderr && stderr.trim().length > 0) {
+        logEvent("agy", "generate:stderr", {
+            requestId,
+            stderrChars: stderr.length,
+            stderrPreview: stderr.slice(0, 200),
+        });
+    }
+    const agyCombinedOutput = [stdout, stderr].filter(Boolean).join("\n");
+    try {
+        return parseAgyOutput(agyCombinedOutput).artifactPath;
+    }
+    catch (err) {
+        if (err?.code !== "AGY_PARSE_FAILED") {
+            throw err;
+        }
+        const fallbackPath = await findRecentAgyArtifact(generationStartedAtMs);
+        if (!fallbackPath) {
+            throw err;
+        }
+        logEvent("agy", "generate:fallback_artifact_found", {
+            requestId,
+            artifactPath: fallbackPath,
+            stdoutChars: stdout.length,
+            stderrChars: stderr.length,
+        });
+        return fallbackPath;
+    }
+}
+async function readAgyArtifactResult(artifactPath, prompt, signal, requestId) {
+    const receipt = await readAgyArtifact(artifactPath, signal);
+    const { buffer } = receipt;
+    let result;
+    try {
+        throwIfAgyAborted(signal);
+        const b64 = buffer.toString("base64");
+        const mime = detectImageMimeFromB64(b64) || "image/png";
+        logEvent("agy", "generate:done", {
+            requestId,
+            artifactPath,
+            b64Len: b64.length,
+            mime,
+            fileBytes: buffer.length,
+        });
+        result = {
+            b64,
+            revisedPrompt: prompt,
+            usage: { agy_artifact_bytes: buffer.length },
+            webSearchCalls: 0,
+            mime,
+        };
+    }
+    finally {
+        // Only the trusted reader's issued receipt authorizes artifact cleanup.
+        await cleanupAgyArtifact(receipt);
+    }
+    throwIfAgyAborted(signal);
+    return result;
+}
+export async function generateViaAgy(prompt, options = {}) {
+    throwIfAgyAborted(options.signal);
+    const refDetails = (options.references || []).slice(0, deriveReferenceLimit("agy", "edit"));
+    const { paths: refPaths, cleanup } = await writeRefsToTempFiles(refDetails);
+    let result;
+    try {
+        throwIfAgyAborted(options.signal);
+        const agyPrompt = buildAgyPrompt(prompt, refPaths);
+        logEvent("agy", "generate:start", {
+            requestId: options.requestId,
+            promptChars: prompt.length,
+            agyPromptChars: agyPrompt.length,
+            refs: refPaths.length,
+        });
+        const generationStartedAtMs = Date.now();
+        const { stdout, stderr } = await spawnAgy(agyPrompt, options.signal);
+        throwIfAgyAborted(options.signal);
+        const artifactPath = await resolveAgyArtifactPath(stdout, stderr, generationStartedAtMs, options.requestId);
+        throwIfAgyAborted(options.signal);
+        result = await readAgyArtifactResult(artifactPath, prompt, options.signal, options.requestId);
+    }
+    catch (err) {
+        try {
+            logEvent("agy", "generate:failed_cleanup", { requestId: options.requestId });
+        }
+        catch { /* Logging must not replace the primary operation error. */ }
+        throw err;
+    }
+    finally {
+        await cleanup();
+    }
+    // No await after this barrier: cancellation during reference cleanup must win.
+    throwIfAgyAborted(options.signal);
+    return result;
+}

package/lib/providers/adapters/comfy.js

@@ -35,6 +35,7 @@ export function createComfyAdapter(ctx) {
                 id: workflow.id,
                 kind: "image",
                 supports: {
+                    generate: true,
                     edit: Boolean(workflow.bind.refImage),
                     mask: false,
                     streaming: false,

package/lib/providers/adapters/geminiOperations.js

@@ -0,0 +1,214 @@
+import { logEvent } from "../../logger.js";
+import { detectImageMimeFromB64 } from "../../refs.js";
+import { getVertexAccessToken, getVertexProjectId, isVertexInitialized } from "../../vertexAuth.js";
+import { deriveReferenceLimit } from "../../providers/derive.js";
+const MODEL_ID_MAP = {
+    "nano-banana-2": "gemini-3.1-flash-image",
+    "nano-banana-pro": "gemini-3-pro-image",
+};
+const GEMINI_TIMEOUT_MS = 120_000;
+// Public v1beta ImageResponseFormat uses enums (ASPECT_RATIO_*/IMAGE_SIZE_*),
+// while Vertex imageConfig takes plain strings ("1:1"/"1K") — mixing them got
+// every public-API request rejected with invalid aspect_ratio (070 QA).
+const V1BETA_ASPECT_ENUM = {
+    "1:1": "ASPECT_RATIO_ONE_BY_ONE", "2:3": "ASPECT_RATIO_TWO_BY_THREE",
+    "3:2": "ASPECT_RATIO_THREE_BY_TWO", "3:4": "ASPECT_RATIO_THREE_BY_FOUR",
+    "4:3": "ASPECT_RATIO_FOUR_BY_THREE", "4:5": "ASPECT_RATIO_FOUR_BY_FIVE",
+    "5:4": "ASPECT_RATIO_FIVE_BY_FOUR", "9:16": "ASPECT_RATIO_NINE_BY_SIXTEEN",
+    "16:9": "ASPECT_RATIO_SIXTEEN_BY_NINE", "21:9": "ASPECT_RATIO_TWENTY_ONE_BY_NINE",
+    "1:8": "ASPECT_RATIO_ONE_BY_EIGHT", "8:1": "ASPECT_RATIO_EIGHT_BY_ONE",
+    "1:4": "ASPECT_RATIO_ONE_BY_FOUR", "4:1": "ASPECT_RATIO_FOUR_BY_ONE",
+};
+const V1BETA_SIZE_ENUM = {
+    "512": "IMAGE_SIZE_FIVE_TWELVE",
+    "1K": "IMAGE_SIZE_ONE_K",
+    "2K": "IMAGE_SIZE_TWO_K",
+    "4K": "IMAGE_SIZE_FOUR_K",
+};
+function toV1BetaImageFormat(params) {
+    const aspect = V1BETA_ASPECT_ENUM[params.aspectRatio];
+    const size = V1BETA_SIZE_ENUM[params.imageSize];
+    if (!aspect)
+        throw new Error(`gemini-api: no v1beta aspect enum for ${params.aspectRatio}`);
+    if (!size)
+        throw new Error(`gemini-api: no v1beta image-size enum for ${params.imageSize}`);
+    return { aspect_ratio: aspect, image_size: size };
+}
+function parseGeminiImageParams(size) {
+    if (!size || size === "auto" || size === "1024x1024")
+        return { aspectRatio: "1:1", imageSize: "1K" };
+    const match = size.match(/^(\d+)x(\d+)$/);
+    if (!match)
+        return { aspectRatio: "1:1", imageSize: "1K" };
+    const w = Number(match[1]);
+    const h = Number(match[2]);
+    const ratio = w / h;
+    const ratioMap = [
+        ["1:1", 1], ["2:3", 2 / 3], ["3:2", 3 / 2], ["3:4", 3 / 4], ["4:3", 4 / 3],
+        ["4:5", 4 / 5], ["5:4", 5 / 4], ["9:16", 9 / 16], ["16:9", 16 / 9], ["21:9", 21 / 9],
+        ["1:8", 1 / 8], ["8:1", 8], ["1:4", 1 / 4], ["4:1", 4],
+    ];
+    let bestLabel = "1:1";
+    let bestDist = Infinity;
+    for (const [label, val] of ratioMap) {
+        const dist = Math.abs(ratio - val);
+        if (dist < bestDist) {
+            bestDist = dist;
+            bestLabel = label;
+        }
+    }
+    const maxDim = Math.max(w, h);
+    const imageSize = maxDim <= 512 ? "512" : maxDim <= 1024 ? "1K" : maxDim <= 2048 ? "2K" : "4K";
+    return { aspectRatio: bestLabel, imageSize };
+}
+function geminiApiError(message, status, code) {
+    const err = new Error(message);
+    err.status = status;
+    err.code = code;
+    return err;
+}
+function resolveGeminiModelId(model) {
+    return MODEL_ID_MAP[model] || model;
+}
+function buildContents(prompt, references) {
+    const parts = [];
+    // Add reference images first (if any)
+    for (const ref of references.slice(0, deriveReferenceLimit("gemini-api", "edit"))) {
+        const mime = ref.declaredMime || ref.detectedMime || detectImageMimeFromB64(ref.b64) || "image/png";
+        parts.push({
+            inlineData: {
+                mimeType: mime,
+                data: ref.b64,
+            },
+        });
+    }
+    // Add text prompt
+    parts.push({ text: prompt });
+    return [{ role: "user", parts }];
+}
+export async function generateViaGeminiApi(prompt, ctx, options = {}) {
+    const apiKey = ctx.geminiApiKey;
+    const vertexReady = ctx.hasVertexKey && isVertexInitialized();
+    const authMode = ctx.geminiAuthMode;
+    const useVertex = authMode === "vertex" ? vertexReady : (!apiKey && vertexReady);
+    if (!apiKey && !useVertex) {
+        throw geminiApiError("Gemini API key or Vertex AI credentials not configured", 401, "GEMINI_API_KEY_MISSING");
+    }
+    const model = options.model || "nano-banana-2";
+    const apiModelId = resolveGeminiModelId(model);
+    const references = (options.references || []).slice(0, deriveReferenceLimit("gemini-api", "edit"));
+    let url;
+    let authHeaders;
+    if (useVertex) {
+        const token = await getVertexAccessToken();
+        const projectId = getVertexProjectId();
+        url = `https://aiplatform.googleapis.com/v1/projects/${projectId}/locations/global/publishers/google/models/${apiModelId}:generateContent`;
+        authHeaders = { "Content-Type": "application/json", "Authorization": `Bearer ${token}` };
+    }
+    else {
+        url = `https://generativelanguage.googleapis.com/v1beta/models/${apiModelId}:generateContent`;
+        authHeaders = { "Content-Type": "application/json", "x-goog-api-key": apiKey };
+    }
+    // size "auto" → omit image config entirely so the model decides ratio/size
+    const isAutoSize = !options.size || options.size === "auto";
+    const imageParams = isAutoSize ? null : parseGeminiImageParams(options.size);
+    // Vertex AI rejects responseFormat; it expects imageConfig directly under
+    // generationConfig (camelCase). Public API uses response_format.image (snake_case).
+    const generationConfig = useVertex
+        ? {
+            responseModalities: ["TEXT", "IMAGE"],
+            ...(imageParams
+                ? { imageConfig: { aspectRatio: imageParams.aspectRatio, imageSize: imageParams.imageSize } }
+                : {}),
+        }
+        : {
+            response_modalities: ["TEXT", "IMAGE"],
+            ...(imageParams
+                ? { response_format: { image: toV1BetaImageFormat(imageParams) } }
+                : {}),
+        };
+    const configKey = useVertex ? "generationConfig" : "generation_config";
+    const body = { contents: buildContents(prompt, references), [configKey]: generationConfig };
+    logEvent("gemini-api", "generate:start", {
+        requestId: options.requestId,
+        model,
+        apiModelId,
+        promptChars: prompt.length,
+        refs: references.length,
+    });
+    const timeoutSignal = AbortSignal.timeout(GEMINI_TIMEOUT_MS);
+    const combinedSignal = options.signal
+        ? AbortSignal.any([options.signal, timeoutSignal])
+        : timeoutSignal;
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: authHeaders,
+            body: JSON.stringify(body),
+            signal: combinedSignal,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            if (res.status === 429) {
+                throw geminiApiError(`Gemini API rate limited: ${text.slice(0, 200)}`, 429, "GEMINI_API_RATE_LIMITED");
+            }
+            if (res.status === 400 || res.status === 403) {
+                throw geminiApiError(`Gemini API error: ${text.slice(0, 200)}`, res.status, "GEMINI_API_BAD_REQUEST");
+            }
+            throw geminiApiError(`Gemini API error (${res.status}): ${text.slice(0, 200)}`, 502, "GEMINI_API_UPSTREAM_ERROR");
+        }
+        const json = await res.json();
+        // Extract image from candidates[0].content.parts[]
+        const parts = json?.candidates?.[0]?.content?.parts || [];
+        let b64 = null;
+        let textResponse = "";
+        let mime = "image/png";
+        for (const part of parts) {
+            if (part.inlineData?.data) {
+                b64 = part.inlineData.data;
+                mime = part.inlineData.mimeType || "image/png";
+            }
+            if (part.text) {
+                textResponse += part.text;
+            }
+        }
+        if (!b64) {
+            // Check for safety block
+            const finishReason = json?.candidates?.[0]?.finishReason;
+            if (finishReason === "SAFETY") {
+                throw geminiApiError("Gemini API: generation blocked by safety filter", 400, "GEMINI_API_SAFETY_BLOCKED");
+            }
+            throw geminiApiError(`Gemini API: no image in response (finishReason: ${finishReason || "unknown"})`, 502, "GEMINI_API_NO_IMAGE");
+        }
+        const usageMetadata = json?.usageMetadata || {};
+        logEvent("gemini-api", "generate:done", {
+            requestId: options.requestId,
+            model,
+            b64Len: b64.length,
+            mime,
+            textResponseLen: textResponse.length,
+        });
+        return {
+            b64,
+            revisedPrompt: textResponse || prompt,
+            usage: {
+                promptTokens: usageMetadata.promptTokenCount || 0,
+                candidatesTokens: usageMetadata.candidatesTokenCount || 0,
+                totalTokens: usageMetadata.totalTokenCount || 0,
+            },
+            webSearchCalls: 0,
+            mime,
+        };
+    }
+    catch (e) {
+        if (e.name === "AbortError") {
+            if (options.signal?.aborted) {
+                throw geminiApiError("Generation canceled", 499, "GENERATION_CANCELED");
+            }
+            throw geminiApiError("Gemini API generation timed out", 504, "GENERATION_TIMEOUT");
+        }
+        if (e.code && e.status)
+            throw e;
+        throw geminiApiError(`Gemini API request failed: ${e.message}`, 502, "GEMINI_API_NETWORK_FAILED");
+    }
+}

package/lib/providers/adapters/googleExecution.js

@@ -0,0 +1,97 @@
+import { requireRuntimeContext } from "../../runtimeContext.js";
+import { detectImageMimeFromB64 } from "../../refs.js";
+import { generateViaAgy } from "./agyOperations.js";
+import { generateViaGeminiApi } from "./geminiOperations.js";
+export function isGoogleRequest(request) {
+    return request.provider === "agy" || request.provider === "gemini-api";
+}
+function googleInput(request) {
+    if (request.surface === "edit") {
+        return {
+            prompt: `Edit this image: ${request.prompt}`,
+            references: [{ b64: request.sourceImage, declaredMime: null,
+                    detectedMime: detectImageMimeFromB64(request.sourceImage) || null }],
+        };
+    }
+    if (request.surface === "node") {
+        const selectedRefs = request.contextMode === "parent-only" ? [] : request.references;
+        return {
+            prompt: request.sourceImage ? `Edit this image: ${request.prompt}` : request.prompt,
+            references: request.sourceImage
+                ? [{ b64: request.sourceImage, declaredMime: null, detectedMime: null }, ...selectedRefs]
+                : selectedRefs,
+        };
+    }
+    return { prompt: request.prompt, references: request.references };
+}
+function prepareGoogleClassic(ctx, request) {
+    const { provider, prompt, requestId } = request;
+    const { model, size } = request.options;
+    // Classic captures scalars once; each attempt reads live refs, signal and credentials.
+    return { execute: async () => {
+            try {
+                const value = provider === "agy"
+                    ? await generateViaAgy(prompt, { references: request.references, signal: request.signal, requestId })
+                    : await generateViaGeminiApi(prompt, requireRuntimeContext(ctx), {
+                        model, size, signal: request.signal,
+                        ...(requestId !== undefined ? { requestId } : {}),
+                        references: request.references,
+                    });
+                return { kind: "single", value };
+            }
+            catch (error) {
+                throw error;
+            } // Preserve native identity; caller owns normalization.
+        } };
+}
+async function runGoogleImage(ctx, request, input) {
+    try {
+        const { provider, signal, requestId, options } = request;
+        if (provider === "agy") {
+            return await generateViaAgy(input.prompt, { references: input.references, signal, requestId });
+        }
+        return await generateViaGeminiApi(input.prompt, request.surface === "node" ? requireRuntimeContext(ctx) : ctx, {
+            model: options.model, size: options.size, signal,
+            ...(requestId !== undefined ? { requestId } : {}),
+            references: input.references,
+        });
+    }
+    catch (error) {
+        throw error;
+    }
+}
+function googleSequence(result) {
+    // Preserve the dense one-image projection; the caller owns the final persistence sweep.
+    return {
+        images: [{ b64: result.b64, ...(result.revisedPrompt !== undefined ? { revisedPrompt: result.revisedPrompt } : {}) }],
+        usage: result.usage, webSearchCalls: result.webSearchCalls,
+    };
+}
+export async function prepareGoogleExecution(ctx, request, _progress) {
+    try {
+        switch (request.surface) {
+            case "classic": return prepareGoogleClassic(ctx, request);
+            case "node":
+            case "edit": return { execute: async () => {
+                    try {
+                        return { kind: "single", value: await runGoogleImage(ctx, request, googleInput(request)) };
+                    }
+                    catch (error) {
+                        throw error;
+                    } // Caller owns retries, cancellation and cleanup.
+                } };
+            case "multimode": return { execute: async () => {
+                    try {
+                        const result = await runGoogleImage(ctx, request, googleInput(request));
+                        return { kind: "sequence", value: googleSequence(result) };
+                    }
+                    catch (error) {
+                        throw error;
+                    }
+                } };
+        }
+    }
+    catch (error) {
+        throw error;
+    }
+}

package/lib/providers/adapters/grokExecution.js

@@ -0,0 +1,137 @@
+import { planGrokImage } from "../../grokImagePlanner.js";
+import { resolveGrokQualityModel } from "../../imageModels.js";
+import { toGrokReferences } from "../../nodeHelpers.js";
+import { generateViaGrok, editViaGrok } from "./grokOperations.js";
+import { generateMultimodeViaGrok } from "./grokMultimodeOperations.js";
+export function isGrokRequest(request) {
+    return request.provider === "grok" || request.provider === "grok-api";
+}
+async function prepareGrokClassic(ctx, request) {
+    try {
+        const { provider: activeProvider, prompt: generationPrompt, requestId } = request;
+        const { model: imageModel, quality, size: effectiveSize, webSearchEnabled } = request.options;
+        const grokRefs = request.providerUrl
+            ? [{ b64: "", url: request.providerUrl, declaredMime: "image/png", detectedMime: "image/png" }, ...request.references]
+            : request.references;
+        // Keep classic's once-per-batch key and shared plan capture before any image attempt.
+        const grokDirectApiKey = activeProvider === "grok-api" ? ctx.xaiApiKey : undefined;
+        const sharedGrokPlan = await planGrokImage(generationPrompt, ctx, {
+            model: resolveGrokQualityModel(imageModel, quality),
+            size: effectiveSize,
+            signal: request.signal,
+            requestId,
+            referenceCount: grokRefs.length,
+            references: grokRefs,
+            directApiKey: grokDirectApiKey,
+            backgroundConstraint: request.backgroundConstraint,
+            webSearchEnabled,
+        });
+        return { execute: async () => {
+                try {
+                    const grokModel = resolveGrokQualityModel(imageModel, quality);
+                    const value = await generateViaGrok(generationPrompt, ctx, {
+                        model: grokModel,
+                        size: effectiveSize,
+                        signal: request.signal,
+                        requestId,
+                        plannedPrompt: sharedGrokPlan?.prompt,
+                        webSearchCalls: sharedGrokPlan?.webSearchCalls,
+                        references: grokRefs,
+                        directApiKey: grokDirectApiKey,
+                    });
+                    return { kind: "single", value };
+                }
+                catch (error) {
+                    throw error;
+                } // Caller owns lifecycle and the existing error envelope.
+            } };
+    }
+    catch (error) {
+        throw error;
+    }
+}
+function prepareGrokNode(ctx, request) {
+    // The outer execution boundary checks current presence; retries retain this key.
+    const grokDirectApiKey = request.provider === "grok-api" ? ctx.xaiApiKey : undefined;
+    return { execute: async () => {
+            try {
+                return { kind: "single", value: await executeGrokNode(ctx, request, grokDirectApiKey) };
+            }
+            catch (error) {
+                throw error;
+            } // The caller owns retries and normalization.
+        } };
+}
+async function executeGrokNode(ctx, request, grokDirectApiKey) {
+    try {
+        const { sourceImage: parentB64, prompt: generationPrompt, references, requestId, signal, options } = request;
+        const { model, size, webSearchEnabled } = options;
+        const refsForRequest = request.contextMode === "parent-only" ? [] : references;
+        return await generateViaGrok(generationPrompt, ctx, {
+            model, size, requestId, signal,
+            references: toGrokReferences(parentB64, refsForRequest),
+            directApiKey: grokDirectApiKey,
+            webSearchEnabled,
+        });
+    }
+    catch (error) {
+        throw error;
+    }
+}
+async function executeGrokEdit(ctx, request) {
+    try {
+        const { provider, rawPrompt, sourceImage, signal, requestId, options } = request;
+        const directApiKey = provider === "grok-api" ? ctx.xaiApiKey : undefined;
+        return await editViaGrok(rawPrompt, sourceImage, ctx, {
+            model: resolveGrokQualityModel(options.model, options.quality),
+            size: options.size, signal, requestId, directApiKey,
+        });
+    }
+    catch (error) {
+        throw error;
+    }
+}
+async function executeGrokMultimode(ctx, request, progress) {
+    try {
+        const { provider, prompt, references, signal, requestId, options, maxImages } = request;
+        const directApiKey = provider === "grok-api" ? ctx.xaiApiKey : undefined;
+        const grokRefs = request.providerUrl
+            ? [{ b64: "", url: request.providerUrl }, ...references] : references;
+        return await generateMultimodeViaGrok(prompt, ctx, {
+            model: resolveGrokQualityModel(options.model, options.quality), maxImages,
+            size: options.size, signal, requestId, references: grokRefs, directApiKey,
+            onFinalImage: progress.onFinalImage,
+            webSearchEnabled: options.webSearchEnabled,
+        });
+    }
+    catch (error) {
+        throw error;
+    }
+}
+export async function prepareGrokExecution(ctx, request, progress = {}) {
+    try {
+        switch (request.surface) {
+            case "classic": return await prepareGrokClassic(ctx, request);
+            case "node": return prepareGrokNode(ctx, request);
+            case "edit": return { execute: async () => {
+                    try {
+                        return { kind: "single", value: await executeGrokEdit(ctx, request) };
+                    }
+                    catch (error) {
+                        throw error;
+                    } // Route owns failure normalization and job cleanup.
+                } };
+            case "multimode": return { execute: async () => {
+                    try {
+                        return { kind: "sequence", value: await executeGrokMultimode(ctx, request, progress) };
+                    }
+                    catch (error) {
+                        throw error;
+                    } // Caller owns partial-timeout recovery.
+                } };
+        }
+    }
+    catch (error) {
+        throw error;
+    }
+}