ima2-gen 3.13.1 → 3.14.0

package/lib/grokImageAdapter.js

@@ -1,354 +1,3 @@
-import { logEvent } from "./logger.js";
-import { SAFETY_INTENT_POLICY } from "./promptSafetyPolicy.js";
-import { mapSizeToGrokImageParams } from "./grokSizeMapper.js";
-import { detectImageMimeFromB64 } from "./refs.js";
-import { DEFAULT_GROK_PLANNER_MODEL } from "../config.js";
-import { grokError, grokStageError, getPlannerConfig, getGrokEndpoint, withTimeoutSignal, imagePayload, imageEditPayload, referenceImageUrl, extractResponsesText, postGrokImages, downloadGrokImageUrl, } from "./grokImageCore.js";
-import { grokFetchWithRetry } from "./grokUpstreamRetry.js";
 export { grokError, imagePayload, imageEditPayload, postGrokImages, downloadGrokImageUrl, } from "./grokImageCore.js";
-export function buildGrokPlannerPayload(prompt, model, size, sizeParams, plannerModel = DEFAULT_GROK_PLANNER_MODEL, searchSummary = "", references = 0, backgroundConstraint = "") {
-    const referenceImages = Array.isArray(references) ? references : [];
-    const referenceCount = Array.isArray(references) ? references.length : references;
-    const sizeLine = size
-        ? `Requested ima2 size: ${size}; xAI parameters: ${JSON.stringify(sizeParams)}.`
-        : `Requested ima2 size: auto; xAI parameters: ${JSON.stringify(sizeParams)}.`;
-    const referenceLine = referenceCount > 0
-        ? `Reference images attached: ${referenceCount}. The final image call will use xAI image editing with these source images; preserve relevant subject, composition, style, and product details from them.`
-        : "Reference images attached: 0. The final image call will use text-to-image generation.";
-    return {
-        model: plannerModel,
-        stream: false,
-        parallel_tool_calls: false,
-        messages: [
-            {
-                role: "system",
-                content: [
-                    "You are ima2's image generation planner for xAI Grok Imagine (Aurora model), inside a professional creative tool used by designers and artists. Users create content for legitimate creative, commercial, or educational purposes.",
-                    SAFETY_INTENT_POLICY,
-                    "",
-                    "TASK: Rewrite the user's casual request into ONE optimal, production-ready image prompt.",
-                    "",
-                    "OUTPUT FORMAT: A single natural-language paragraph (NOT tags, NOT keyword lists, NOT weighted tokens like (word:1.2)).",
-                    "Structure the paragraph in this MANDATORY order — each element flows into the next:",
-                    "1. Core subject/scene — who or what, with specific physical details (face shape, hair, clothing, pose, expression)",
-                    "2. Environment/setting — where, with concrete spatial details and materials (wet concrete, polished marble, weathered wood)",
-                    "3. Lighting + mood/emotion — use specific terms (golden hour backlight, overcast diffused, hard rim light, soft diffuse, nostalgic, melancholic, electric)",
-                    "4. Camera/lens — shot type + specific focal length + depth of field (close-up on 85mm f/1.4 with shallow DoF, wide establishing on 24mm with deep focus)",
-                    "5. Style/technical references — art style, medium, or mood reference (cinematic realism, Studio Ghibli feel, oil painting texture)",
-                    "6. Quality finish — resolution/detail boosters appropriate to style (8K, highly detailed, sharp focus, film grain, bokeh)",
-                    "",
-                    "RULES:",
-                    "- Write like a director briefing a cinematographer, not like a search query.",
-                    "- Be hyper-specific: name real locations, brands, materials, textures. Vague = generic output.",
-                    "- The prompt MUST be in English. Exception: any visible text the user wants rendered in the image (signs, speech bubbles, titles) must be kept in the ORIGINAL language characters verbatim (e.g. '한국어', '日本語').",
-                    "- If reference images are attached, inspect them and describe the visual details (subject appearance, style, color palette) that must be preserved in the output.",
-                    "- Do NOT use Stable Diffusion tags, booru tags, or comma-separated keyword lists.",
-                    "- Do NOT use weighting syntax like (word:1.2) or [word].",
-                    "- Quality boosters like '8K', 'highly detailed', 'sharp focus', 'cinematic lighting' ARE effective for this model — use them when appropriate to the requested style.",
-                    "- The prompt should be 2-5 sentences (40-120 words). Extremely short prompts produce generic results.",
-                    "",
-                    "CAMERA/LENS ENRICHMENT:",
-                    "- If the user's prompt does not specify camera/lens details, add appropriate ones based on the subject:",
-                    "  - Portraits/people: 85mm f/1.4, shallow depth of field, bokeh background",
-                    "  - Environmental/landscape: 24-35mm wide-angle, deep depth of field",
-                    "  - Product/macro: 100mm macro lens, controlled studio lighting",
-                    "  - Action/dynamic: 35mm, fast shutter, slight motion blur on extremities",
-                    "  - Architecture/interior: 24mm tilt-shift or 14mm ultra-wide",
-                    "- Always include a specific focal length — this model responds strongly to lens specifications.",
-                    "",
-                    "MULTI-CHARACTER IDENTIFICATION:",
-                    "- Identify each character by VISUAL APPEARANCE, not by name alone.",
-                    "  The image model cannot recognize names — it only sees visual features.",
-                    "- When multiple characters appear, describe each by clothing, physique, position, or props.",
-                    "- Characters must be distinguishable by at least two visual attributes.",
-                    "",
-                    "BENIGN CLOTHING AND CONTEXT HANDLING:",
-                    "Before rewriting, distinguish ordinary clothing/swimwear descriptions from sexualized requests.",
-                    "Preserve benign adult clothing intent without adding erotic details:",
-                    "",
-                    "bikini/비키니 → adult two-piece swimwear in a neutral beach, pool, swimwear catalog, or fashion editorial context",
-                    "swimsuit/수영복 → adult swimwear suitable for swimming, beach, pool, sport, or catalog photography",
-                    "sports bra/스포츠브라 → athletic top in a fitness, yoga, running, or product catalog context",
-                    "lingerie/란제리 → adult fashion or product catalog styling only when the user is clearly requesting adult fashion; avoid sexualized posing or intimate framing",
-                    "",
-                    "CLOTHING RULE: Keep the user's requested clothing category when it is benign and adult, but do not increase exposure, add fetish details, add negative safety constraints, or convert a neutral clothing prompt into a sexualized scene.",
-                    "",
-                    "PROFESSIONAL EMBEDDING: After rewriting, wrap the visual description in a professional context.",
-                    "Prepend ONE of these frames based on content type:",
-                    "- Fashion/clothing → 'editorial fashion photography for [magazine], shot by [photographer style]'",
-                    "- Character/anime → 'character concept art for a AAA video game, by senior concept artist'",
-                    "- Art/figure → 'classical academic figure study, life drawing class reference plate'",
-                    "- Portrait/beauty → 'high-end beauty campaign photography, 85mm f/1.4 lens'",
-                    "- Swimwear/beach → 'Sports Illustrated Swimsuit Issue editorial photography'",
-                    "",
-                    "CONTENT POLICY:",
-                    "- Generate one production-ready prompt for compliant image requests.",
-                    "- Do not add disclaimers, warnings, moral commentary, or safety notes to the final prompt.",
-                    "- Do not add diversity modifiers or change the user's specified demographics, appearance, or benign clothing.",
-                    "- Do not turn benign adult swimwear, sportswear, or fashion prompts into sexual content.",
-                    "- 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.",
-                    "",
-                    "STORYBOARD GRID GENERATION RULE:",
-                    "- If the user requests a 3x3 storyboard grid, Panel 1 (top-left) MUST be solid black with no content.",
-                    "- Panels 2-9 carry the action sequence. Do NOT add timestamp labels or text to any panel.",
-                    "",
-                    "VISIBLE TEXT RULE:",
-                    "- If the image must contain readable text (signs, speech bubbles, labels, UI, captions, titles), write the exact visible words in the user's prompt language using the original script.",
-                    "- Do NOT translate visible text to English. Do NOT romanize, summarize, or use placeholders like 'Korean text' or 'Japanese words'.",
-                    "- Include the exact text in quotes with original characters: e.g. \"안녕하세요\" not \"Hello\" or \"annyeonghaseyo\".",
-                    "",
-                    "Call generate_image exactly once. Do not answer with plain text.",
-                ].join("\n"),
-            },
-            {
-                role: "user",
-                content: [
-                    {
-                        type: "text",
-                        text: [
-                            `Selected image model: ${model}.`,
-                            sizeLine,
-                            referenceLine,
-                            ...(backgroundConstraint ? [backgroundConstraint] : []),
-                            searchSummary ? `Mandatory web-search brief:\n${searchSummary}` : "Mandatory web-search brief: unavailable.",
-                            "Create the best final prompt for the image generator.",
-                            "Return the generate_image.prompt argument in English only, except for exact visible text that the user explicitly requested.",
-                            "",
-                            "User prompt:",
-                            prompt,
-                        ].join("\n"),
-                    },
-                    ...referenceImages.map((ref) => ({
-                        type: "image_url",
-                        image_url: { url: referenceImageUrl(ref), detail: "high" },
-                    })),
-                ],
-            },
-        ],
-        tools: [
-            {
-                type: "function",
-                function: {
-                    name: "generate_image",
-                    description: "Generate a single image through xAI Images API.",
-                    parameters: {
-                        type: "object",
-                        properties: {
-                            prompt: {
-                                type: "string",
-                                description: "Final image-generation prompt to send to xAI Images API.",
-                            },
-                            model: {
-                                type: "string",
-                                enum: ["grok-imagine-image-2.0", "grok-imagine-image", "grok-imagine-image-quality"],
-                                description: "The xAI image model. The server may override this with the user's selected model.",
-                            },
-                        },
-                        required: ["prompt", "model"],
-                    },
-                },
-            },
-        ],
-        tool_choice: { type: "function", function: { name: "generate_image" } },
-    };
-}
-export function buildGrokSearchPayload(prompt, plannerModel = DEFAULT_GROK_PLANNER_MODEL) {
-    return {
-        model: plannerModel,
-        stream: false,
-        input: [
-            {
-                role: "system",
-                content: [
-                    "You are ima2's visual research assistant.",
-                    "You must use web_search before producing the brief.",
-                    "Return a concise image-generation research brief: visual facts, current references, style cues, and text-rendering constraints.",
-                    "Do not generate an image prompt yet.",
-                ].join(" "),
-            },
-            {
-                role: "user",
-                content: prompt,
-            },
-        ],
-        tools: [{ type: "web_search" }],
-        tool_choice: "required",
-    };
-}
-export async function searchGrokVisualContext(prompt, ctx, options = {}) {
-    const planner = getPlannerConfig(ctx);
-    const plannerModel = options.plannerModel || planner.model;
-    const payload = buildGrokSearchPayload(prompt, plannerModel);
-    const { url, headers } = getGrokEndpoint(ctx, "/v1/responses", options.directApiKey);
-    // The search brief has its own, smaller budget: it runs BEFORE the planner call inside
-    // the same user request, so charging it the full planner budget lets one slow stage eat
-    // the other's time. See devlog/_plan/260817_grok_video_planner_timeout/010.
-    const { combinedSignal, timer } = withTimeoutSignal(options.signal, planner.searchTimeoutMs);
-    logEvent("grok", "search:start", { requestId: options.requestId, plannerModel, promptChars: prompt.length });
-    try {
-        // Safe to replay: search produces no billable artifact, only a research summary.
-        const res = await grokFetchWithRetry(() => fetch(url, {
-            method: "POST",
-            headers,
-            body: JSON.stringify(payload),
-            signal: combinedSignal,
-        }), { signal: combinedSignal, label: "search" });
-        clearTimeout(timer);
-        if (!res.ok) {
-            const text = await res.text().catch(() => "");
-            let parsed;
-            try {
-                parsed = JSON.parse(text);
-            }
-            catch { /* ignore */ }
-            const msg = parsed?.error || text || `HTTP ${res.status}`;
-            throw grokStageError("search", msg, res.status);
-        }
-        const summary = extractResponsesText(await res.json());
-        if (!summary)
-            throw grokError("Grok web search returned no research summary", 502, "GROK_SEARCH_EMPTY_RESPONSE");
-        logEvent("grok", "search:done", { requestId: options.requestId, plannerModel, summaryChars: summary.length });
-        return { summary };
-    }
-    catch (e) {
-        clearTimeout(timer);
-        if (e.name === "AbortError") {
-            if (options.signal?.aborted)
-                throw grokError("Generation canceled", 499, "GENERATION_CANCELED");
-            throw grokError("Grok web search timed out", 504, "GROK_SEARCH_TIMEOUT");
-        }
-        if (e.code && e.status)
-            throw e;
-        throw grokError(`Grok web search request failed: ${e.message}`, 502, "GROK_SEARCH_NETWORK_FAILED");
-    }
-}
-export function parseGrokImagePlan(response, fallbackModel) {
-    const toolCalls = response.choices?.[0]?.message?.tool_calls || [];
-    const call = toolCalls.find((item) => item.type === "function" && item.function?.name === "generate_image");
-    if (!call?.function?.arguments) {
-        throw grokError("Grok planner did not call generate_image", 502, "GROK_PLANNER_EMPTY_TOOL_CALL");
-    }
-    let args;
-    try {
-        args = JSON.parse(call.function.arguments);
-    }
-    catch {
-        throw grokError("Grok planner returned invalid tool arguments", 502, "GROK_PLANNER_INVALID_TOOL_ARGS");
-    }
-    if (typeof args?.prompt !== "string" || !args.prompt.trim()) {
-        throw grokError("Grok planner returned an empty image prompt", 502, "GROK_PLANNER_INVALID_TOOL_ARGS");
-    }
-    return { prompt: args.prompt.trim(), model: fallbackModel, webSearchCalls: 1 };
-}
-export async function planGrokImage(prompt, ctx, options = {}) {
-    const imageModel = options.model || ctx.config.grokProvider?.defaultImageModel || "grok-imagine-image-quality";
-    const planner = getPlannerConfig(ctx);
-    const plannerModel = options.plannerModel || planner.model;
-    const sizeParams = mapSizeToGrokImageParams(options.size);
-    // Honor the web-search toggle end to end: skip the forced search call and
-    // record calls actually made (070 QA: search ran even with
-    // webSearchEnabled:false, and webSearchCalls was hardcoded to 1).
-    const searchEnabled = options.webSearchEnabled !== false;
-    const search = searchEnabled
-        ? await searchGrokVisualContext(prompt, ctx, { ...(options.signal ? { signal: options.signal } : {}), ...(options.requestId ? { requestId: options.requestId } : {}), ...(options.directApiKey ? { directApiKey: options.directApiKey } : {}), plannerModel })
-        : { summary: "", skipped: true };
-    const payload = buildGrokPlannerPayload(prompt, imageModel, options.size, sizeParams, plannerModel, search.summary, options.references || options.referenceCount || 0, options.backgroundConstraint || "");
-    const { url, headers } = getGrokEndpoint(ctx, "/v1/chat/completions", options.directApiKey);
-    const { combinedSignal, timer } = withTimeoutSignal(options.signal, planner.timeoutMs);
-    logEvent("grok", "planner:start", { requestId: options.requestId, plannerModel, imageModel, size: options.size });
-    try {
-        // Safe to replay: the planner produces no billable artifact, only a prompt.
-        const res = await grokFetchWithRetry(() => fetch(url, {
-            method: "POST",
-            headers,
-            body: JSON.stringify(payload),
-            signal: combinedSignal,
-        }), { signal: combinedSignal, label: "planner" });
-        clearTimeout(timer);
-        if (!res.ok) {
-            const text = await res.text().catch(() => "");
-            let parsed;
-            try {
-                parsed = JSON.parse(text);
-            }
-            catch { /* ignore */ }
-            const msg = parsed?.error || text || `HTTP ${res.status}`;
-            throw grokStageError("planner", msg, res.status);
-        }
-        const parsed = parseGrokImagePlan(await res.json(), imageModel);
-        const plan = { ...parsed, webSearchCalls: searchEnabled ? 1 : 0 };
-        logEvent("grok", "planner:done", {
-            requestId: options.requestId,
-            plannerModel,
-            imageModel,
-            promptChars: plan.prompt.length,
-            aspectRatio: sizeParams.aspect_ratio,
-            resolution: sizeParams.resolution,
-        });
-        return plan;
-    }
-    catch (e) {
-        clearTimeout(timer);
-        if (e.name === "AbortError") {
-            if (options.signal?.aborted)
-                throw grokError("Generation canceled", 499, "GENERATION_CANCELED");
-            throw grokError("Grok planner timed out", 504, "GROK_PLANNER_TIMEOUT");
-        }
-        if (e.code && e.status)
-            throw e;
-        throw grokError(`Grok planner request failed: ${e.message}`, 502, "GROK_PLANNER_NETWORK_FAILED");
-    }
-}
-export async function generateViaGrok(prompt, ctx, options = {}) {
-    const model = options.model || ctx.config.grokProvider?.defaultImageModel || "grok-imagine-image-quality";
-    const references = options.references || [];
-    const plan = options.plannedPrompt
-        ? { prompt: options.plannedPrompt, model, webSearchCalls: options.webSearchCalls ?? 1 }
-        : await planGrokImage(prompt, ctx, { ...options, referenceCount: references.length, directApiKey: options.directApiKey });
-    const hasReferences = references.length > 0;
-    const payload = hasReferences
-        ? imageEditPayload(model, plan.prompt, references, options.size)
-        : imagePayload(model, plan.prompt, options.size);
-    const endpoint = hasReferences ? "/v1/images/edits" : "/v1/images/generations";
-    const logStage = hasReferences ? "generate:edit-start" : "generate:start";
-    logEvent("grok", logStage, {
-        requestId: options.requestId,
-        model,
-        promptChars: plan.prompt.length,
-        size: options.size,
-        refs: references.length,
-    });
-    const result = await postGrokImages(ctx, payload, options.signal, endpoint, options.directApiKey);
-    const imageUrl = result.data?.[0]?.url;
-    if (!imageUrl) {
-        throw grokError("Grok returned no image URL", 502, "GROK_EMPTY_RESPONSE");
-    }
-    const downloaded = await downloadGrokImageUrl(imageUrl, options.signal);
-    const usage = result.usage ? { grok_cost_usd_ticks: result.usage.cost_in_usd_ticks ?? 0 } : null;
-    logEvent("grok", "generate:done", {
-        requestId: options.requestId,
-        model,
-        endpoint,
-        refs: references.length,
-        b64Len: downloaded.b64.length,
-    });
-    return { b64: downloaded.b64, providerUrl: imageUrl, usage, webSearchCalls: plan.webSearchCalls, mime: downloaded.mime, revisedPrompt: plan.prompt };
-}
-export async function editViaGrok(prompt, imageB64, ctx, options = {}) {
-    const model = options.model || ctx.config.grokProvider?.defaultImageModel || "grok-imagine-image-quality";
-    const detectedInputMime = detectImageMimeFromB64(imageB64) || "image/png";
-    const imageUrl = imageB64.startsWith("data:") ? imageB64 : `data:${detectedInputMime};base64,${imageB64}`;
-    const payload = { model, prompt, n: 1, response_format: "url", image: { type: "image_url", url: imageUrl }, ...mapSizeToGrokImageParams(options.size) };
-    logEvent("grok", "edit:start", { requestId: options.requestId, model, promptChars: prompt.length });
-    const result = await postGrokImages(ctx, payload, options.signal, "/v1/images/edits", options.directApiKey);
-    const editResultUrl = result.data?.[0]?.url;
-    if (!editResultUrl) {
-        throw grokError("Grok edit returned no image URL", 502, "GROK_EMPTY_RESPONSE");
-    }
-    const downloaded = await downloadGrokImageUrl(editResultUrl, options.signal);
-    const usage = result.usage ? { grok_cost_usd_ticks: result.usage.cost_in_usd_ticks ?? 0 } : null;
-    logEvent("grok", "edit:done", { requestId: options.requestId, model, b64Len: downloaded.b64.length });
-    return { b64: downloaded.b64, providerUrl: editResultUrl, usage, webSearchCalls: 0, mime: downloaded.mime, revisedPrompt: result.data[0]?.revised_prompt || prompt };
-}
+export { buildGrokPlannerPayload, buildGrokSearchPayload, searchGrokVisualContext, parseGrokImagePlan, planGrokImage, } from "./grokImagePlanner.js";
+export { generateViaGrok, editViaGrok } from "./providers/adapters/grokOperations.js";

package/lib/grokImageCore.js

@@ -1,7 +1,7 @@
 import { mapSizeToGrokImageParams } from "./grokSizeMapper.js";
 import { detectImageMimeFromB64 } from "./refs.js";
 import { getGrokProxyUrl } from "./grokRuntime.js";
-import { grokFetchWithRetry } from "./grokUpstreamRetry.js";
+export { downloadGrokImageUrl } from "./grokImageDownload.js";
 import { DEFAULT_GROK_PLANNER_MODEL } from "../config.js";
 export function getGrokEndpoint(ctx, path = "/v1/images/generations", directApiKey) {
     if (directApiKey) {
@@ -76,62 +76,6 @@ export function extractResponsesText(response) {
     }
     return chunks.join("\n\n").trim();
 }
-const MAX_IMAGE_DOWNLOAD_BYTES = 50 * 1024 * 1024;
-export async function downloadGrokImageUrl(url, signal, timeoutMs = 30_000) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
-    try {
-        const parsed = new URL(url);
-        if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
-            throw grokError("Image download URL must be HTTP(S)", 502, "GROK_IMAGE_DOWNLOAD_FAILED");
-        }
-        // Safe to replay: downloading a finished artifact creates nothing upstream.
-        const res = await grokFetchWithRetry(() => fetch(url, { signal: combined }), { signal: combined, label: "image-download" });
-        if (!res.ok)
-            throw grokError(`Image download failed: HTTP ${res.status}`, 502, "GROK_IMAGE_DOWNLOAD_FAILED");
-        const contentLength = Number(res.headers.get("content-length") || "0");
-        if (contentLength > MAX_IMAGE_DOWNLOAD_BYTES) {
-            throw grokError("Image download exceeds 50MB limit", 502, "GROK_IMAGE_DOWNLOAD_FAILED");
-        }
-        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");
-        const mime = res.headers.get("content-type")?.split(";")[0]?.trim()
-            || detectImageMimeFromB64(buffer.toString("base64"))
-            || "image/png";
-        return { buffer, b64: buffer.toString("base64"), mime };
-    }
-    catch (e) {
-        clearTimeout(timer);
-        if (e.name === "AbortError") {
-            if (signal?.aborted)
-                throw grokError("Generation canceled", 499, "GENERATION_CANCELED");
-            throw grokError("Image download timed out", 504, "GROK_IMAGE_TIMEOUT");
-        }
-        if (e.code && e.status)
-            throw e;
-        throw grokError(`Image download failed: ${e.message}`, 502, "GROK_IMAGE_DOWNLOAD_FAILED");
-    }
-}
 /**
  * NOT wrapped in grokFetchWithRetry on purpose: a reset or 5xx here may follow an image the
  * origin already generated and billed, and no idempotency key exists to deduplicate it.

package/lib/grokImageDownload.js

@@ -0,0 +1,159 @@
+import { pinnedHttpGet, PinnedGetFailure } from "./pinnedHttpGet.js";
+import { detectImageMimeFromB64 } from "./refs.js";
+import { grokFetchWithRetry } from "./grokUpstreamRetry.js";
+import { resolveImageDownloadTarget, } from "./grokImageDownloadPolicy.js";
+const MAX_IMAGE_DOWNLOAD_BYTES = 50 * 1024 * 1024;
+const MAX_IMAGE_REDIRECTS = 5;
+const IMAGE_REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+class ImageDownloadFailure extends Error {
+    status;
+    code;
+    constructor(message, status = 502, code = "GROK_IMAGE_DOWNLOAD_FAILED") {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+class ImageBodyFailure extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+    }
+}
+function cancelPinnedImageResponse(response) {
+    try {
+        void Promise.resolve(response.cancel()).catch(() => { });
+    }
+    catch { /* cleanup only */ }
+    return Promise.resolve(); // Never await an advisory cleanup promise.
+}
+function toRetryResponse(source) {
+    const headers = new Headers();
+    const retryAfter = source.headers.get("retry-after");
+    if (retryAfter !== null)
+        headers.set("retry-after", retryAfter);
+    return { ok: source.status >= 200 && source.status < 300, status: source.status,
+        headers, source, body: { cancel: () => cancelPinnedImageResponse(source) } };
+}
+async function fetchPinnedImageWithRetry(url, policy, signal) {
+    let active;
+    try {
+        const result = await grokFetchWithRetry(async () => {
+            const target = await resolveImageDownloadTarget(url, policy, signal);
+            signal.throwIfAborted();
+            active = await pinnedHttpGet(target, signal);
+            return toRetryResponse(active);
+        }, { signal, label: "image-download" });
+        signal.throwIfAborted();
+        return result.source;
+    }
+    catch (error) {
+        if (active)
+            void cancelPinnedImageResponse(active);
+        throw error;
+    }
+}
+async function readBoundedImageBody(response, options) {
+    const onAbort = () => { void cancelPinnedImageResponse(response); };
+    options.signal.addEventListener("abort", onAbort, { once: true });
+    try {
+        options.signal.throwIfAborted();
+        if (Number(response.headers.get("content-length")) > options.maxBytes) {
+            throw new ImageBodyFailure("too-large");
+        }
+        if (!response.body)
+            throw new ImageBodyFailure("empty");
+        const chunks = [];
+        let total = 0;
+        for await (const chunk of response.body) {
+            options.signal.throwIfAborted();
+            total += chunk.byteLength;
+            if (total > options.maxBytes) {
+                void cancelPinnedImageResponse(response);
+                throw new ImageBodyFailure("too-large");
+            }
+            chunks.push(Buffer.from(chunk));
+        }
+        options.signal.throwIfAborted();
+        if (!total)
+            throw new ImageBodyFailure("empty");
+        return Buffer.concat(chunks, total);
+    }
+    catch (error) {
+        void cancelPinnedImageResponse(response);
+        throw error;
+    }
+    finally {
+        options.signal.removeEventListener("abort", onAbort);
+    }
+}
+async function downloadImageHops(url, policy, signal) {
+    const trustedOrigin = policy.trustedProxyOrigin ? new URL(policy.trustedProxyOrigin).origin : undefined;
+    let trusted = trustedOrigin !== undefined && url.origin === trustedOrigin;
+    let currentUrl = url;
+    for (let redirects = 0;; redirects++) {
+        signal.throwIfAborted();
+        const effectiveHopPolicy = trusted ? { trustedProxyOrigin: trustedOrigin } : {};
+        const response = await fetchPinnedImageWithRetry(currentUrl, effectiveHopPolicy, signal);
+        try {
+            signal.throwIfAborted();
+            if (IMAGE_REDIRECT_STATUSES.has(response.status)) {
+                const location = response.headers.get("location");
+                if (!location?.trim() || redirects >= MAX_IMAGE_REDIRECTS) {
+                    throw new ImageDownloadFailure("Image download redirect refused");
+                }
+                currentUrl = new URL(location, currentUrl);
+                trusted = trusted && currentUrl.origin === trustedOrigin;
+                continue;
+            }
+            if (response.status < 200 || response.status >= 300) {
+                throw new ImageDownloadFailure(`Image download failed: HTTP ${response.status}`);
+            }
+            const buffer = await readBoundedImageBody(response, { maxBytes: MAX_IMAGE_DOWNLOAD_BYTES, signal });
+            signal.throwIfAborted();
+            const b64 = buffer.toString("base64");
+            const mime = response.headers.get("content-type")?.split(";")[0]?.trim()
+                || detectImageMimeFromB64(b64) || "image/png";
+            return { buffer, b64, mime };
+        }
+        finally {
+            void cancelPinnedImageResponse(response);
+        }
+    }
+}
+export async function downloadGrokImageUrl(url, signal, timeoutMs = 30_000, policy = {}) {
+    const controller = new AbortController();
+    const combined = new AbortController();
+    const onAbort = () => combined.abort(signal?.reason);
+    const timer = setTimeout(() => { controller.abort(); combined.abort(controller.signal.reason); }, timeoutMs);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        if (signal?.aborted)
+            onAbort();
+        combined.signal.throwIfAborted();
+        const result = await downloadImageHops(new URL(url), policy, combined.signal);
+        combined.signal.throwIfAborted();
+        return result;
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw new ImageDownloadFailure("Generation canceled", 499, "GENERATION_CANCELED");
+        if (controller.signal.aborted)
+            throw new ImageDownloadFailure("Image download timed out", 504, "GROK_IMAGE_TIMEOUT");
+        if (error instanceof ImageBodyFailure) {
+            throw new ImageDownloadFailure(error.reason === "too-large"
+                ? "Image download exceeds 50MB limit" : "Image download was empty");
+        }
+        if (error instanceof ImageDownloadFailure)
+            throw error;
+        if (error instanceof PinnedGetFailure)
+            throw new ImageDownloadFailure(error.message);
+        // Never publish raw DNS/socket errors, URL parse errors or signed URL credentials.
+        throw new ImageDownloadFailure("Image download failed");
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+    }
+}