ima2-gen 2.0.1 → 2.0.3

package/lib/agentToolManifest.js

@@ -0,0 +1,90 @@
+import { AGENT_ALLOWED_TOOLS } from "./agentTypes.js";
+// Single source of truth for the agent tool surface. Consumed by the LLM
+// planner developer prompt, /api/agent/tools, and capabilities.agentMode.
+export const AGENT_TOOL_MANIFEST = [
+    {
+        name: "ima2.get_image_context",
+        description: "Load the session image context manifest (previous images, current image, locks). Runs automatically before image generation.",
+        parameters: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "ima2.web_search",
+        description: "Search the web for factual visual references before generating. Only available when web search is enabled for the session.",
+        parameters: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Search query for factual visual accuracy." },
+            },
+            required: ["query"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "ima2.generate_image",
+        description: "Generate one or more images. Supports fanout: provide one prompt per variant.",
+        parameters: {
+            type: "object",
+            properties: {
+                prompts: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "One generation prompt per planned variant (1 to the configured image limit).",
+                },
+                plannedVariants: { type: "integer", minimum: 1, description: "Number of images to generate." },
+                plannedParallelism: { type: "integer", minimum: 1, description: "Concurrent generation calls." },
+                sourceImagePolicy: {
+                    type: "string",
+                    enum: ["auto", "none", "current"],
+                    description: "none creates a fresh image and ignores the current session image; current uses the current session image as edit/reference input; auto lets the runtime choose.",
+                },
+            },
+            required: ["prompts"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "ima2.generate_video",
+        description: "Generate a single video with Grok Imagine. If the session has a last image, it is used as the image-to-video source automatically.",
+        parameters: {
+            type: "object",
+            properties: {
+                prompt: { type: "string", description: "Video prompt describing visual flow and motion." },
+                duration: { type: "integer", minimum: 1, maximum: 15, description: "Video duration in seconds. Default 5." },
+                resolution: { type: "string", enum: ["480p", "720p"], description: "Output resolution. Default 480p." },
+                aspectRatio: {
+                    type: "string",
+                    enum: ["auto", "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3"],
+                    description: "Output aspect ratio. Default auto.",
+                },
+            },
+            required: ["prompt"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "ima2.get_generation_errors",
+        description: "Read-only lookup of the session's recent generation failures (failed queue jobs and error turns). Use when the user asks why a generation failed.",
+        parameters: {
+            type: "object",
+            properties: {
+                limit: { type: "integer", minimum: 1, maximum: 20, description: "Maximum error records to return. Default 10." },
+            },
+            additionalProperties: false,
+        },
+    },
+];
+const MANIFEST_NAMES = new Set(AGENT_TOOL_MANIFEST.map((entry) => entry.name));
+for (const tool of AGENT_ALLOWED_TOOLS) {
+    if (!MANIFEST_NAMES.has(tool)) {
+        throw new Error(`Agent tool manifest is missing an entry for: ${tool}`);
+    }
+}
+export function formatToolManifestForPrompt() {
+    return AGENT_TOOL_MANIFEST
+        .map((entry) => `- ${entry.name}: ${entry.description}\n  parameters: ${JSON.stringify(entry.parameters)}`)
+        .join("\n");
+}

package/lib/agentTypes.js

@@ -3,4 +3,5 @@ export const AGENT_ALLOWED_TOOLS = [
     "ima2.web_search",
     "ima2.generate_image",
     "ima2.generate_video",
+    "ima2.get_generation_errors",
 ];

package/lib/agyCli.js

@@ -0,0 +1,31 @@
+import { existsSync } from "node:fs";
+import { delimiter, dirname, join } from "node:path";
+import { homedir } from "node:os";
+export function agyCommandName(platform = process.platform) {
+    return platform === "win32" ? "agy.cmd" : "agy";
+}
+export function agyLocalBinCandidates(home = homedir(), platform = process.platform) {
+    const command = agyCommandName(platform);
+    return [
+        join(home, ".local", "bin", command),
+        join(home, ".npm-global", "bin", command),
+    ];
+}
+export function resolveAgyBin(env = process.env, home = homedir(), platform = process.platform) {
+    if (env.IMA2_AGY_BIN) {
+        if (!existsSync(env.IMA2_AGY_BIN)) {
+            console.warn(`[ima2-agy] IMA2_AGY_BIN is set to "${env.IMA2_AGY_BIN}" but the file does not exist. Falling back to PATH lookup.`);
+        }
+        else {
+            return env.IMA2_AGY_BIN;
+        }
+    }
+    return agyLocalBinCandidates(home, platform).find((candidate) => existsSync(candidate))
+        ?? agyCommandName(platform);
+}
+export function buildAgyPathEnv(env = process.env, agyBin = resolveAgyBin(env)) {
+    const basePath = env.PATH || "";
+    if (agyBin === agyCommandName() || agyBin === "agy")
+        return basePath;
+    return `${dirname(agyBin)}${delimiter}${basePath}`;
+}

package/lib/agyImageAdapter.js

@@ -1,9 +1,11 @@
 import { spawn } from "node:child_process";
-import { readFile, rm, stat, writeFile, mkdir } from "node:fs/promises";
-import { extname, join, resolve } from "node:path";
+import { readFile, readdir, rm, stat, writeFile, mkdir } from "node:fs/promises";
+import { extname, dirname, join, resolve } from "node:path";
 import { homedir, tmpdir } from "node:os";
 import { randomBytes } from "node:crypto";
+import { buildAgyPathEnv, resolveAgyBin } from "./agyCli.js";
 import { logEvent } from "./logger.js";
+import { SAFETY_INTENT_POLICY } from "./promptSafetyPolicy.js";
 import { detectImageMimeFromB64 } from "./refs.js";
 const AGY_TIMEOUT_MS = 360_000;
 const AGY_OUTPUT_RESOLUTION = "1024x1024";
@@ -19,7 +21,10 @@ function buildAgyPrompt(userPrompt, referencePaths) {
         ? JSON.stringify(referencePaths)
         : "[]";
     return [
-        "Please generate one image by calling the tool default_api:generate_image once.",
+        "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:",
@@ -30,17 +35,27 @@ function buildAgyPrompt(userPrompt, referencePaths) {
         '  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");
 }
 function parseAgyOutput(stdout) {
-    const lines = stdout.trim().split("\n").filter((l) => l.trim().length > 0);
+    const lines = stdout.replace(/\r/g, "").trim().split("\n").filter((l) => l.trim().length > 0);
     const resultLine = lines.find((l) => l.startsWith("RESULT|"));
     if (resultLine) {
         const parts = resultLine.split("|");
         if (parts.length >= 3) {
-            return { artifactPath: parts[1], ext: parts[2] };
+            return { artifactPath: parts[1].trim(), ext: parts[2].trim() };
         }
         throw agyError(`Malformed RESULT line: ${resultLine}`, 502, "AGY_MALFORMED_RESULT");
     }
@@ -63,21 +78,57 @@ function parseAgyOutput(stdout) {
         const ext = p.split(".").pop() || "png";
         return { artifactPath: p, ext };
     }
-    const normalizedStdout = stdout.replace(/\\/g, "/");
-    const pathMatch = normalizedStdout.match(/\/[^\s"']+\/(brain|artifacts)\/[^\s"']+\.(png|jpg|jpeg|webp)/i);
+    const normalizedStdout = stdout.replace(/\r/g, "").replace(/\\/g, "/");
+    const pathMatch = normalizedStdout.match(/(?:[A-Za-z]:)?\/[^\s"']+\/(brain|artifacts|\.gemini)\/[^\s"']+\.(png|jpg|jpeg|webp)/i);
     if (pathMatch) {
-        const artifactPath = process.platform === "win32" ? pathMatch[0].replace(/\//g, "\\") : pathMatch[0];
+        const matched = pathMatch[0];
+        const artifactPath = process.platform === "win32" ? matched.replace(/\//g, "\\") : matched;
         const ext = extname(artifactPath).slice(1) || "png";
         return { artifactPath, ext };
     }
     throw agyError(`Could not parse artifact path from agy output (${stdout.length} chars): ${stdout.slice(0, 200)}`, 502, "AGY_PARSE_FAILED");
 }
+export async function findRecentAgyArtifact(sinceMs, rootOverrides) {
+    const roots = rootOverrides ?? [
+        join(homedir(), ".gemini", "antigravity-cli", "brain"),
+        join(homedir(), ".gemini"),
+    ];
+    const candidates = [];
+    const seen = new Set();
+    async function walk(dir, depth) {
+        if (depth > 5 || seen.has(dir))
+            return;
+        seen.add(dir);
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            const p = join(dir, entry.name);
+            if (!entry.isSymbolicLink() && entry.isDirectory()) {
+                await walk(p, depth + 1);
+                continue;
+            }
+            if (!/^ima2_generated.*\.(png|jpg|jpeg|webp)$/i.test(entry.name)) {
+                continue;
+            }
+            const s = await stat(p).catch(() => null);
+            if (!s)
+                continue;
+            if (s.mtimeMs >= sinceMs - 5_000) {
+                candidates.push({ path: p, mtimeMs: s.mtimeMs });
+            }
+        }
+    }
+    for (const root of roots) {
+        await walk(root, 0);
+    }
+    candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return candidates[0]?.path ?? null;
+}
 function spawnAgy(prompt, signal) {
     return new Promise((resolve, reject) => {
-        const child = spawn("agy", ["-p", "-"], {
+        const child = spawn(resolveAgyBin(), ["-p", "-"], {
             stdio: ["pipe", "pipe", "pipe"],
             env: {
-                PATH: process.env.PATH,
+                PATH: buildAgyPathEnv(),
                 HOME: process.env.HOME,
                 USERPROFILE: process.env.USERPROFILE,
                 TMPDIR: process.env.TMPDIR,
@@ -105,7 +156,11 @@ function spawnAgy(prompt, signal) {
                 return;
             settled = true;
             clearTimeout(timer);
-            reject(agyError(`Agy process error: ${err.message}`, 502, "AGY_PROCESS_ERROR"));
+            const bin = resolveAgyBin();
+            const hint = err.code === "ENOENT"
+                ? `. "${bin}" was not found — install agy or set IMA2_AGY_BIN=/absolute/path/to/agy`
+                : "";
+            reject(agyError(`Agy process error: ${err.message}${hint}`, 502, "AGY_PROCESS_ERROR"));
         });
         child.on("close", (code) => {
             if (settled)
@@ -167,6 +222,17 @@ async function writeRefsToTempFiles(refs) {
         },
     };
 }
+async function cleanupAgyArtifact(artifactPath) {
+    try {
+        await rm(artifactPath, { force: true }).catch(() => { });
+        const dir = dirname(artifactPath);
+        const entries = await readdir(dir).catch(() => null);
+        if (entries && entries.length === 0) {
+            await rm(dir, { recursive: true, force: true }).catch(() => { });
+        }
+    }
+    catch { /* best-effort */ }
+}
 export async function generateViaAgy(prompt, options = {}) {
     const refDetails = (options.references || []).slice(0, 3);
     const { paths: refPaths, cleanup } = await writeRefsToTempFiles(refDetails);
@@ -178,6 +244,7 @@ export async function generateViaAgy(prompt, options = {}) {
         refs: refPaths.length,
     });
     try {
+        const generationStartedAtMs = Date.now();
         const { stdout, stderr } = await spawnAgy(agyPrompt, options.signal);
         if (stderr && stderr.trim().length > 0) {
             logEvent("agy", "generate:stderr", {
@@ -186,7 +253,27 @@ export async function generateViaAgy(prompt, options = {}) {
                 stderrPreview: stderr.slice(0, 200),
             });
         }
-        const { artifactPath } = parseAgyOutput(stdout);
+        const agyCombinedOutput = [stdout, stderr].filter(Boolean).join("\n");
+        let artifactPath;
+        try {
+            artifactPath = 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: options.requestId,
+                artifactPath: fallbackPath,
+                stdoutChars: stdout.length,
+                stderrChars: stderr.length,
+            });
+            artifactPath = fallbackPath;
+        }
         // Validate artifact path is within allowed directories
         const resolvedPath = resolve(artifactPath);
         const allowedPrefixes = [
@@ -218,6 +305,7 @@ export async function generateViaAgy(prompt, options = {}) {
             mime,
             fileBytes: buffer.length,
         });
+        await cleanupAgyArtifact(resolvedPath);
         return {
             b64,
             revisedPrompt: prompt,
@@ -226,6 +314,10 @@ export async function generateViaAgy(prompt, options = {}) {
             mime,
         };
     }
+    catch (err) {
+        logEvent("agy", "generate:failed_cleanup", { requestId: options.requestId });
+        throw err;
+    }
     finally {
         await cleanup();
     }

package/lib/capabilities.js

@@ -1,7 +1,8 @@
 import { config as runtimeConfigDefault } from "../config.js";
+import { AGENT_ALLOWED_TOOLS } from "./agentTypes.js";
+import { AGENT_TOOL_MANIFEST } from "./agentToolManifest.js";
 import { KEY_TO_ENV, WRITABLE_CONFIG_KEYS } from "./configKeys.js";
 import { DEFAULT_IMAGE_QUALITY, VALID_IMAGE_QUALITIES } from "./oauthNormalize.js";
-const MAX_GENERATED_IMAGES = 8;
 const VALID_MODES = ["auto", "direct"];
 const VALID_PROVIDERS = ["auto", "oauth", "api", "grok", "grok-api", "agy", "gemini-api"];
 const AGENT_COMMANDS = [
@@ -79,11 +80,11 @@ export function buildIma2Capabilities({ appConfig = runtimeConfigDefault, packag
         },
         limits: {
             maxRefCount: appConfig.limits.maxRefCount,
-            maxGeneratedImages: MAX_GENERATED_IMAGES,
+            maxGeneratedImages: appConfig.limits.maxGeneratedImages,
             maxParallel: {
                 value: appConfig.limits.maxParallel,
-                enforced: false,
-                note: "advisory client-side queue guidance only; server-side semaphore is not enforced",
+                enforced: true,
+                note: "server-side inflight capacity guard uses this runtime limit",
             },
         },
         promptBuilder: {
@@ -96,7 +97,8 @@ export function buildIma2Capabilities({ appConfig = runtimeConfigDefault, packag
         agentMode: {
             available: true,
             route: "/api/agent/sessions",
-            allowedTools: ["ima2.get_image_context", "ima2.web_search", "ima2.generate_image"],
+            allowedTools: [...AGENT_ALLOWED_TOOLS],
+            toolManifest: [...AGENT_TOOL_MANIFEST],
             finalArtifact: "image",
             uiOnly: true,
             cliCommand: null,

package/lib/configKeys.js

@@ -10,6 +10,8 @@ export const WRITABLE_CONFIG_KEYS = new Set([
     "cardNewsPlanner.model",
     "cardNewsPlanner.timeoutMs",
     "cardNewsPlanner.deterministicFallback",
+    "agentPlanner.enabled",
+    "agentPlanner.timeoutMs",
     "grokProvider.plannerModel",
     "grokProvider.plannerTimeoutMs",
     "grokProvider.defaultImageModel",
@@ -25,6 +27,7 @@ export const WRITABLE_CONFIG_KEYS = new Set([
     "oauth.statusTimeoutMs",
     "oauth.restartDelayMs",
     "limits.maxRefCount",
+    "limits.maxGeneratedImages",
     "limits.maxParallel",
     "history.defaultPageSize",
     "history.maxPageCap",
@@ -44,9 +47,12 @@ export const KEY_TO_ENV = {
     "cardNewsPlanner.enabled": "IMA2_CARD_NEWS_PLANNER",
     "cardNewsPlanner.model": "IMA2_CARD_NEWS_PLANNER_MODEL",
     "cardNewsPlanner.timeoutMs": "IMA2_CARD_NEWS_PLANNER_TIMEOUT_MS",
+    "agentPlanner.enabled": "IMA2_AGENT_PLANNER_ENABLED",
+    "agentPlanner.timeoutMs": "IMA2_AGENT_PLANNER_TIMEOUT_MS",
     "grokProvider.plannerModel": "IMA2_GROK_PLANNER_MODEL",
     "grokProvider.plannerTimeoutMs": "IMA2_GROK_PLANNER_TIMEOUT_MS",
     "grokProvider.defaultImageModel": "IMA2_GROK_IMAGE_MODEL_DEFAULT",
+    "limits.maxGeneratedImages": "IMA2_MAX_GENERATED_IMAGES",
     "limits.maxParallel": "IMA2_MAX_PARALLEL",
     "limits.maxRefCount": "IMA2_MAX_REF_COUNT",
     "history.defaultPageSize": "IMA2_HISTORY_PAGE_SIZE",

package/lib/errorClassify.js

@@ -29,13 +29,14 @@ export function classifyUpstreamErrorCode(code) {
         return "MODERATION_REFUSED";
     return "UNKNOWN";
 }
-/**
- * Classify an upstream error message into an ImaErrorCode.
- * Order matters: auth session expiry must beat generic "token" matches,
- * and moderation must beat generic 5xx.
- * @param {string | undefined | null} msg
- * @returns {ImaErrorCode}
- */
+export function classifyModerationStage(msg) {
+    const s = String(msg || "").toLowerCase();
+    if (s.includes("request was rejected") || s.includes("prompt was rejected"))
+        return "input";
+    if (s.includes("image was filtered") || s.includes("generated image"))
+        return "output";
+    return "unknown";
+}
 export function classifyUpstreamError(msg) {
     const s = String(msg || "").toLowerCase();
     if (!s)

package/lib/eventBus.js

@@ -0,0 +1,71 @@
+import { EventEmitter } from "node:events";
+/** Global replay window — sized for 7+ concurrent jobs (~15 events each) with reconnect headroom. */
+export const RING_SIZE = 2000;
+/** Align with /api/events connection cap — avoids MaxListenersExceededWarning under load. */
+export const MAX_SSE_LISTENERS = 512;
+const bus = new EventEmitter();
+bus.setMaxListeners(MAX_SSE_LISTENERS);
+let seq = 0;
+const ring = [];
+function omitLargeImageFields(data) {
+    let omitted = false;
+    const next = { ...data };
+    if (typeof next.image === "string" && next.image.length > 1000) {
+        delete next.image;
+        omitted = true;
+    }
+    if (Array.isArray(next.images)) {
+        const images = next.images.map((item) => {
+            if (!item || typeof item !== "object" || Array.isArray(item))
+                return item;
+            const imageItem = item;
+            if (typeof imageItem.image !== "string" || imageItem.image.length <= 1000)
+                return item;
+            const { image: _omit, ...rest } = imageItem;
+            omitted = true;
+            return { ...rest, _imageOmitted: true };
+        });
+        if (omitted)
+            next.images = images;
+    }
+    if (omitted)
+        next._imageOmitted = true;
+    return { data: omitted ? next : data, omitted };
+}
+function toRingEntry(entry) {
+    // Keep terminal/partial metadata replayable; omit multi-MB base64 from the ring.
+    const stripped = omitLargeImageFields(entry.data);
+    return stripped.omitted ? { ...entry, data: stripped.data } : entry;
+}
+export function publish(jobId, event, data) {
+    seq++;
+    const entry = { id: seq, jobId, event, data };
+    const ringEntry = toRingEntry(entry);
+    ring.push(ringEntry);
+    if (ring.length > RING_SIZE)
+        ring.shift();
+    bus.emit("event", entry);
+}
+export function subscribe(listener) {
+    bus.on("event", listener);
+    return () => bus.off("event", listener);
+}
+export function replayOldestId() {
+    return ring.length > 0 ? ring[0].id : null;
+}
+/** True when the ring has evicted events the client still expects from Last-Event-ID. */
+export function hasReplayGap(lastEventId) {
+    if (lastEventId <= 0 || ring.length === 0)
+        return false;
+    const oldest = ring[0].id;
+    return lastEventId < oldest - 1;
+}
+export function replaySince(lastEventId) {
+    const idx = ring.findIndex(e => e.id > lastEventId);
+    return idx === -1 ? [] : ring.slice(idx);
+}
+export function _resetForTest() {
+    seq = 0;
+    ring.length = 0;
+    bus.removeAllListeners();
+}

package/lib/geminiApiImageAdapter.js

@@ -8,30 +8,30 @@ const MODEL_ID_MAP = {
 const GEMINI_TIMEOUT_MS = 120_000;
 function parseGeminiImageParams(size) {
     if (!size || size === "auto" || size === "1024x1024")
-        return { aspectRatio: 1, imageSize: 0 };
+        return { aspectRatio: "1:1", imageSize: "1K" };
     const match = size.match(/^(\d+)x(\d+)$/);
     if (!match)
-        return { aspectRatio: 1, imageSize: 0 };
+        return { aspectRatio: "1:1", imageSize: "1K" };
     const w = Number(match[1]);
     const h = Number(match[2]);
     const ratio = w / h;
     const ratioMap = [
-        [1, 1], [2, 2 / 3], [3, 3 / 2], [4, 3 / 4], [5, 4 / 3],
-        [6, 4 / 5], [7, 5 / 4], [8, 9 / 16], [9, 16 / 9], [10, 21 / 9],
-        [11, 1 / 8], [12, 8], [13, 1 / 4], [14, 4],
+        ["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 bestEnum = 1;
+    let bestLabel = "1:1";
     let bestDist = Infinity;
-    for (const [enumVal, val] of ratioMap) {
+    for (const [label, val] of ratioMap) {
         const dist = Math.abs(ratio - val);
         if (dist < bestDist) {
             bestDist = dist;
-            bestEnum = enumVal;
+            bestLabel = label;
         }
     }
     const maxDim = Math.max(w, h);
-    const imageSize = maxDim <= 512 ? 1 : maxDim <= 1024 ? 2 : maxDim <= 2048 ? 3 : 4;
-    return { aspectRatio: bestEnum, imageSize };
+    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);
@@ -81,20 +81,23 @@ export async function generateViaGeminiApi(prompt, ctx, options = {}) {
         url = `https://generativelanguage.googleapis.com/v1beta/models/${apiModelId}:generateContent`;
         authHeaders = { "Content-Type": "application/json", "x-goog-api-key": apiKey };
     }
-    const imageParams = parseGeminiImageParams(options.size);
-    // NOTE: Vertex (aiplatform.googleapis.com) rejects the response_format field that the
-    // direct Gemini API accepts, so the Vertex path can only request modalities — output
-    // defaults to 1K/1:1 regardless of requested size. Direct API path honors aspect/size.
+    // 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"] }
+        ? {
+            responseModalities: ["TEXT", "IMAGE"],
+            ...(imageParams
+                ? { imageConfig: { aspectRatio: imageParams.aspectRatio, imageSize: imageParams.imageSize } }
+                : {}),
+        }
         : {
             response_modalities: ["TEXT", "IMAGE"],
-            response_format: {
-                image: {
-                    aspect_ratio: imageParams.aspectRatio,
-                    image_size: imageParams.imageSize,
-                },
-            },
+            ...(imageParams
+                ? { response_format: { image: { aspect_ratio: imageParams.aspectRatio, image_size: imageParams.imageSize } } }
+                : {}),
         };
     const configKey = useVertex ? "generationConfig" : "generation_config";
     const body = { contents: buildContents(prompt, references), [configKey]: generationConfig };

package/lib/generationErrors.js

@@ -1,4 +1,4 @@
-import { classifyUpstreamError, classifyUpstreamErrorCode } from "./errorClassify.js";
+import { classifyUpstreamError, classifyUpstreamErrorCode, classifyModerationStage } from "./errorClassify.js";
 import { safeDiagnosticLabel } from "./responsesParse.js";
 import { RESPONSE_DIAGNOSTIC_CODES } from "./responsesErrors.js";
 const PASSTHROUGH_CODES = new Set([
@@ -192,9 +192,11 @@ export function normalizeGenerationFailure(lastErr, options = {}) {
         return err;
     }
     if (SAFETY_CODES.has(code)) {
+        const stage = classifyModerationStage(lastErr?.message);
         const err = new Error(options.safetyMessage || lastErr?.message || "Content generation refused after retries");
         err.code = "SAFETY_REFUSAL";
         err.status = 422;
+        err.moderationStage = stage;
         err.cause = lastErr;
         return err;
     }

package/lib/generationRequestLog.js

@@ -0,0 +1,25 @@
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { atomicWriteJson } from "./atomicWrite.js";
+const MAX_ENTRIES = 200;
+let writeQueue = Promise.resolve();
+async function readEntries(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        return Array.isArray(parsed) ? parsed.slice(0, MAX_ENTRIES) : [];
+    }
+    catch {
+        return [];
+    }
+}
+export async function listGenerationRequestLog(path) {
+    return readEntries(path);
+}
+export function appendGenerationRequestLog(path, entry) {
+    writeQueue = writeQueue.catch(() => undefined).then(async () => {
+        await mkdir(dirname(path), { recursive: true });
+        const entries = await readEntries(path);
+        await atomicWriteJson(path, [entry, ...entries].slice(0, MAX_ENTRIES));
+    });
+    return writeQueue;
+}