ima2-gen 1.1.13 → 1.1.16

package/routes/generate.ts

@@ -1,12 +1,13 @@
-import { mkdir, writeFile } from "fs/promises";
+import { mkdir, readFile, writeFile } from "fs/promises";
 import { join } from "path";
 import { randomBytes } from "crypto";
 import type { Express, Request, Response } from "express";
-import { summarizeReferencePayload, validateAndNormalizeRefs } from "../lib/refs.js";
+import { detectImageMimeFromB64, summarizeReferencePayload, validateAndNormalizeRefs } from "../lib/refs.js";
 import { classifyUpstreamError } from "../lib/errorClassify.js";
 import { normalizeOAuthParams } from "../lib/oauthNormalize.js";
 import { resolveProviderOptions } from "../lib/providerOptions.js";
 import { generateViaResponses } from "../lib/responsesImageAdapter.js";
+import { generateViaGrok, planGrokImage } from "../lib/grokImageAdapter.js";
 import { isNonRetryableGenerationError, normalizeGenerationFailure, type UpstreamErr } from "../lib/generationErrors.js";
 import { startJob, finishJob, registerJobAbortController, isJobCanceled } from "../lib/inflight.js";
 import {
@@ -31,6 +32,12 @@ function validateModeration(ctx: RuntimeContext, moderation: unknown) {
   return { moderation };
 }
 
+function imageFormatFromMime(mime: string | null | undefined): "png" | "jpeg" | "webp" {
+  if (mime === "image/jpeg") return "jpeg";
+  if (mime === "image/webp") return "webp";
+  return "png";
+}
+
 export function registerGenerateRoutes(app: Express, ctxRaw: RouteRuntimeContext) {
   const ctx = requireRuntimeContext(ctxRaw);
   app.post("/api/generate", async (req: Request, res: Response) => {
@@ -119,6 +126,16 @@ export function registerGenerateRoutes(app: Express, ctxRaw: RouteRuntimeContext
         return res.status(400).json({ error: refCheckResult.error, code: refCheckResult.code });
       }
       const refCheck = refCheckResult as Extract<typeof refCheckResult, { refs: string[] }>;
+      if (activeProvider === "grok" && refCheck.refs.length > 3) {
+        finishStatus = "error";
+        finishHttpStatus = 400;
+        finishErrorCode = "GROK_REF_TOO_MANY";
+        return res.status(400).json({
+          error: "Grok image editing supports up to 3 reference images",
+          code: "GROK_REF_TOO_MANY",
+          requestId,
+        });
+      }
 
       const client = req.get("x-ima2-client") || "ui";
       const referenceDiagnostics = refCheck.referenceDiagnostics || [];
@@ -146,10 +163,37 @@ export function registerGenerateRoutes(app: Express, ctxRaw: RouteRuntimeContext
       const startTime = Date.now();
 
       const mimeMap: Record<string, string> = { png: "image/png", jpeg: "image/jpeg", webp: "image/webp" };
-      const mime = mimeMap[String(format)] || "image/png";
+      const effectiveFormat = activeProvider === "grok" ? "jpeg" : String(format);
+      const mime = mimeMap[effectiveFormat] || "image/png";
       await mkdir(ctx.config.storage.generatedDir, { recursive: true });
 
+      const sharedGrokPlan = activeProvider === "grok"
+        ? await planGrokImage(prompt, ctx, {
+          model: quality === "high" ? "grok-imagine-image-quality" : imageModel,
+          size: effectiveSize,
+          signal: cancelController.signal,
+          requestId,
+          referenceCount: refCheck.refs.length,
+          references: refCheck.refDetails,
+        })
+        : null;
+
       const generateOne = async () => {
+        if (activeProvider === "grok") {
+          const grokModel = quality === "high" ? "grok-imagine-image-quality" : imageModel;
+          const r = await generateViaGrok(prompt, ctx, {
+            model: grokModel,
+            size: effectiveSize,
+            signal: cancelController.signal,
+            requestId,
+            plannedPrompt: sharedGrokPlan?.prompt,
+            webSearchCalls: sharedGrokPlan?.webSearchCalls,
+            references: refCheck.refDetails,
+          });
+          throwIfJobCanceled(requestId);
+          return r;
+        }
+
         const MAX_RETRIES = 1;
         let lastErr: unknown;
         for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
@@ -169,6 +213,7 @@ export function registerGenerateRoutes(app: Express, ctxRaw: RouteRuntimeContext
                 reasoningEffort,
                 webSearchEnabled,
                 signal: cancelController.signal,
+                allowPromptOnlyOAuthFallback: activeProvider !== "api",
               },
             );
             throwIfJobCanceled(requestId);
@@ -195,11 +240,35 @@ export function registerGenerateRoutes(app: Express, ctxRaw: RouteRuntimeContext
       const images: Array<{ image: string; filename: string; revisedPrompt: any }> = [];
       let totalUsage: Record<string, number> | null = null;
       let totalWebSearchCalls = 0;
+      let firstRetryMeta: Record<string, unknown> | null = null;
       for (const r of results) {
         if (r.status === "fulfilled" && r.value.b64) {
           throwIfJobCanceled(requestId);
+          const valueWithMime = r.value as typeof r.value & { mime?: string };
+          const resultMime = activeProvider === "grok"
+            ? (valueWithMime.mime || detectImageMimeFromB64(r.value.b64) || mime)
+            : mime;
+          const resultFormat = activeProvider === "grok" ? imageFormatFromMime(resultMime) : effectiveFormat;
+          const retryValue = r.value as typeof r.value & {
+            retryKind?: string;
+            initialEventCount?: number;
+            initialEventTypes?: unknown;
+            referencesDroppedOnRetry?: boolean;
+            developerPromptDroppedOnRetry?: boolean;
+            webSearchDroppedOnRetry?: boolean;
+          };
+          if (!firstRetryMeta && retryValue.retryKind) {
+            firstRetryMeta = {
+              retryKind: retryValue.retryKind,
+              initialEventCount: retryValue.initialEventCount ?? null,
+              initialEventTypes: retryValue.initialEventTypes || null,
+              referencesDroppedOnRetry: retryValue.referencesDroppedOnRetry ?? null,
+              developerPromptDroppedOnRetry: retryValue.developerPromptDroppedOnRetry ?? null,
+              webSearchDroppedOnRetry: retryValue.webSearchDroppedOnRetry ?? null,
+            };
+          }
           const rand = randomBytes(ctx.config.ids.generatedHexBytes).toString("hex");
-          const filename = `${Date.now()}_${rand}_${images.length}.${format}`;
+          const filename = `${Date.now()}_${rand}_${images.length}.${resultFormat}`;
           const meta = {
             kind: "classic",
             requestId,
@@ -213,9 +282,10 @@ export function registerGenerateRoutes(app: Express, ctxRaw: RouteRuntimeContext
             composerInsertedPrompts,
             quality,
             size: effectiveSize,
-            format,
+            format: resultFormat,
             moderation,
-            model: imageModel,
+            model: activeProvider === "grok" ? (quality === "high" ? "grok-imagine-image-quality" : imageModel) : imageModel,
+            reasoningEffort,
             provider: activeProvider,
             createdAt: Date.now(),
             usage: r.value.usage || null,
@@ -224,7 +294,7 @@ export function registerGenerateRoutes(app: Express, ctxRaw: RouteRuntimeContext
             refsCount: refCheck.refs.length,
           };
           const rawBuffer = Buffer.from(r.value.b64, "base64");
-          const embedded: any = await embedImageMetadataBestEffort(rawBuffer, format, meta, {
+          const embedded: any = await embedImageMetadataBestEffort(rawBuffer, resultFormat, meta, {
             version: ctx.packageVersion,
           });
           if (!embedded.embedded) {
@@ -239,7 +309,7 @@ export function registerGenerateRoutes(app: Express, ctxRaw: RouteRuntimeContext
           await writeFile(join(ctx.config.storage.generatedDir, filename + ".json"), JSON.stringify(meta)).catch(() => {});
           invalidateHistoryIndex();
           images.push({
-            image: `data:${mime};base64,${r.value.b64}`,
+            image: `data:${resultMime};base64,${r.value.b64}`,
             filename,
             revisedPrompt: r.value.revisedPrompt || null,
           });
@@ -253,7 +323,11 @@ export function registerGenerateRoutes(app: Express, ctxRaw: RouteRuntimeContext
               });
             }
           }
-          if (typeof r.value.webSearchCalls === "number") totalWebSearchCalls += r.value.webSearchCalls;
+          if (typeof r.value.webSearchCalls === "number") {
+            totalWebSearchCalls = activeProvider === "grok"
+              ? Math.max(totalWebSearchCalls, r.value.webSearchCalls)
+              : totalWebSearchCalls + r.value.webSearchCalls;
+          }
         } else if (r.status === "rejected") {
           logError("generate", "parallel_failed", r.reason, { requestId });
         }
@@ -284,8 +358,21 @@ export function registerGenerateRoutes(app: Express, ctxRaw: RouteRuntimeContext
             upstreamParam: firstErr.upstreamParam || null,
             diagnosticReason: firstErr.diagnosticReason || null,
             retryKind: firstErr.retryKind || null,
+            initialEventCount: firstErr.initialEventCount ?? null,
+            initialEventTypes: firstErr.initialEventTypes || null,
             referencesDroppedOnRetry: firstErr.referencesDroppedOnRetry ?? null,
+            developerPromptDroppedOnRetry: firstErr.developerPromptDroppedOnRetry ?? null,
+            webSearchDroppedOnRetry: firstErr.webSearchDroppedOnRetry ?? null,
+            fallbackEventCount: firstErr.fallbackEventCount ?? null,
+            fallbackEventTypes: firstErr.fallbackEventTypes || null,
+            fallbackImageCallSeen: firstErr.fallbackImageCallSeen ?? null,
+            fallbackImageResultCount: firstErr.fallbackImageResultCount ?? null,
             errorEventCount: firstErr.eventCount ?? null,
+            eventTypes: firstErr.eventTypes || null,
+            webSearchCalls: firstErr.webSearchCalls ?? null,
+            responseDiagnostics: firstErr.responseDiagnostics || null,
+            toolTypes: firstErr.toolTypes || null,
+            toolChoiceKind: firstErr.toolChoiceKind || null,
             requestId,
           });
         }
@@ -295,11 +382,27 @@ export function registerGenerateRoutes(app: Express, ctxRaw: RouteRuntimeContext
         return res.status(500).json({ error: "All generation attempts failed" });
       }
 
-      const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+      const elapsed = +((Date.now() - startTime) / 1000).toFixed(1);
+      // Persist elapsed (computed after the generation loop) into each image's sidecar.
+      // forward-fix: only newly generated items get elapsed. The embedded XMP is written
+      // earlier in the loop (before elapsed exists), so history reload relies on this sidecar patch.
+      await Promise.all(
+        images.map(async ({ filename }) => {
+          try {
+            const sidecarPath = join(ctx.config.storage.generatedDir, filename + ".json");
+            const sidecarMeta = JSON.parse(await readFile(sidecarPath, "utf-8"));
+            sidecarMeta.elapsed = elapsed;
+            await writeFile(sidecarPath, JSON.stringify(sidecarMeta));
+          } catch {
+            /* best-effort, matches the sidecar write .catch(() => {}) above */
+          }
+        }),
+      );
       const firstRevised = images[0]?.revisedPrompt || null;
       const extra = {
         usage: totalUsage,
         provider: activeProvider,
+        reasoningEffort,
         webSearchCalls: totalWebSearchCalls,
         quality,
         size: effectiveSize,
@@ -309,6 +412,7 @@ export function registerGenerateRoutes(app: Express, ctxRaw: RouteRuntimeContext
         revisedPrompt: firstRevised,
         promptMode: normalizedPromptMode,
         webSearchEnabled,
+        ...(firstRetryMeta || {}),
       };
 
       if (count === 1) {
@@ -358,8 +462,21 @@ export function registerGenerateRoutes(app: Express, ctxRaw: RouteRuntimeContext
         upstreamParam: ext.upstreamParam || null,
         diagnosticReason: ext.diagnosticReason || null,
         retryKind: ext.retryKind || null,
+        initialEventCount: ext.initialEventCount ?? null,
+        initialEventTypes: ext.initialEventTypes || null,
         referencesDroppedOnRetry: ext.referencesDroppedOnRetry ?? null,
+        developerPromptDroppedOnRetry: ext.developerPromptDroppedOnRetry ?? null,
+        webSearchDroppedOnRetry: ext.webSearchDroppedOnRetry ?? null,
+        fallbackEventCount: ext.fallbackEventCount ?? null,
+        fallbackEventTypes: ext.fallbackEventTypes || null,
+        fallbackImageCallSeen: ext.fallbackImageCallSeen ?? null,
+        fallbackImageResultCount: ext.fallbackImageResultCount ?? null,
         errorEventCount: ext.eventCount ?? null,
+        eventTypes: ext.eventTypes || null,
+        webSearchCalls: ext.webSearchCalls ?? null,
+        responseDiagnostics: ext.responseDiagnostics || null,
+        toolTypes: ext.toolTypes || null,
+        toolChoiceKind: ext.toolChoiceKind || null,
         requestId,
       });
     } finally {

package/routes/grok.js

@@ -0,0 +1,22 @@
+import { getGrokProxyUrl } from "../lib/grokRuntime.js";
+export function registerGrokRoutes(app, ctx) {
+    app.get("/api/grok/status", async (_req, res) => {
+        const grokCfg = ctx.config.grokProvider || {};
+        const timeoutMs = grokCfg.statusTimeoutMs || 3000;
+        try {
+            const r = await fetch(getGrokProxyUrl(ctx, "/v1/models"), {
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (r.ok) {
+                const data = await r.json();
+                const models = data?.data?.map((m) => m.id).filter(Boolean) || [];
+                const hasImageModel = models.some((m) => m.startsWith("grok-imagine"));
+                return res.json({ status: hasImageModel ? "ready" : "no_image_model", models });
+            }
+            return res.json({ status: "error", reason: `HTTP ${r.status}` });
+        }
+        catch {
+            return res.json({ status: "offline" });
+        }
+    });
+}

package/routes/grok.ts

@@ -0,0 +1,24 @@
+import type { Express } from "express";
+import type { RouteRuntimeContext } from "../lib/runtimeContext.js";
+import { getGrokProxyUrl } from "../lib/grokRuntime.js";
+
+export function registerGrokRoutes(app: Express, ctx: RouteRuntimeContext) {
+  app.get("/api/grok/status", async (_req, res) => {
+    const grokCfg = (ctx.config as any).grokProvider || {};
+    const timeoutMs = grokCfg.statusTimeoutMs || 3000;
+    try {
+      const r = await fetch(getGrokProxyUrl(ctx, "/v1/models"), {
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      if (r.ok) {
+        const data: any = await r.json();
+        const models: string[] = data?.data?.map((m: any) => m.id).filter(Boolean) || [];
+        const hasImageModel = models.some((m: string) => m.startsWith("grok-imagine"));
+        return res.json({ status: hasImageModel ? "ready" : "no_image_model", models });
+      }
+      return res.json({ status: "error", reason: `HTTP ${r.status}` });
+    } catch {
+      return res.json({ status: "offline" });
+    }
+  });
+}

package/routes/health.js

@@ -15,6 +15,11 @@ export function registerHealthRoutes(app, ctxRaw) {
             url: ctx.oauthUrl,
             status: ctx.oauthReadyState,
         },
+        grok: {
+            configuredPort: Number(ctx.grokPort),
+            actualPort: Number(ctx.grokActualPort || ctx.grokPort),
+            url: ctx.grokUrl,
+        },
     });
     app.get("/api/providers", (_req, res) => {
         res.json({

package/routes/health.ts

@@ -17,6 +17,11 @@ export function registerHealthRoutes(app: Express, ctxRaw: RouteRuntimeContext)
       url: ctx.oauthUrl,
       status: ctx.oauthReadyState,
     },
+    grok: {
+      configuredPort: Number(ctx.grokPort),
+      actualPort: Number(ctx.grokActualPort || ctx.grokPort),
+      url: ctx.grokUrl,
+    },
   });
 
   app.get("/api/providers", (_req: Request, res: Response) => {

package/routes/index.js

@@ -17,6 +17,8 @@ import { registerComfyRoutes } from "./comfy.js";
 import { registerImageImportRoutes } from "./imageImport.js";
 import { registerPromptBuilderRoutes } from "./promptBuilder.js";
 import { registerAgentRoutes } from "./agent.js";
+import { registerGrokRoutes } from "./grok.js";
+import { registerVideoRoutes } from "./video.js";
 import { requireRuntimeContext } from "../lib/runtimeContext.js";
 export function configureRoutes(app, ctxRaw) {
     const ctx = requireRuntimeContext(ctxRaw);
@@ -40,4 +42,6 @@ export function configureRoutes(app, ctxRaw) {
     registerPromptBuilderRoutes(app, ctx);
     registerPromptRoutes(app, ctx);
     registerPromptImportRoutes(app, ctx);
+    registerGrokRoutes(app, ctx);
+    registerVideoRoutes(app, ctx);
 }

package/routes/index.ts

@@ -18,6 +18,8 @@ import { registerComfyRoutes } from "./comfy.js";
 import { registerImageImportRoutes } from "./imageImport.js";
 import { registerPromptBuilderRoutes } from "./promptBuilder.js";
 import { registerAgentRoutes } from "./agent.js";
+import { registerGrokRoutes } from "./grok.js";
+import { registerVideoRoutes } from "./video.js";
 import { type RouteRuntimeContext, requireRuntimeContext } from "../lib/runtimeContext.js";
 
 export function configureRoutes(app: Express, ctxRaw: RouteRuntimeContext) {
@@ -41,4 +43,6 @@ export function configureRoutes(app: Express, ctxRaw: RouteRuntimeContext) {
   registerPromptBuilderRoutes(app, ctx);
   registerPromptRoutes(app, ctx);
   registerPromptImportRoutes(app, ctx);
+  registerGrokRoutes(app, ctx);
+  registerVideoRoutes(app, ctx);
 }

package/routes/multimode.js

@@ -1,11 +1,12 @@
 import { mkdir, writeFile } from "fs/promises";
 import { join } from "path";
 import { randomBytes } from "crypto";
-import { summarizeReferencePayload, validateAndNormalizeRefs } from "../lib/refs.js";
+import { detectImageMimeFromB64, summarizeReferencePayload, validateAndNormalizeRefs } from "../lib/refs.js";
 import { classifyUpstreamError } from "../lib/errorClassify.js";
 import { normalizeOAuthParams } from "../lib/oauthNormalize.js";
 import { resolveProviderOptions } from "../lib/providerOptions.js";
 import { generateMultimodeViaResponses } from "../lib/responsesImageAdapter.js";
+import { generateMultimodeViaGrok } from "../lib/grokMultimodeAdapter.js";
 import { startJob, finishJob, registerJobAbortController, isJobCanceled } from "../lib/inflight.js";
 import { isGenerationCanceledError, makeGenerationCanceledError, throwIfJobCanceled, } from "../lib/generationCancel.js";
 import { logEvent, logError } from "../lib/logger.js";
@@ -34,6 +35,13 @@ function sequenceStatus(returned, requested) {
         return "partial";
     return "complete";
 }
+function imageFormatFromMime(mime) {
+    if (mime === "image/jpeg")
+        return "jpeg";
+    if (mime === "image/webp")
+        return "webp";
+    return "png";
+}
 export function registerMultimodeRoutes(app, ctxRaw) {
     const ctx = requireRuntimeContext(ctxRaw);
     app.post("/api/generate/multimode", async (req, res) => {
@@ -149,7 +157,8 @@ export function registerMultimodeRoutes(app, ctxRaw) {
             });
             const startTime = Date.now();
             const mimeMap = { png: "image/png", jpeg: "image/jpeg", webp: "image/webp" };
-            const mime = mimeMap[String(format)] || "image/png";
+            const mmFormat = activeProvider === "grok" ? "jpeg" : String(format);
+            const mime = mimeMap[mmFormat] || "image/png";
             const sequenceId = `seq_${Date.now().toString(36)}_${randomBytes(4).toString("hex")}`;
             routeMaxImages = maxImages;
             routeSequenceId = sequenceId;
@@ -169,8 +178,12 @@ export function registerMultimodeRoutes(app, ctxRaw) {
                 if (persistedIndexes.has(index))
                     return;
                 throwIfJobCanceled(requestId);
+                const resultMime = activeProvider === "grok"
+                    ? (image.mime || detectImageMimeFromB64(image.b64) || mime)
+                    : mime;
+                const resultFormat = activeProvider === "grok" ? imageFormatFromMime(resultMime) : mmFormat;
                 const rand = randomBytes(ctx.config.ids.generatedHexBytes).toString("hex");
-                const filename = `${Date.now()}_${rand}_multimode_${index}.${format}`;
+                const filename = `${Date.now()}_${rand}_multimode_${index}.${resultFormat}`;
                 const meta = {
                     kind: "multimode-image",
                     generationStrategy: "one-call-text-sequence",
@@ -189,9 +202,9 @@ export function registerMultimodeRoutes(app, ctxRaw) {
                     composerInsertedPrompts,
                     quality,
                     size: effectiveSize,
-                    format,
+                    format: resultFormat,
                     moderation,
-                    model: imageModel,
+                    model: activeProvider === "grok" ? (quality === "high" ? "grok-imagine-image-quality" : imageModel) : imageModel,
                     provider: activeProvider,
                     createdAt: Date.now(),
                     usage: latestUsage,
@@ -200,14 +213,14 @@ export function registerMultimodeRoutes(app, ctxRaw) {
                     refsCount: refCheck.refs.length,
                 };
                 const rawBuffer = Buffer.from(image.b64, "base64");
-                const embedded = await embedImageMetadataBestEffort(rawBuffer, format, meta, {
+                const embedded = await embedImageMetadataBestEffort(rawBuffer, resultFormat, meta, {
                     version: ctx.packageVersion,
                 });
                 await writeFile(join(ctx.config.storage.generatedDir, filename), embedded.buffer);
                 await writeFile(join(ctx.config.storage.generatedDir, filename + ".json"), JSON.stringify(meta)).catch(() => { });
                 invalidateHistoryIndex();
                 const item = {
-                    image: `data:${mime};base64,${image.b64}`,
+                    image: `data:${resultMime};base64,${image.b64}`,
                     filename,
                     revisedPrompt: image.revisedPrompt || null,
                     sequenceId,
@@ -221,25 +234,43 @@ export function registerMultimodeRoutes(app, ctxRaw) {
                 sendSse(res, "image", item);
             };
             sendSse(res, "phase", { phase: "streaming", requestId, sequenceId, maxImages });
-            const generated = await generateMultimodeViaResponses(activeProvider, prompt, quality, effectiveSize, moderation, refCheck.refDetails || refCheck.refs, requestId, normalizedPromptMode, ctx, {
-                model: imageModel,
-                maxImages,
-                reasoningEffort,
-                webSearchEnabled,
-                onPartialImage: (partial) => isJobCanceled(requestId)
-                    ? undefined
-                    : sendSse(res, "partial", {
-                        image: `data:${mime};base64,${partial.b64}`,
-                        requestId,
-                        sequenceId,
-                        index: partial.index,
-                    }),
-                onFinalImage: async (image, index) => {
-                    const totalReturned = Math.max(index + 1, images.length + 1);
-                    await persistAndSendImage(image, index, totalReturned, sequenceStatus(totalReturned, maxImages));
-                },
-                signal: cancelController.signal,
-            });
+            let generated;
+            if (activeProvider === "grok") {
+                const grokModel = quality === "high" ? "grok-imagine-image-quality" : imageModel;
+                generated = await generateMultimodeViaGrok(prompt, ctx, {
+                    model: grokModel,
+                    maxImages,
+                    size: effectiveSize,
+                    signal: cancelController.signal,
+                    requestId,
+                    references: refCheck.refDetails,
+                    onFinalImage: async (image, index) => {
+                        const totalReturned = Math.max(index + 1, images.length + 1);
+                        await persistAndSendImage(image, index, totalReturned, sequenceStatus(totalReturned, maxImages));
+                    },
+                });
+            }
+            else {
+                generated = await generateMultimodeViaResponses(activeProvider, prompt, quality, effectiveSize, moderation, refCheck.refDetails || refCheck.refs, requestId, normalizedPromptMode, ctx, {
+                    model: imageModel,
+                    maxImages,
+                    reasoningEffort,
+                    webSearchEnabled,
+                    onPartialImage: (partial) => isJobCanceled(requestId)
+                        ? undefined
+                        : sendSse(res, "partial", {
+                            image: `data:${mime};base64,${partial.b64}`,
+                            requestId,
+                            sequenceId,
+                            index: partial.index,
+                        }),
+                    onFinalImage: async (image, index) => {
+                        const totalReturned = Math.max(index + 1, images.length + 1);
+                        await persistAndSendImage(image, index, totalReturned, sequenceStatus(totalReturned, maxImages));
+                    },
+                    signal: cancelController.signal,
+                });
+            }
             throwIfJobCanceled(requestId);
             latestUsage = generated.usage || null;
             latestWebSearchCalls = generated.webSearchCalls || 0;
@@ -250,6 +281,20 @@ export function registerMultimodeRoutes(app, ctxRaw) {
             const returned = images.length;
             const status = sequenceStatus(returned, maxImages);
             const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+            if (returned === 0) {
+                finishStatus = "error";
+                finishHttpStatus = 422;
+                finishErrorCode = "EMPTY_RESPONSE";
+                finishMeta = { sequenceId, filenames: [], imageCount: 0, maxImages, status, composerPrompt: routeComposerPrompt, composerInsertedPrompts: routeComposerInsertedPrompts };
+                sendSse(res, "error", {
+                    error: "No image data returned from the multimode stream",
+                    code: finishErrorCode,
+                    status: finishHttpStatus,
+                    requestId, sequenceId, requested: maxImages, returned,
+                });
+                logEvent("multimode", "empty_response", { requestId, sequenceId, maxImages, elapsedMs: Date.now() - startTime });
+                return;
+            }
             finishMeta = {
                 sequenceId,
                 filenames: images.map((image) => image.filename),