ima2-gen 3.13.1 → 3.14.0

package/lib/responsesTransport.js

@@ -0,0 +1,190 @@
+import { logEvent } from "./logger.js";
+import { classifyUpstreamError, classifyUpstreamErrorCode } from "./errorClassify.js";
+import { errInfo } from "./errInfo.js";
+import { setJobPhase } from "./inflight.js";
+import { parseJson, parseStream, safeDiagnosticLabel, } from "./responsesParse.js";
+import { waitForOAuthReady } from "./oauthProxy.js";
+const RESPONSES_ERROR_MARKER = "ima2ResponsesError";
+function makeError(message, { status = 500, code = "RESPONSES_IMAGE_ERROR", cause, ...rest } = {}) {
+    const err = new Error(message);
+    err.status = status;
+    err.code = code;
+    if (cause)
+        err.cause = cause;
+    Object.assign(err, rest);
+    Object.defineProperty(err, RESPONSES_ERROR_MARKER, { value: true });
+    return err;
+}
+function parseOpenAIErrorBody(text) {
+    try {
+        const parsed = JSON.parse(text);
+        const error = parsed?.error || {};
+        return {
+            message: typeof error.message === "string" && error.message ? error.message : "OpenAI request failed",
+            code: safeDiagnosticLabel(error.code),
+            type: safeDiagnosticLabel(error.type),
+            param: safeDiagnosticLabel(error.param),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function normalizedCode(upstream) {
+    const byCode = classifyUpstreamErrorCode(upstream?.code);
+    if (byCode !== "UNKNOWN")
+        return byCode;
+    const byType = classifyUpstreamErrorCode(upstream?.type);
+    if (byType !== "UNKNOWN")
+        return byType;
+    const byMessage = classifyUpstreamError(upstream?.message);
+    return byMessage !== "UNKNOWN" ? byMessage : "RESPONSES_IMAGE_ERROR";
+}
+function safeUpstreamClientMessage(upstream, status) {
+    const code = normalizedCode(upstream);
+    if (code === "AUTH_API_KEY_INVALID")
+        return "API key is invalid or unavailable.";
+    if (code === "MODERATION_REFUSED")
+        return "OpenAI refused the image request for safety reasons.";
+    if (code === "INVALID_REQUEST") {
+        return upstream?.param
+            ? "OpenAI rejected the image request parameters."
+            : "OpenAI rejected the image request.";
+    }
+    if (status === 401 || status === 403)
+        return "OpenAI authentication failed.";
+    if (status === 429)
+        return "OpenAI rate limited the image request.";
+    return "OpenAI rejected the image request.";
+}
+function safeBaseUrl(value) {
+    try {
+        const parsed = new URL(value);
+        parsed.username = "";
+        parsed.password = "";
+        return parsed.toString().replace(/\/$/, "");
+    }
+    catch {
+        return value.replace(/\/$/, "");
+    }
+}
+function apiAuthorizationHeader(apiKey) {
+    const key = typeof apiKey === "string" ? apiKey.trim() : "";
+    if (!key) {
+        throw makeError("API key is required for API provider image generation", {
+            status: 401,
+            code: "API_KEY_REQUIRED",
+        });
+    }
+    if (/[\u0000-\u001f\u007f]/.test(key)) {
+        throw makeError("API key contains invalid characters.", {
+            status: 401,
+            code: "AUTH_API_KEY_INVALID",
+        });
+    }
+    return `Bearer ${key}`;
+}
+function isKnownResponsesError(value) {
+    return Boolean(value &&
+        typeof value === "object" &&
+        value.ima2ResponsesError === true);
+}
+async function getEndpoint(ctx, provider, _scope) {
+    if (provider === "api") {
+        return {
+            url: "https://api.openai.com/v1/responses",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "text/event-stream",
+                Authorization: apiAuthorizationHeader(ctx.apiKey),
+            },
+        };
+    }
+    await waitForOAuthReady(ctx);
+    const port = ctx?.config?.oauth?.proxyPort || 10531;
+    return {
+        url: `${safeBaseUrl(ctx?.oauthUrl || `http://127.0.0.1:${port}`)}/v1/responses`,
+        headers: { "Content-Type": "application/json", Accept: "text/event-stream" },
+    };
+}
+function combineAbortSignals(signals) {
+    const only = signals[0];
+    if (signals.length === 1 && only)
+        return only;
+    const controller = new AbortController();
+    for (const signal of signals) {
+        if (signal.aborted) {
+            controller.abort();
+            break;
+        }
+        signal.addEventListener("abort", () => controller.abort(), { once: true });
+    }
+    return controller.signal;
+}
+export async function postResponses({ ctx, provider, scope, payload, requestId, maxImages = 1, signal = null, onPartialImage = null, onFinalImage = null, }) {
+    const { url, headers } = await getEndpoint(ctx, provider, scope);
+    const timeoutMs = ctx?.config?.oauth?.generationTimeoutMs || 400 * 1000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const fetchSignal = signal
+        ? combineAbortSignals([controller.signal, signal])
+        : controller.signal;
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: headers,
+            signal: fetchSignal,
+            body: JSON.stringify(payload),
+        });
+        logEvent(scope, "response", { requestId, provider, status: res.status, contentType: res.headers.get("content-type") });
+        if (!res.ok) {
+            const text = await res.text();
+            const upstream = parseOpenAIErrorBody(text);
+            if (res.status >= 400 && res.status < 500 && upstream?.message) {
+                throw makeError(safeUpstreamClientMessage(upstream, res.status), {
+                    status: res.status,
+                    code: normalizedCode(upstream),
+                    upstreamBodyChars: text.length,
+                    upstreamCode: upstream.code,
+                    upstreamType: upstream.type,
+                    upstreamParam: upstream.param,
+                    upstreamMessageRedacted: true,
+                });
+            }
+            throw makeError(`${provider === "api" ? "OpenAI API" : "OAuth proxy"} returned ${res.status}`, {
+                status: res.status,
+                upstreamBodyChars: text.length,
+            });
+        }
+        if (requestId)
+            setJobPhase(requestId, "streaming");
+        const contentType = res.headers.get("content-type") || "";
+        return contentType.includes("text/event-stream")
+            ? await parseStream(res, { requestId, scope, maxImages, onPartialImage, onFinalImage })
+            : await parseJson(res, maxImages);
+    }
+    catch (e) {
+        const err = errInfo(e);
+        if (err.name === "AbortError") {
+            if (signal?.aborted) {
+                throw makeError("Generation canceled", {
+                    status: 499,
+                    code: "GENERATION_CANCELED",
+                    cause: err.raw,
+                });
+            }
+            throw makeError("Responses image generation timed out", { status: 504, code: "RESPONSES_IMAGE_TIMEOUT", cause: err.raw });
+        }
+        if (isKnownResponsesError(err.raw))
+            throw err.raw;
+        throw makeError("Responses request failed before receiving a response", {
+            status: 502,
+            code: "NETWORK_FAILED",
+            errorName: err.name,
+            upstreamMessageRedacted: true,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/lib/spriteJobEvents.js

@@ -1,5 +1,23 @@
 import { publish } from "./eventBus.js";
 import { writeSse } from "./routeHelpers.js";
 import { publishJobEvent } from "./ssePublish.js";
-export function createSpriteJobEmitter(res, requestId) { return { emit(event, data) { const wrote = !res.writableEnded ? writeSse(res, event, data) : false; const published = event === "done" ? publishJobEvent(requestId, event, data) : (publish(requestId, event, data), true); return wrote || published; }, end() { if (!res.writableEnded)
-        res.end(); } }; }
+export function createSpriteJobEmitter(res, requestId) {
+    return {
+        emit(event, data) {
+            const wrote = !res.writableEnded ? writeSse(res, event, data) : false;
+            if (event !== "done" && event !== "error") {
+                publish(requestId, event, data);
+                return true;
+            }
+            // Direct legacy SSE keeps its nested error. The shared envelope reads flat fields.
+            const nested = data.error;
+            const error = nested && typeof nested === "object" && !Array.isArray(nested)
+                ? nested : null;
+            const payload = event === "error" && error ? { ...data,
+                code: error.code, error: error.message } : data;
+            return publishJobEvent(requestId, event, payload) || wrote;
+        },
+        end() { if (!res.writableEnded)
+            res.end(); },
+    };
+}

package/lib/ssePublish.js

@@ -1,16 +1,17 @@
 import { publish } from "./eventBus.js";
-import { getJobPhase, isJobCanceled } from "./inflight.js";
+import { getJobPhase, isJobCanceled, isJobTrackingExpired } from "./inflight.js";
 import { buildEnvelope } from "./jobs/envelope.js";
 /**
- * Publish a multiplexed job event. Suppresses terminal `done` after cancel so
- * clients never resolve success when abortJob already emitted `error`.
+ * Publish a multiplexed job event. Cancellation/expiry dominate later terminal
+ * errors and success, so abort listeners cannot replace the established outcome.
  *
  * Also attaches the canonical envelope (#151). The snapshot is taken here,
  * before the event is queued, so replay reproduces what was true at publish
  * time rather than re-deriving state that has since moved on.
  */
 export function publishJobEvent(requestId, event, data) {
-    if (event === "done" && isJobCanceled(requestId))
+    if ((event === "done" || event === "error") &&
+        (isJobCanceled(requestId) || isJobTrackingExpired(requestId)))
         return false;
     const inflightPhase = getJobPhase(requestId);
     publish(requestId, event, data, {

package/lib/videoExtendI2vOperation.js

@@ -0,0 +1,76 @@
+import { appendVideoContinuityEntry, lineageFromVideoMetadata } from "./videoContinuity.js";
+import { deriveChildVideoLineage } from "./videoLineage.js";
+import { invalidateHistoryIndex } from "./historyIndex.js";
+import { finishJob, isJobCanceled, setJobPhase } from "./inflight.js";
+import { makeGenerationCanceledError } from "./generationCancel.js";
+import { publish } from "./eventBus.js";
+import { publishJobEvent } from "./ssePublish.js";
+import { errInfo } from "./errInfo.js";
+import { codedVideoError as codedError, emitPhase, extractError, retryableData } from "./videoExtendedHelpers.js";
+import { errorEnvelopeFields } from "./errors/envelope.js";
+// Approved relocation: keep the original operation body and ordering unchanged.
+export async function runLastFrameI2v(task) {
+    const { ctx, requestId, sourceVideoId, prompt, model, provider, duration, resolution, aspectRatio, parent, motion, cancelController, extractFrame, generateVideo, persistArtifact, createFilename } = task;
+    const startedAt = Date.now();
+    let stage = "extracting-frame";
+    try {
+        emitPhase(requestId, stage);
+        let sourceImage;
+        try {
+            sourceImage = await extractFrame(ctx.config.storage.generatedDir, sourceVideoId, "last", { signal: cancelController.signal });
+        }
+        catch (error) {
+            throw extractError(error, cancelController.signal);
+        }
+        if (cancelController.signal.aborted)
+            throw makeGenerationCanceledError();
+        const parentContinuity = lineageFromVideoMetadata(sourceVideoId, parent);
+        const onEvent = (event) => {
+            setJobPhase(requestId, event.phase === "submitted" ? "streaming" : event.phase);
+            publish(requestId, event.phase, {
+                requestId,
+                ...(event.phase === "submitted" ? { xaiVideoRequestId: event.xaiVideoRequestId, requestedModel: event.requestedModel, effectiveModel: event.effectiveModel, modelFallback: event.modelFallback ?? null } : {}),
+                ...(event.phase === "progress" ? { progress: typeof event.progress === "number" ? event.progress / 100 : null, stalled: Boolean(event.stalled) } : {}),
+            });
+        };
+        const compiledPrompt = motion.fragment ? `${prompt}\n\nCamera motion: ${motion.fragment}.` : prompt;
+        const result = await generateVideo(compiledPrompt, ctx, {
+            model, mode: "image-to-video", duration, resolution, aspectRatio,
+            sourceImage, sourceMime: "image/png", signal: cancelController.signal,
+            requestId, continuityLineage: parentContinuity,
+            directApiKey: provider === "grok-api" ? ctx.xaiApiKey ?? undefined : undefined,
+            onEvent,
+        });
+        if (cancelController.signal.aborted)
+            throw makeGenerationCanceledError();
+        stage = "persisting";
+        emitPhase(requestId, stage);
+        const filename = createFilename(ctx);
+        const createdAt = Date.now();
+        const videoLineage = deriveChildVideoLineage(filename, sourceVideoId, parent);
+        const videoContinuity = appendVideoContinuityEntry(parentContinuity, { filename, userPrompt: prompt, revisedPrompt: result.revisedPrompt, createdAt });
+        const elapsed = +((createdAt - startedAt) / 1000).toFixed(1);
+        const video = { operation: "extend", mode: "image-to-video", sourceVideoId, sourceFrame: "last", duration: result.duration, resolution: result.resolution, aspectRatio: result.aspectRatio, xaiVideoRequestId: result.xaiVideoRequestId };
+        const metadata = { kind: "video", mediaType: "video", providerUrl: result.url, requestId, prompt, userPrompt: prompt, revisedPrompt: result.revisedPrompt, motionPresetIds: motion.ids, provider, model: result.effectiveModel, createdAt, elapsed, usage: result.usage, webSearchCalls: result.webSearchCalls, video, videoLineage, videoContinuity };
+        try {
+            await persistArtifact(ctx.config.storage.generatedDir, filename, result.videoBuffer, metadata);
+        }
+        catch (error) {
+            throw codedError(errInfo(error).message, 500, "VIDEO_PERSIST_FAILED");
+        }
+        invalidateHistoryIndex();
+        const done = { requestId, filename, url: `/generated/${encodeURIComponent(filename)}`, providerUrl: result.url, mediaType: "video", provider, model: result.effectiveModel, prompt, userPrompt: prompt, revisedPrompt: result.revisedPrompt, createdAt, elapsed, usage: result.usage, webSearchCalls: result.webSearchCalls, video, videoLineage, videoContinuity };
+        // finishJob BEFORE done (audit blocker B4): a done event must never be
+        // followed by an error from a failing inflight-completion write.
+        finishJob(requestId, { status: "completed", meta: { filename, xaiVideoRequestId: result.xaiVideoRequestId } });
+        publishJobEvent(requestId, "done", done);
+    }
+    catch (error) {
+        if (!isJobCanceled(requestId)) {
+            const info = errInfo(error);
+            // #151 stage 2: terminal failure carries the canonical envelope.
+            publishJobEvent(requestId, "error", { requestId, error: info.message, code: info.code ?? "VIDEO_EXTEND_FAILED", status: info.status ?? 500, ...retryableData(error), ...errorEnvelopeFields(error) });
+            finishJob(requestId, { status: "error", httpStatus: info.status ?? 500, errorCode: info.code ?? "VIDEO_EXTEND_FAILED", meta: { stage } });
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ima2-gen",
-  "version": "3.13.1",
+  "version": "3.14.0",
   "packageManager": "npm@11.18.0",
   "description": "Local-first visual generation runtime and studio for people and coding agents, with reproducible image and video workflows across multiple providers.",
   "type": "module",
@@ -31,6 +31,8 @@
     "prepublishOnly": "node scripts/release-contract.mjs assert-publish-context && npm run verify:release",
     "lint:pkg": "node -e \"const p=require('./package.json'); const req=['name','version','bin']; for(const k of req){if(!p[k])throw new Error('missing '+k)} const mustInclude=['bin/**/*.js','lib/**/*.js','routes/**/*.js','skills/','integrations/comfyui/ima2_gen_bridge/__init__.py','integrations/comfyui/ima2_gen_bridge/nodes.py','integrations/comfyui/ima2_gen_bridge/README.md','assets/card-news/templates/','assets/mcp-snapshots/','vendor/','server.js','LICENSE']; for(const f of mustInclude){if(!p.files.includes(f))throw new Error('files[] must include '+f)}\"",
     "docs:refresh-line-counts": "node scripts/refresh-structure-line-counts.mjs",
+    "docs:runtime": "node --import tsx scripts/generate-runtime-install-contract.mjs",
+    "docs:runtime:check": "node --import tsx scripts/generate-runtime-install-contract.mjs --check",
     "publish:dry-run": "node scripts/publish-dry-run.mjs",
     "release:patch": "gh workflow run release.yml -f bump=patch -f dry_run=false",
     "release:minor": "gh workflow run release.yml -f bump=minor -f dry_run=false",
@@ -120,9 +122,10 @@
     "@types/better-sqlite3": "^9.6.0",
     "@types/express": "^5.0.6",
     "@types/node": "^22.20.1",
+    "node-gyp": "13.0.1",
     "tsx": "^4.23.12",
     "typescript": "^5.9.3",
     "yaml": "2.9.0"
   },
-  "gitHead": "d2afe6b2aa7d006e2cd9765aa632714f96435db2"
+  "gitHead": "36aa6fcea62f753d858d20c4823e04922951c954"
 }

package/routes/edit.js

@@ -7,14 +7,9 @@ import { generateImageThumbnailFromBuffer } from "../lib/imageThumb.js";
 import { classifyUpstreamError } from "../lib/errorClassify.js";
 import { normalizeOAuthParams } from "../lib/oauthNormalize.js";
 import { resolveProviderOptions } from "../lib/providerOptions.js";
-import { editViaResponses } from "../lib/responsesImageAdapter.js";
-import { editViaGrok } from "../lib/grokImageAdapter.js";
+import { prepareImageExecution } from "../lib/providers/execution/index.js";
+import { checkImageExecutionAdmission } from "../lib/providers/execution/admission.js";
 import { resolveGrokQualityModel } from "../lib/imageModels.js";
-import { generateViaAgy } from "../lib/agyImageAdapter.js";
-import { generateViaGeminiApi } from "../lib/geminiApiImageAdapter.js";
-import { generateViaAtlasCloud } from "../lib/atlasCloudImageAdapter.js";
-import { generateViaMinimax } from "../lib/minimaxImageAdapter.js";
-import { generateViaComfy } from "../lib/comfyImageAdapter.js";
 import { startJob, finishJob, registerJobAbortController, isJobCanceled, isStartJobFailure, INFLIGHT_RETRY_AFTER_SECONDS } from "../lib/inflight.js";
 import { isGenerationCanceledError, makeGenerationCanceledError, throwIfJobCanceled, } from "../lib/generationCancel.js";
 import { logEvent, logError } from "../lib/logger.js";
@@ -25,6 +20,7 @@ import { invalidateHistoryIndex } from "../lib/historyIndex.js";
 import { errInfo } from "../lib/errInfo.js";
 import { requireRuntimeContext } from "../lib/runtimeContext.js";
 import { errorEnvelopeFields } from "../lib/errors/envelope.js";
+import { getProviderSurfaceSupport } from "../lib/providers/derive.js";
 function validateModeration(ctx, moderation) {
     if (typeof moderation !== "string" || !ctx.config.oauth.validModeration.has(moderation)) {
         return { error: "moderation must be one of: auto, low" };
@@ -103,7 +99,7 @@ export function registerEditRoutes(app, ctxRaw) {
                 rawSize: size,
                 rawWebSearchEnabled,
             });
-            if (providerOptions.error) {
+            if (providerOptions.error !== undefined) {
                 finishStatus = "error";
                 finishHttpStatus = providerOptions.status;
                 finishErrorCode = providerOptions.code;
@@ -116,6 +112,18 @@ export function registerEditRoutes(app, ctxRaw) {
             const activeProvider = providerOptions.provider;
             const sessionId = typeof req.body?.sessionId === "string" ? req.body.sessionId : null;
             const normalizedPromptMode = promptMode === "direct" ? "direct" : "auto";
+            const admission = checkImageExecutionAdmission(ctx, {
+                provider: activeProvider, surface: "edit", referenceCount: imageB64 ? 1 : 0,
+            });
+            if (admission) {
+                finishStatus = "error";
+                finishHttpStatus = admission.status;
+                finishErrorCode = admission.code;
+                return res.status(admission.status).json({
+                    error: admission.message, code: admission.code, requestId,
+                    ...errorEnvelopeFields({ code: admission.code, status: admission.status }),
+                });
+            }
             const started = startJob({
                 requestId,
                 kind: "classic",
@@ -154,7 +162,7 @@ export function registerEditRoutes(app, ctxRaw) {
             // NovelAI joins this list because its infill is a distinct action with its
             // own model ids, not a mask flag on generate; accepting a mask here would
             // silently drop it.
-            if ((activeProvider === "grok" || activeProvider === "agy" || activeProvider === "grok-api" || activeProvider === "gemini-api" || activeProvider === "atlascloud" || activeProvider === "minimax" || activeProvider === "nai" || activeProvider === "comfy") && rawMask) {
+            if (getProviderSurfaceSupport(activeProvider ?? "", "edit")?.mask === false && rawMask) {
                 finishStatus = "error";
                 finishHttpStatus = 400;
                 const code = activeProvider === "agy" ? "AGY_MASK_UNSUPPORTED" : activeProvider === "gemini-api" ? "GEMINI_API_MASK_UNSUPPORTED" : activeProvider === "atlascloud" ? "ATLASCLOUD_MASK_UNSUPPORTED" : activeProvider === "minimax" ? "MINIMAX_MASK_UNSUPPORTED" : activeProvider === "nai" ? "NAI_MASK_UNSUPPORTED" : activeProvider === "comfy" ? "COMFY_MASK_UNSUPPORTED" : "GROK_MASK_UNSUPPORTED";
@@ -165,7 +173,7 @@ export function registerEditRoutes(app, ctxRaw) {
             // is text-to-image only. Dispatching here would ignore that image and
             // return an unrelated generation, so the lane refuses instead. NovelAI's
             // img2img and infill are separate actions and a follow-on unit.
-            if (activeProvider === "nai") {
+            if (getProviderSurfaceSupport(activeProvider ?? "", "edit")?.supported === false) {
                 finishStatus = "error";
                 finishHttpStatus = 400;
                 finishErrorCode = "NAI_EDIT_UNSUPPORTED";
@@ -206,119 +214,19 @@ export function registerEditRoutes(app, ctxRaw) {
                 maskBytes: maskCheck.maskBytes ?? 0,
             });
             const startTime = Date.now();
-            let resultB64;
-            let usage;
-            let revisedPrompt;
-            let webSearchCalls = 0;
-            let resultMimeFromProvider;
-            let providerUrl = null;
-            if (activeProvider === "gemini-api") {
-                const r = await generateViaGeminiApi(`Edit this image: ${prompt}`, requireRuntimeContext(ctx), {
-                    model: imageModel,
-                    size: effectiveSize,
-                    signal: cancelController.signal,
-                    requestId,
-                    references: [{ b64: imageB64, declaredMime: null, detectedMime: detectImageMimeFromB64(imageB64) || null }],
-                });
-                resultB64 = r.b64;
-                usage = r.usage;
-                revisedPrompt = r.revisedPrompt;
-                webSearchCalls = r.webSearchCalls;
-                resultMimeFromProvider = r.mime;
-            }
-            else if (activeProvider === "agy") {
-                const r = await generateViaAgy(`Edit this image: ${prompt}`, {
-                    references: [{ b64: imageB64, declaredMime: null, detectedMime: detectImageMimeFromB64(imageB64) || null }],
-                    signal: cancelController.signal,
-                    requestId,
-                });
-                resultB64 = r.b64;
-                usage = r.usage;
-                revisedPrompt = r.revisedPrompt;
-                webSearchCalls = r.webSearchCalls;
-                resultMimeFromProvider = r.mime;
-            }
-            else if (activeProvider === "atlascloud") {
-                const r = await generateViaAtlasCloud(`Edit this image: ${prompt}`, requireRuntimeContext(ctx), {
-                    model: imageModel,
-                    size: effectiveSize,
-                    quality,
-                    signal: cancelController.signal,
-                    requestId,
-                    references: [{ b64: imageB64, declaredMime: null, detectedMime: detectImageMimeFromB64(imageB64) || null }],
-                });
-                resultB64 = r.b64;
-                providerUrl = r.providerUrl ?? null;
-                usage = r.usage;
-                revisedPrompt = r.revisedPrompt ?? undefined;
-                webSearchCalls = r.webSearchCalls;
-                resultMimeFromProvider = r.mime;
-            }
-            else if (activeProvider === "minimax") {
-                const r = await generateViaMinimax(`Edit this image: ${prompt}`, requireRuntimeContext(ctx), {
-                    model: imageModel,
-                    size: effectiveSize,
-                    signal: cancelController.signal,
-                    requestId,
-                    references: [{ b64: imageB64, declaredMime: null, detectedMime: detectImageMimeFromB64(imageB64) || null }],
-                });
-                resultB64 = r.b64;
-                providerUrl = r.providerUrl ?? null;
-                usage = r.usage;
-                revisedPrompt = r.revisedPrompt ?? undefined;
-                webSearchCalls = r.webSearchCalls;
-                resultMimeFromProvider = r.mime;
-            }
-            else if (activeProvider === "comfy") {
-                // i2i goes through the same adapter as generate: the reference is
-                // uploaded to the instance and its filename injected into the
-                // workflow's LoadImage binding. A graph without that binding refuses
-                // with COMFY_WORKFLOW_BIND_INVALID rather than silently ignoring the
-                // input image.
-                const r = await generateViaComfy(`Edit this image: ${prompt}`, requireRuntimeContext(ctx), {
-                    model: imageModel,
-                    size: effectiveSize,
-                    signal: cancelController.signal,
-                    requestId,
-                    references: [{ b64: imageB64, declaredMime: null, detectedMime: detectImageMimeFromB64(imageB64) || null }],
-                });
-                resultB64 = r.b64;
-                providerUrl = r.providerUrl ?? null;
-                usage = r.usage;
-                revisedPrompt = r.revisedPrompt ?? undefined;
-                webSearchCalls = r.webSearchCalls;
-                resultMimeFromProvider = r.mime;
-            }
-            else if (activeProvider === "grok" || activeProvider === "grok-api") {
-                const directApiKey = activeProvider === "grok-api" ? ctx.xaiApiKey : undefined;
-                const grokModel = resolveGrokQualityModel(imageModel, quality);
-                const r = await editViaGrok(prompt, imageB64, ctx, {
-                    model: grokModel,
-                    size: effectiveSize,
-                    signal: cancelController.signal,
-                    requestId,
-                    directApiKey,
-                });
-                resultB64 = r.b64;
-                providerUrl = r.providerUrl ?? null;
-                usage = r.usage;
-                revisedPrompt = r.revisedPrompt;
-                webSearchCalls = r.webSearchCalls;
-                resultMimeFromProvider = r.mime;
-            }
-            else {
-                const r = await editViaResponses(activeProvider, prompt, imageB64, quality, effectiveSize, moderation, normalizedPromptMode, ctx, requestId, {
-                    model: imageModel,
-                    reasoningEffort,
-                    webSearchEnabled,
-                    mask: maskCheck.mask,
-                    signal: cancelController.signal,
-                });
-                resultB64 = r.b64;
-                usage = r.usage ?? null;
-                revisedPrompt = r.revisedPrompt ?? undefined;
-                webSearchCalls = r.webSearchCalls ?? 0;
-            }
+            const { value: r } = await (await prepareImageExecution(ctx, {
+                surface: "edit", provider: activeProvider, requestId,
+                signal: cancelController.signal, prompt, rawPrompt: prompt,
+                sourceImage: imageB64, mask: maskCheck.mask ?? null, references: [],
+                options: { model: imageModel, quality, size: effectiveSize, moderation,
+                    mode: normalizedPromptMode, reasoningEffort, webSearchEnabled },
+            })).execute();
+            const resultB64 = r.b64;
+            const usage = r.usage;
+            const revisedPrompt = r.revisedPrompt ?? undefined;
+            const webSearchCalls = r.webSearchCalls;
+            const resultMimeFromProvider = r.mime;
+            const providerUrl = r.providerUrl ?? null;
             throwIfJobCanceled(requestId);
             const elapsed = +((Date.now() - startTime) / 1000).toFixed(1);
             await mkdir(ctx.config.storage.generatedDir, { recursive: true });