ima2-gen 2.0.15 → 2.0.16

package/lib/cardNewsPath.js

@@ -0,0 +1,25 @@
+import { isAbsolute, resolve, sep } from "node:path";
+export function assertSafeSetId(setId, status = 400) {
+    if (typeof setId === "string"
+        && !isAbsolute(setId)
+        && !setId.includes("..")
+        && !setId.includes("/")
+        && !setId.includes("\\")
+        && /^[a-zA-Z0-9_-]{3,120}$/.test(setId))
+        return setId;
+    const err = new Error(status === 404 ? "Card News set not found" : "Invalid Card News setId");
+    err.status = status;
+    err.code = status === 404 ? "CARD_NEWS_SET_NOT_FOUND" : "INVALID_CARD_NEWS_SET_ID";
+    throw err;
+}
+export function resolveCardNewsSetDir(generatedDir, setId, status = 400) {
+    const root = resolve(generatedDir, "cardnews");
+    const target = resolve(root, assertSafeSetId(setId, status));
+    if (!target.startsWith(root + sep)) {
+        const err = new Error("Invalid Card News setId");
+        err.status = status;
+        err.code = status === 404 ? "CARD_NEWS_SET_NOT_FOUND" : "INVALID_CARD_NEWS_SET_ID";
+        throw err;
+    }
+    return target;
+}

package/lib/db.js

@@ -151,6 +151,7 @@ function migrate(database) {
 	      result_image_ids TEXT NOT NULL DEFAULT '[]',
 	      error_code       TEXT,
 	      error_message    TEXT,
+	      progress_stage   TEXT,
 	      created_at       INTEGER NOT NULL,
 	      started_at       INTEGER,
 	      finished_at      INTEGER,
@@ -201,6 +202,7 @@ function migrate(database) {
     addColumnIfMissing(database, agentQueueColumns, "agent_queue_items", "result_image_ids", "TEXT NOT NULL DEFAULT '[]'");
     addColumnIfMissing(database, agentQueueColumns, "agent_queue_items", "error_code", "TEXT");
     addColumnIfMissing(database, agentQueueColumns, "agent_queue_items", "error_message", "TEXT");
+    addColumnIfMissing(database, agentQueueColumns, "agent_queue_items", "progress_stage", "TEXT");
     addColumnIfMissing(database, agentQueueColumns, "agent_queue_items", "started_at", "INTEGER");
     addColumnIfMissing(database, agentQueueColumns, "agent_queue_items", "finished_at", "INTEGER");
     // ── Prompt Library (schema v4) ──

package/lib/generatePipeline.js

@@ -0,0 +1,474 @@
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { safeWriteSidecar, atomicWriteJson } from "./atomicWrite.js";
+import { join } from "path";
+import { randomBytes } from "crypto";
+import { detectImageMimeFromB64, summarizeReferencePayload, validateAndNormalizeRefs } from "./refs.js";
+import { generateImageThumbnailFromBuffer } from "./imageThumb.js";
+import { classifyUpstreamError } from "./errorClassify.js";
+import { appendGenerationRequestLog } from "./generationRequestLog.js";
+import { normalizeOAuthParams } from "./oauthNormalize.js";
+import { resolveProviderOptions } from "./providerOptions.js";
+import { generateViaResponses } from "./responsesImageAdapter.js";
+import { generateViaGrok, planGrokImage } from "./grokImageAdapter.js";
+import { generateViaAgy } from "./agyImageAdapter.js";
+import { generateViaGeminiApi } from "./geminiApiImageAdapter.js";
+import { isNonRetryableGenerationError, normalizeGenerationFailure } from "./generationErrors.js";
+import { startJob, finishJob, registerJobAbortController, isJobCanceled, isStartJobFailure, setJobPhase, INFLIGHT_RETRY_AFTER_SECONDS, } from "./inflight.js";
+import { isGenerationCanceledError, makeGenerationCanceledError, throwIfJobCanceled, } from "./generationCancel.js";
+import { logEvent, logError } from "./logger.js";
+import { embedImageMetadataBestEffort } from "./imageMetadataStore.js";
+import { invalidateHistoryIndex } from "./historyIndex.js";
+import { normalizeComposerInsertedPrompts, normalizeComposerPrompt, } from "./composerSnapshot.js";
+import { errInfo } from "./errInfo.js";
+import { requireRuntimeContext } from "./runtimeContext.js";
+import { STORYBOARD_PREFIX } from "./storyboardPrefix.js";
+import { validateModeration, imageFormatFromMime, upstreamErrorFields } from "./routeHelpers.js";
+import { publish } from "./eventBus.js";
+import { publishJobEvent } from "./ssePublish.js";
+import { normalizeBodyRequestId, validateBoundedCount, validateGenerationPrompt } from "./generationInputValidation.js";
+export async function runGeneratePipeline(req, res, ctx) {
+    const requestId = normalizeBodyRequestId(req.body?.requestId, req.id);
+    const asyncMode = req.body?.async === true;
+    let finishStatus = "completed";
+    let finishHttpStatus;
+    let finishErrorCode;
+    let finishMeta = {};
+    let finishCanceled = false;
+    let jobOwned = false;
+    const cancelController = new AbortController();
+    const fail = (status, payload) => {
+        finishStatus = "error";
+        finishHttpStatus = status;
+        finishErrorCode = typeof payload.code === "string" ? payload.code : finishErrorCode;
+        if (asyncMode && res.headersSent) {
+            publish(requestId, "error", { ...payload, status, requestId });
+            return;
+        }
+        return res.status(status).json(payload);
+    };
+    const succeed = (payload) => {
+        if (asyncMode) {
+            publishJobEvent(requestId, "done", payload);
+            return;
+        }
+        res.json(payload);
+    };
+    try {
+        const sessionId = typeof req.body?.sessionId === "string" ? req.body.sessionId : null;
+        const clientNodeId = typeof req.body?.clientNodeId === "string" ? req.body.clientNodeId : null;
+        const { prompt, quality: rawQuality = "medium", size = "1024x1024", format = "png", moderation = "low", provider = "auto", n = 1, references = [], mode: promptMode = "auto", model: rawModel, reasoningEffort: rawReasoningEffort, webSearchEnabled: rawWebSearchEnabled = true, } = req.body;
+        const promptError = validateGenerationPrompt(prompt);
+        if (promptError)
+            return fail(400, promptError);
+        const maxGeneratedImages = Math.max(1, Math.trunc(Number(ctx.config.limits.maxGeneratedImages) || 1));
+        const countResult = validateBoundedCount(n, 1, maxGeneratedImages, "n");
+        if ("error" in countResult)
+            return fail(400, countResult);
+        const count = countResult.value;
+        const storyboardActive = req.body?.storyboard === true;
+        const storyboardPrefix = storyboardActive ? STORYBOARD_PREFIX : "";
+        const composerPrompt = normalizeComposerPrompt(req.body?.composerPrompt);
+        const composerInsertedPrompts = normalizeComposerInsertedPrompts(req.body?.composerInsertedPrompts);
+        const { quality, warnings: qualityWarnings } = normalizeOAuthParams({ provider, quality: rawQuality });
+        const providerOptions = resolveProviderOptions(ctx, {
+            provider,
+            rawModel,
+            rawReasoningEffort,
+            rawSize: size,
+            rawWebSearchEnabled,
+        });
+        if (providerOptions.error) {
+            return fail(providerOptions.status, { error: providerOptions.error, code: providerOptions.code });
+        }
+        const imageModel = providerOptions.model;
+        const reasoningEffort = providerOptions.reasoningEffort;
+        const effectiveSize = providerOptions.size;
+        const webSearchEnabled = providerOptions.webSearchEnabled;
+        const activeProvider = providerOptions.provider;
+        const normalizedPromptMode = promptMode === "direct" ? "direct" : "auto";
+        const generationPrompt = storyboardPrefix + prompt;
+        const moderationCheck = validateModeration(ctx, moderation);
+        if (moderationCheck.error)
+            return fail(400, { error: moderationCheck.error });
+        const referencePayload = summarizeReferencePayload(references);
+        const refCheckResult = validateAndNormalizeRefs(references);
+        if (refCheckResult.error) {
+            return fail(400, { error: refCheckResult.error, code: refCheckResult.code });
+        }
+        const refCheck = refCheckResult;
+        const incomingProviderUrl = typeof req.body?.providerUrl === "string" && req.body.providerUrl.startsWith("http")
+            ? req.body.providerUrl
+            : null;
+        const grokRefs = incomingProviderUrl
+            ? [{ b64: "", url: incomingProviderUrl, declaredMime: "image/png", detectedMime: "image/png" }, ...refCheck.refDetails]
+            : refCheck.refDetails;
+        const providerRefCount = activeProvider === "grok" || activeProvider === "grok-api"
+            ? grokRefs.length
+            : refCheck.refs.length;
+        if ((activeProvider === "grok" || activeProvider === "agy" || activeProvider === "grok-api" || activeProvider === "gemini-api") && providerRefCount > 3) {
+            return fail(400, {
+                error: `${activeProvider === "agy" ? "Agy" : "Grok"} image editing supports up to 3 reference images`,
+                code: activeProvider === "agy" ? "AGY_REF_TOO_MANY" : "GROK_REF_TOO_MANY",
+                requestId,
+            });
+        }
+        const started = startJob({
+            requestId,
+            kind: "classic",
+            prompt,
+            meta: {
+                kind: "classic",
+                sessionId,
+                parentNodeId: null,
+                clientNodeId,
+                quality,
+                model: imageModel,
+                size: effectiveSize,
+                n: count,
+                refsCount: providerRefCount,
+                referenceBytes: referencePayload.referenceBytes,
+                referenceB64Chars: referencePayload.referenceB64Chars,
+                composerPrompt,
+                composerInsertedPrompts,
+            },
+        });
+        if (started && isStartJobFailure(started)) {
+            const status = started.code === "TOO_MANY_JOBS" ? 429 : 409;
+            if (started.code === "TOO_MANY_JOBS") {
+                res.setHeader("Retry-After", String(INFLIGHT_RETRY_AFTER_SECONDS));
+            }
+            return fail(status, {
+                error: started.code === "TOO_MANY_JOBS"
+                    ? "Too many concurrent generation jobs"
+                    : "Request ID already in use",
+                code: started.code,
+                requestId,
+            });
+        }
+        jobOwned = true;
+        registerJobAbortController(requestId, cancelController);
+        if (asyncMode) {
+            res.status(202).json({ requestId, async: true });
+        }
+        setJobPhase(requestId, "streaming");
+        if (asyncMode)
+            publish(requestId, "phase", { requestId, phase: "streaming" });
+        const client = req.get("x-ima2-client") || "ui";
+        const referenceDiagnostics = refCheck.referenceDiagnostics || [];
+        const referenceMismatchCount = referenceDiagnostics.filter((ref) => ref.warnings?.includes("mime_mismatch")).length;
+        logEvent("generate", "request", {
+            requestId,
+            client,
+            provider: activeProvider,
+            quality,
+            model: imageModel,
+            size: effectiveSize,
+            moderation,
+            n: count,
+            refs: providerRefCount,
+            referenceBytes: referencePayload.referenceBytes,
+            referenceMismatchCount,
+            refDetectedMimes: [...new Set(referenceDiagnostics.map((ref) => ref.detectedMime).filter(Boolean))].join(","),
+            refDeclaredMimes: [...new Set(referenceDiagnostics.map((ref) => ref.declaredMime).filter(Boolean))].join(","),
+            sessionId,
+            clientNodeId,
+            promptChars: typeof prompt === "string" ? prompt.length : 0,
+            promptMode: normalizedPromptMode,
+            webSearchEnabled,
+        });
+        const startTime = Date.now();
+        const mimeMap = { png: "image/png", jpeg: "image/jpeg", webp: "image/webp" };
+        const effectiveFormat = activeProvider === "grok" || activeProvider === "agy" || activeProvider === "grok-api" || activeProvider === "gemini-api" ? "jpeg" : String(format);
+        const mime = mimeMap[effectiveFormat] || "image/png";
+        await mkdir(ctx.config.storage.generatedDir, { recursive: true });
+        const grokDirectApiKey = activeProvider === "grok-api" ? ctx.xaiApiKey : undefined;
+        const sharedGrokPlan = activeProvider === "grok" || activeProvider === "grok-api"
+            ? await planGrokImage(generationPrompt, ctx, {
+                model: quality === "high" ? "grok-imagine-image-quality" : imageModel,
+                size: effectiveSize,
+                signal: cancelController.signal,
+                requestId,
+                referenceCount: grokRefs.length,
+                references: grokRefs,
+                directApiKey: grokDirectApiKey,
+            })
+            : null;
+        const generateOne = async () => {
+            if (activeProvider === "gemini-api") {
+                const r = await generateViaGeminiApi(generationPrompt, requireRuntimeContext(ctx), {
+                    model: imageModel,
+                    size: effectiveSize,
+                    signal: cancelController.signal,
+                    requestId,
+                    references: refCheck.refDetails,
+                });
+                throwIfJobCanceled(requestId);
+                return r;
+            }
+            if (activeProvider === "agy") {
+                const r = await generateViaAgy(generationPrompt, {
+                    references: refCheck.refDetails,
+                    signal: cancelController.signal,
+                    requestId,
+                });
+                throwIfJobCanceled(requestId);
+                return r;
+            }
+            if (activeProvider === "grok" || activeProvider === "grok-api") {
+                const grokModel = quality === "high" ? "grok-imagine-image-quality" : imageModel;
+                const r = await generateViaGrok(generationPrompt, ctx, {
+                    model: grokModel,
+                    size: effectiveSize,
+                    signal: cancelController.signal,
+                    requestId,
+                    plannedPrompt: sharedGrokPlan?.prompt,
+                    webSearchCalls: sharedGrokPlan?.webSearchCalls,
+                    references: grokRefs,
+                    directApiKey: grokDirectApiKey,
+                });
+                throwIfJobCanceled(requestId);
+                return r;
+            }
+            const MAX_RETRIES = 1;
+            let lastErr;
+            for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+                try {
+                    const r = await generateViaResponses(activeProvider, generationPrompt, quality, effectiveSize, moderation, refCheck.refDetails || refCheck.refs, requestId, normalizedPromptMode, ctx, {
+                        model: imageModel,
+                        reasoningEffort,
+                        webSearchEnabled,
+                        signal: cancelController.signal,
+                        allowPromptOnlyOAuthFallback: activeProvider !== "api",
+                    });
+                    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",
+            });
+        };
+        const results = await Promise.allSettled(Array.from({ length: count }, generateOne));
+        throwIfJobCanceled(requestId);
+        const images = [];
+        let totalUsage = null;
+        let totalWebSearchCalls = 0;
+        let firstRetryMeta = null;
+        for (const r of results) {
+            if (r.status === "fulfilled" && r.value.b64) {
+                throwIfJobCanceled(requestId);
+                const valueWithMime = r.value;
+                const resultMime = activeProvider === "grok" || activeProvider === "agy" || activeProvider === "grok-api" || activeProvider === "gemini-api"
+                    ? (valueWithMime.mime || detectImageMimeFromB64(r.value.b64) || mime)
+                    : mime;
+                const resultFormat = activeProvider === "grok" || activeProvider === "agy" || activeProvider === "grok-api" || activeProvider === "gemini-api" ? imageFormatFromMime(resultMime) : effectiveFormat;
+                const retryValue = r.value;
+                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}.${resultFormat}`;
+                const createdAt = Date.now();
+                const valueWithProviderUrl = r.value;
+                const providerUrl = typeof valueWithProviderUrl.providerUrl === "string"
+                    ? valueWithProviderUrl.providerUrl
+                    : undefined;
+                const meta = {
+                    kind: "classic",
+                    requestId,
+                    sessionId,
+                    clientNodeId,
+                    prompt,
+                    userPrompt: prompt,
+                    revisedPrompt: r.value.revisedPrompt || null,
+                    promptMode: normalizedPromptMode,
+                    composerPrompt,
+                    composerInsertedPrompts,
+                    quality,
+                    size: effectiveSize,
+                    format: resultFormat,
+                    moderation,
+                    model: activeProvider === "grok" ? (quality === "high" ? "grok-imagine-image-quality" : imageModel) : imageModel,
+                    reasoningEffort,
+                    provider: activeProvider,
+                    createdAt,
+                    ...(providerUrl ? { providerUrl } : {}),
+                    usage: r.value.usage || null,
+                    webSearchCalls: r.value.webSearchCalls || 0,
+                    webSearchEnabled,
+                    refsCount: providerRefCount,
+                };
+                const rawBuffer = Buffer.from(r.value.b64, "base64");
+                const embedded = await embedImageMetadataBestEffort(rawBuffer, resultFormat, meta, {
+                    version: ctx.packageVersion,
+                });
+                if (!embedded.embedded) {
+                    logEvent("generate", "metadata_embed_skipped", { requestId, filename, code: embedded.code, warning: embedded.warning, });
+                }
+                const filePath = join(ctx.config.storage.generatedDir, filename);
+                await writeFile(filePath, embedded.buffer);
+                await safeWriteSidecar(filePath + ".json", meta);
+                generateImageThumbnailFromBuffer(embedded.buffer, filePath).catch(() => { });
+                invalidateHistoryIndex();
+                images.push({
+                    image: `data:${resultMime};base64,${r.value.b64}`,
+                    filename,
+                    revisedPrompt: r.value.revisedPrompt || null,
+                    ...(providerUrl ? { providerUrl } : {}),
+                    createdAt,
+                });
+                if (r.value.usage) {
+                    const usageValue = r.value.usage;
+                    if (!totalUsage)
+                        totalUsage = { ...usageValue };
+                    else {
+                        const tu = totalUsage;
+                        Object.keys(usageValue).forEach((k) => {
+                            if (typeof usageValue[k] === "number")
+                                tu[k] = (tu[k] || 0) + usageValue[k];
+                        });
+                    }
+                }
+                if (typeof r.value.webSearchCalls === "number") {
+                    totalWebSearchCalls = activeProvider === "grok" || activeProvider === "grok-api"
+                        ? Math.max(totalWebSearchCalls, r.value.webSearchCalls)
+                        : totalWebSearchCalls + r.value.webSearchCalls;
+                }
+            }
+            else if (r.status === "rejected") {
+                logError("generate", "parallel_failed", r.reason, { requestId });
+            }
+        }
+        if (images.length === 0) {
+            const firstErr = results.find((r) => r.status === "rejected")?.reason;
+            if (firstErr?.code) {
+                const status = firstErr.status || 500;
+                if (isGenerationCanceledError(firstErr)) {
+                    finishCanceled = true;
+                    return fail(firstErr.status, {
+                        error: firstErr.message,
+                        code: firstErr.code,
+                        requestId,
+                    });
+                }
+                return fail(status, {
+                    error: firstErr.message,
+                    code: firstErr.code,
+                    ...upstreamErrorFields(firstErr),
+                    requestId,
+                });
+            }
+            return fail(500, { error: "All generation attempts failed", code: "GENERATE_ALL_FAILED", requestId });
+        }
+        const elapsed = +((Date.now() - startTime) / 1000).toFixed(1);
+        // Patch elapsed into sidecars after the generation loop (best effort).
+        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 atomicWriteJson(sidecarPath, sidecarMeta);
+            }
+            catch {
+                /* best-effort elapsed patch */
+            }
+        }));
+        const firstRevised = images[0]?.revisedPrompt || null;
+        const extra = {
+            usage: totalUsage,
+            provider: activeProvider,
+            reasoningEffort,
+            webSearchCalls: totalWebSearchCalls,
+            quality,
+            size: effectiveSize,
+            moderation,
+            model: imageModel,
+            warnings: qualityWarnings,
+            revisedPrompt: firstRevised,
+            promptMode: normalizedPromptMode,
+            webSearchEnabled,
+            ...(firstRetryMeta || {}),
+        };
+        if (count === 1) {
+            finishHttpStatus = 200;
+            finishMeta = { filenames: [images[0].filename], imageCount: 1 };
+            logEvent("generate", "saved", { requestId, imageCount: 1, elapsedMs: Date.now() - startTime, filename: images[0].filename, });
+            succeed({
+                image: images[0].image,
+                elapsed,
+                filename: images[0].filename,
+                requestId,
+                providerUrl: images[0].providerUrl ?? null,
+                createdAt: images[0].createdAt,
+                ...extra,
+            });
+        }
+        else {
+            finishHttpStatus = 200;
+            finishMeta = { filenames: images.map((image) => image.filename), imageCount: images.length };
+            logEvent("generate", "saved", { requestId, imageCount: images.length, elapsedMs: Date.now() - startTime, });
+            succeed({ images, elapsed, count: images.length, requestId, ...extra });
+        }
+    }
+    catch (e) {
+        const err = errInfo(e);
+        const ext = (err.raw && typeof err.raw === "object" ? err.raw : {});
+        const fallbackCode = err.code || classifyUpstreamError(err.message);
+        if (isGenerationCanceledError(err.raw) || isJobCanceled(requestId)) {
+            const canceled = makeGenerationCanceledError();
+            finishCanceled = true;
+            return fail(canceled.status, {
+                error: canceled.message,
+                code: canceled.code,
+                requestId,
+            });
+        }
+        finishErrorCode = fallbackCode || "GENERATE_FAILED";
+        logError("generate", "error", err.raw, { requestId, code: finishErrorCode });
+        fail(err.status || 500, {
+            error: err.message,
+            code: finishErrorCode,
+            ...upstreamErrorFields(ext),
+            requestId,
+        });
+    }
+    finally {
+        if (jobOwned)
+            finishJob(requestId, {
+                canceled: finishCanceled,
+                status: finishStatus,
+                httpStatus: finishHttpStatus,
+                errorCode: finishErrorCode,
+                meta: finishMeta,
+            });
+        appendGenerationRequestLog(ctx.config.storage.generationRequestLogFile, {
+            id: randomBytes(8).toString("hex"),
+            requestId,
+            createdAt: Date.now(),
+            prompt: typeof req.body?.prompt === "string" ? req.body.prompt : "",
+            requested: parseInt(req.body?.n) || 1,
+            succeeded: finishStatus === "completed" ? (finishMeta.imageCount ?? 1) : 0,
+            error: finishStatus === "error" ? (finishErrorCode ?? "unknown") : null,
+        }).catch(() => { });
+    }
+}

package/lib/generationInputValidation.js

@@ -0,0 +1,32 @@
+import { normalizeRequestId } from "./requestLogger.js";
+export const MAX_GENERATION_PROMPT_CHARS = 32_000;
+export function normalizeBodyRequestId(bodyRequestId, fallbackRequestId) {
+    return normalizeRequestId(bodyRequestId === undefined ? fallbackRequestId : bodyRequestId);
+}
+export function validateGenerationPrompt(prompt) {
+    if (typeof prompt !== "string" || prompt.length === 0) {
+        return { error: { code: "INVALID_PROMPT", message: "Prompt must be a non-empty string" } };
+    }
+    if (prompt.length > MAX_GENERATION_PROMPT_CHARS) {
+        return {
+            error: {
+                code: "PROMPT_TOO_LONG",
+                message: `Prompt must not exceed ${MAX_GENERATION_PROMPT_CHARS} characters`,
+            },
+        };
+    }
+    return null;
+}
+export function validateBoundedCount(value, fallback, maximum, field) {
+    const candidate = value === undefined ? fallback : value;
+    const parsed = typeof candidate === "number" ? candidate : Number(candidate);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > maximum) {
+        return {
+            error: {
+                code: "INVALID_COUNT",
+                message: `${field} must be an integer between 1 and ${maximum}`,
+            },
+        };
+    }
+    return { value: parsed };
+}

package/lib/grokImageCore.js

@@ -88,7 +88,24 @@ export async function downloadGrokImageUrl(url, signal, timeoutMs = 30_000) {
         if (contentLength > MAX_IMAGE_DOWNLOAD_BYTES) {
             throw grokError("Image download exceeds 50MB limit", 502, "GROK_IMAGE_DOWNLOAD_FAILED");
         }
-        const buffer = Buffer.from(await res.arrayBuffer());
+        if (!res.body)
+            throw grokError("Image download had no response body", 502, "GROK_IMAGE_DOWNLOAD_FAILED");
+        const chunks = [];
+        let total = 0;
+        const reader = res.body.getReader();
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > MAX_IMAGE_DOWNLOAD_BYTES) {
+                await reader.cancel("download size limit exceeded").catch(() => { });
+                controller.abort();
+                throw grokError("Image download exceeds 50MB limit", 502, "GROK_IMAGE_DOWNLOAD_FAILED");
+            }
+            chunks.push(Buffer.from(value));
+        }
+        const buffer = Buffer.concat(chunks, total);
         clearTimeout(timer);
         if (buffer.length === 0)
             throw grokError("Image download was empty", 502, "GROK_IMAGE_DOWNLOAD_FAILED");

package/lib/historyIndex.js

@@ -3,6 +3,7 @@ import { listHistoryRows } from "./historyList.js";
 const HISTORY_INDEX_TTL_MS = 3000;
 let snapshot = null;
 let pending = null;
+let generation = 0;
 function isFreshIndex(current, baseDir) {
     return Boolean(current &&
         current.baseDir === baseDir &&
@@ -13,17 +14,23 @@ export async function getHistoryIndex(baseDir = config.storage.generatedDir) {
         return snapshot;
     if (pending)
         return pending;
-    pending = (async () => {
+    const scanGeneration = generation;
+    const scan = (async () => {
         const rows = await listHistoryRows(baseDir);
         const next = { baseDir, builtAt: Date.now(), rows };
-        snapshot = next;
+        if (scanGeneration === generation)
+            snapshot = next;
         return next;
-    })().finally(() => {
-        pending = null;
+    })();
+    const tracked = scan.finally(() => {
+        if (pending === tracked)
+            pending = null;
     });
+    pending = tracked;
     return pending;
 }
 export function invalidateHistoryIndex() {
+    generation += 1;
     snapshot = null;
     pending = null;
 }

package/lib/historyList.js

@@ -79,6 +79,9 @@ export async function listHistoryRows(baseDir = config.storage.generatedDir) {
             canvasSourceFilename: meta?.canvasSourceFilename || null,
             canvasEditableFilename: meta?.canvasEditableFilename || null,
             canvasMergedAt: Number.isFinite(meta?.canvasMergedAt) ? meta.canvasMergedAt : null,
+            annotationsBaked: Boolean(meta?.annotationsBaked),
+            annotationSnapshot: meta?.annotationSnapshot ?? null,
+            annotationOnly: Boolean(meta?.annotationOnly),
             setId: meta?.setId || null,
             cardId: meta?.cardId || null,
             cardOrder: Number.isFinite(meta?.cardOrder) ? meta.cardOrder : null,

package/lib/imageMetadata.js

@@ -38,6 +38,9 @@ export function buildIma2MetadataPayload(meta = {}, context = {}) {
         canvasSourceFilename: stringOrNull(meta.canvasSourceFilename, 240),
         canvasEditableFilename: stringOrNull(meta.canvasEditableFilename, 240),
         canvasMergedAt: numberOrNull(meta.canvasMergedAt),
+        annotationsBaked: Boolean(meta.annotationsBaked),
+        annotationSnapshot: isPlainObject(meta.annotationSnapshot) ? meta.annotationSnapshot : null,
+        annotationOnly: Boolean(meta.annotationOnly),
         prompt: stringOrNull(meta.prompt),
         userPrompt: stringOrNull(meta.userPrompt) || stringOrNull(meta.prompt),
         revisedPrompt: stringOrNull(meta.revisedPrompt),