@phuetz/code-buddy 1.6.0 → 2.0.0

package/dist/tools/media-generation-tool.js

@@ -1,8 +1,10 @@
 import { randomUUID } from 'crypto';
+import { constants as fsConstants } from 'fs';
 import fs from 'fs/promises';
 import path from 'path';
 import { getImageGenerationModel } from '../config/agent-defaults.js';
 import { resolveToolGatewayRoute } from '../agent/tool-gateway-router.js';
+import { logger } from '../utils/logger.js';
 const IMAGE_SIZES = {
     landscape: '1536x1024',
     square: '1024x1024',
@@ -40,6 +42,12 @@ export async function generateImage(input, runtime = {}) {
     const aspect = resolveImageAspect(input.aspectRatio);
     const fetchImpl = runtime.fetch ?? fetch;
     const generatedAt = (runtime.now ?? (() => new Date()))().toISOString();
+    // ComfyUI has a workflow-submit/poll/view API, not /images/generations.
+    if (config.provider === 'comfyui') {
+        const comfy = await generateComfyUIImageWithFallback(prompt, aspect, config, runtime, generatedAt);
+        await ingestLisaSelfieIfNeeded(comfy, runtime);
+        return comfy;
+    }
     const size = IMAGE_SIZES[aspect];
     const body = {
         model: config.model,
@@ -92,7 +100,16 @@ export async function generateImage(input, runtime = {}) {
     if (!imageRef) {
         throw new Error('Image provider returned neither b64_json nor url');
     }
-    return {
+    await writeMediaSidecar(outputPath, {
+        kind: 'image',
+        prompt,
+        ...(revisedPrompt ? { revisedPrompt } : {}),
+        provider: config.provider,
+        model: config.model,
+        aspect_ratio: aspect,
+        generatedAt,
+    });
+    const result = {
         kind: 'image_generate_result',
         success: true,
         image: imageRef,
@@ -104,6 +121,1142 @@ export async function generateImage(input, runtime = {}) {
         generatedAt,
         ...(revisedPrompt ? { revised_prompt: revisedPrompt } : {}),
     };
+    await ingestLisaSelfieIfNeeded(result, runtime);
+    return result;
+}
+async function ingestLisaSelfieIfNeeded(result, runtime) {
+    if (!result.success || !result.outputPath)
+        return;
+    try {
+        const { maybeIngestGeneratedLisaSelfie } = await import('../companion/lisa-selfie-ingest.js');
+        await maybeIngestGeneratedLisaSelfie({
+            sourcePath: result.outputPath,
+            prompt: result.prompt,
+            model: result.model,
+            provider: result.provider,
+            env: runtime.env,
+            rootDir: runtime.rootDir,
+        });
+    }
+    catch (err) {
+        logger.warn(`[image_generate] lisa selfie cache ingest skipped: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Edit an existing image without overwriting it. OpenAI receives a real PNG
+ * alpha mask through `/images/edits`; xAI receives its documented JSON image
+ * edit request and a precise normalized-region hint in the prompt. ComfyUI
+ * runs only through an explicit, validated API-format inpaint workflow.
+ */
+export async function editImage(input, runtime = {}) {
+    const prompt = input.prompt.trim();
+    if (!prompt)
+        throw new Error('prompt is required for image editing');
+    const imageUrl = validateImageReference(input.imageUrl, 'source image');
+    const selections = normalizeEditSelections(input.selections);
+    const maskUrl = input.maskUrl ? validateDataImage(input.maskUrl, 'mask') : undefined;
+    const config = resolveImageProvider(runtime.env ?? process.env);
+    const fetchImpl = runtime.fetch ?? fetch;
+    const generatedAt = (runtime.now ?? (() => new Date()))().toISOString();
+    const selectionHint = selections.length > 0
+        ? ` Preserve everything outside these normalized regions (x,y,width,height): ${selections
+            .map((selection) => `${selection.x.toFixed(4)},${selection.y.toFixed(4)},${selection.width.toFixed(4)},${selection.height.toFixed(4)}`)
+            .join('; ')}.`
+        : '';
+    const effectivePrompt = `${prompt}${selectionHint}`;
+    if (config.provider === 'comfyui') {
+        return editComfyUIImage({
+            prompt,
+            effectivePrompt,
+            imageUrl,
+            maskUrl,
+            selections,
+            sourceRef: input.sourceRef,
+        }, config, runtime, generatedAt);
+    }
+    let response;
+    if (config.provider === 'xai') {
+        response = await postJson(fetchImpl, joinUrl(config.baseUrl, '/images/edits'), {
+            headers: authHeaders(config.apiKey),
+            body: {
+                model: config.model,
+                prompt: effectivePrompt,
+                image: { url: imageUrl, type: 'image_url' },
+            },
+        });
+    }
+    else {
+        if (!imageUrl.startsWith('data:')) {
+            throw new Error('OpenAI image edits require a bounded image data URL; HTTPS sources are supported only by xAI');
+        }
+        const form = new FormData();
+        form.append('model', config.model);
+        form.append('prompt', effectivePrompt);
+        form.append('image[]', dataUrlToBlob(imageUrl, 'source image'), 'source.png');
+        if (maskUrl)
+            form.append('mask', dataUrlToBlob(maskUrl, 'mask'), 'mask.png');
+        const httpResponse = await fetchWithTimeout(fetchImpl, joinUrl(config.baseUrl, '/images/edits'), {
+            method: 'POST',
+            headers: config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {},
+            body: form,
+        }, 180_000);
+        response = await readJsonResponse(httpResponse, joinUrl(config.baseUrl, '/images/edits'));
+    }
+    const first = firstDataItem(response);
+    const b64 = stringField(first, 'b64_json');
+    const remoteUrl = stringField(first, 'url');
+    const revisedPrompt = stringField(first, 'revised_prompt');
+    let outputPath;
+    if (b64) {
+        outputPath = await saveGeneratedAsset(Buffer.from(b64, 'base64'), {
+            rootDir: runtime.rootDir,
+            dirName: 'images',
+            prefix: 'image-edit',
+            extension: 'png',
+            createId: runtime.createId,
+        });
+    }
+    else if (remoteUrl) {
+        outputPath = (await tryDownloadAsset(remoteUrl, {
+            fetchImpl,
+            rootDir: runtime.rootDir,
+            dirName: 'images',
+            prefix: 'image-edit',
+            fallbackExtension: 'png',
+            createId: runtime.createId,
+            maxBytes: 50 * 1024 * 1024,
+        })).outputPath;
+    }
+    const image = outputPath ?? remoteUrl;
+    if (!image)
+        throw new Error('Image edit provider returned neither b64_json nor url');
+    const maskMode = config.provider === 'openai' && maskUrl
+        ? 'alpha'
+        : selections.length > 0
+            ? 'region-prompt'
+            : 'none';
+    const sourceReference = sanitizeImageSourceReference(input.sourceRef) ?? redactDataUrl(imageUrl);
+    await writeMediaSidecar(outputPath, {
+        kind: 'image-edit',
+        prompt,
+        ...(revisedPrompt ? { revisedPrompt } : {}),
+        provider: config.provider,
+        model: config.model,
+        source: sourceReference,
+        masked: maskMode === 'alpha',
+        maskMode,
+        selections,
+        generatedAt,
+    });
+    return {
+        kind: 'image_edit_result',
+        success: true,
+        image,
+        ...(outputPath ? { outputPath, mediaPath: `MEDIA:${outputPath}` } : {}),
+        provider: config.provider,
+        model: config.model,
+        prompt,
+        generatedAt,
+        source: sourceReference,
+        masked: maskMode === 'alpha',
+        maskMode,
+        selections,
+        ...(revisedPrompt ? { revised_prompt: revisedPrompt } : {}),
+    };
+}
+const COMFY_DIMS = {
+    landscape: { width: 1024, height: 768 },
+    square: { width: 768, height: 768 },
+    portrait: { width: 768, height: 1024 },
+};
+const SD_TURBO_DIMS = {
+    // SD Turbo is strictly 512-native. Its non-square latents frequently tile a
+    // portrait into two faces, even at 512x768. The CPU fallback favours a clean
+    // square selfie over honoring the requested ratio with a broken image.
+    landscape: { width: 512, height: 512 },
+    square: { width: 512, height: 512 },
+    portrait: { width: 512, height: 512 },
+};
+const KREA2_DIMS = {
+    landscape: { width: 1344, height: 1024 },
+    square: { width: 1024, height: 1024 },
+    portrait: { width: 1024, height: 1344 },
+};
+function isKrea2Model(model) {
+    return /krea.?2/i.test(model);
+}
+function comfyDimensionsForModel(model, aspect) {
+    // SD Turbo is a 512-native model. Non-square latents commonly tile a close
+    // portrait into stacked/duplicate faces, which is unacceptable for Lisa.
+    if (isKrea2Model(model))
+        return KREA2_DIMS[aspect];
+    return /(?:^|[/_-])sd[_-]?turbo(?:[._-]|$)/i.test(model)
+        ? SD_TURBO_DIMS[aspect]
+        : COMFY_DIMS[aspect];
+}
+/** Sampler/step defaults keyed off the checkpoint family (turbo → few-step). */
+function comfyParamsForModel(model) {
+    const m = model.toLowerCase();
+    if (isKrea2Model(model)) {
+        // Krea 2 Turbo is distilled for eight Euler/simple steps with CFG disabled.
+        // In ComfyUI, cfg=1 plus ConditioningZeroOut matches the official workflow.
+        return { steps: 8, cfg: 1.0, sampler: 'euler', scheduler: 'simple' };
+    }
+    if (m.includes('turbo') || m.includes('lightning') || m.includes('lcm') || m.includes('hyper')) {
+        return { steps: 4, cfg: 1.0, sampler: 'euler', scheduler: 'sgm_uniform' };
+    }
+    if (m.includes('flux')) {
+        return { steps: 20, cfg: 1.0, sampler: 'euler', scheduler: 'simple' };
+    }
+    return { steps: 20, cfg: 7.0, sampler: 'euler', scheduler: 'normal' };
+}
+/**
+ * Resolve ComfyUI LoRA filename from env.
+ * Accepts `lisa`, `lisa.safetensors`, path basename, or `auto`
+ * (picks `lisa.safetensors` / first `*lisa*.safetensors` under models/loras).
+ * Empty / "none" / "off" → no LoRA.
+ */
+export function resolveComfyLoraName(envSource = process.env) {
+    const raw = (env(envSource, 'CODEBUDDY_COMFYUI_LORA') ?? '').trim();
+    if (!raw || /^(none|off|false|0)$/i.test(raw))
+        return undefined;
+    if (/^auto$/i.test(raw)) {
+        return detectInstalledLisaLoraSync(envSource) ?? 'lisa.safetensors';
+    }
+    const base = raw.split(/[/\\]/).pop().trim();
+    if (!base)
+        return undefined;
+    return base.endsWith('.safetensors') ? base : `${base}.safetensors`;
+}
+/** Best-effort sync scan of ComfyUI models/loras for a Lisa LoRA (never throws). */
+export function detectInstalledLisaLoraSync(envSource = process.env) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const fsSync = require('node:fs');
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const pathMod = require('node:path');
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const osMod = require('node:os');
+        const roots = [];
+        if (envSource.COMFYUI_ROOT?.trim())
+            roots.push(envSource.COMFYUI_ROOT.trim());
+        const home = osMod.homedir();
+        roots.push(pathMod.join(home, 'ComfyUI'), pathMod.join(home, 'DEV', 'ComfyUI'), pathMod.join(home, '.codebuddy', 'comfyui'));
+        for (const root of roots) {
+            const dir = pathMod.join(root, 'models', 'loras');
+            if (!fsSync.existsSync(dir))
+                continue;
+            const names = fsSync.readdirSync(dir).filter((n) => n.endsWith('.safetensors'));
+            const exact = names.find((n) => n.toLowerCase() === 'lisa.safetensors');
+            if (exact)
+                return exact;
+            const fuzzy = names.find((n) => /lisa/i.test(n));
+            if (fuzzy)
+                return fuzzy;
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return undefined;
+}
+export function resolveComfyLoraStrength(envSource = process.env) {
+    const n = Number(env(envSource, 'CODEBUDDY_COMFYUI_LORA_STRENGTH') ?? '0.85');
+    if (!Number.isFinite(n))
+        return 0.85;
+    return Math.min(1.5, Math.max(0, n));
+}
+/**
+ * Classic SD1.5/SDXL-style graph. Optional LoraLoader (node 10) when loraName is set.
+ * Exported for unit tests.
+ */
+export function buildComfyWorkflow(prompt, negative, ckpt, dims, params, seed, lora) {
+    // Default: checkpoint feeds KSampler + CLIP encode directly.
+    let modelRef = ['4', 0];
+    let clipRef = ['4', 1];
+    const graph = {
+        '4': { class_type: 'CheckpointLoaderSimple', inputs: { ckpt_name: ckpt } },
+        '5': {
+            class_type: 'EmptyLatentImage',
+            inputs: { width: dims.width, height: dims.height, batch_size: 1 },
+        },
+        '8': { class_type: 'VAEDecode', inputs: { samples: ['3', 0], vae: ['4', 2] } },
+        '9': {
+            class_type: 'SaveImage',
+            inputs: { filename_prefix: 'codebuddy', images: ['8', 0] },
+        },
+    };
+    if (lora?.name) {
+        graph['10'] = {
+            class_type: 'LoraLoader',
+            inputs: {
+                lora_name: lora.name,
+                strength_model: lora.strength,
+                strength_clip: lora.strength,
+                model: ['4', 0],
+                clip: ['4', 1],
+            },
+        };
+        modelRef = ['10', 0];
+        clipRef = ['10', 1];
+    }
+    graph['6'] = { class_type: 'CLIPTextEncode', inputs: { text: prompt, clip: clipRef } };
+    graph['7'] = { class_type: 'CLIPTextEncode', inputs: { text: negative, clip: clipRef } };
+    graph['3'] = {
+        class_type: 'KSampler',
+        inputs: {
+            seed,
+            steps: params.steps,
+            cfg: params.cfg,
+            sampler_name: params.sampler,
+            scheduler: params.scheduler,
+            denoise: 1.0,
+            model: modelRef,
+            positive: ['6', 0],
+            negative: ['7', 0],
+            latent_image: ['5', 0],
+        },
+    };
+    return graph;
+}
+/**
+ * Native Krea 2 graph from ComfyUI's official Krea 2 Turbo template.
+ * Krea 2 ships its diffusion model, Qwen3-VL encoder, and Qwen Image VAE as
+ * separate files. Its LoRAs are model-only and must not be applied to CLIP.
+ */
+export function buildKrea2ComfyWorkflow(prompt, unet, textEncoder, vae, dims, params, seed, lora) {
+    let modelRef = ['4', 0];
+    const graph = {
+        '4': {
+            class_type: 'UNETLoader',
+            inputs: { unet_name: unet, weight_dtype: 'default' },
+        },
+        '5': {
+            class_type: 'EmptyLatentImage',
+            inputs: { width: dims.width, height: dims.height, batch_size: 1 },
+        },
+        '6': {
+            class_type: 'CLIPLoader',
+            inputs: { clip_name: textEncoder, type: 'krea2', device: 'default' },
+        },
+        '7': { class_type: 'VAELoader', inputs: { vae_name: vae } },
+        '8': { class_type: 'CLIPTextEncode', inputs: { text: prompt, clip: ['6', 0] } },
+        '10': { class_type: 'ConditioningZeroOut', inputs: { conditioning: ['8', 0] } },
+        '11': { class_type: 'VAEDecode', inputs: { samples: ['3', 0], vae: ['7', 0] } },
+        '9': {
+            class_type: 'SaveImage',
+            inputs: { filename_prefix: 'codebuddy-krea2', images: ['11', 0] },
+        },
+    };
+    if (lora?.name) {
+        graph['12'] = {
+            class_type: 'LoraLoaderModelOnly',
+            inputs: {
+                lora_name: lora.name,
+                strength_model: lora.strength,
+                model: ['4', 0],
+            },
+        };
+        modelRef = ['12', 0];
+    }
+    graph['3'] = {
+        class_type: 'KSampler',
+        inputs: {
+            seed,
+            steps: params.steps,
+            cfg: params.cfg,
+            sampler_name: params.sampler,
+            scheduler: params.scheduler,
+            denoise: 1.0,
+            model: modelRef,
+            positive: ['8', 0],
+            negative: ['10', 0],
+            latent_image: ['5', 0],
+        },
+    };
+    return graph;
+}
+const COMFY_INPAINT_PLACEHOLDERS = {
+    source: '{{CODEBUDDY_SOURCE_IMAGE}}',
+    mask: '{{CODEBUDDY_MASK_IMAGE}}',
+    prompt: '{{CODEBUDDY_PROMPT}}',
+    negativePrompt: '{{CODEBUDDY_NEGATIVE_PROMPT}}',
+    output: '{{CODEBUDDY_OUTPUT_PREFIX}}',
+};
+const MAX_COMFY_WORKFLOW_BYTES = 1024 * 1024;
+const MAX_COMFY_WORKFLOW_NODES = 512;
+const SAFE_COMFY_ID = /^[A-Za-z0-9_.-]{1,128}$/;
+const SAFE_COMFY_INPUT = /^[A-Za-z0-9_.-]{1,64}$/;
+/** First image emitted by any output node in a /history entry, or null. */
+function firstComfyImage(outputs) {
+    if (!outputs || typeof outputs !== 'object')
+        return null;
+    for (const node of Object.values(outputs)) {
+        if (!node || typeof node !== 'object' || Array.isArray(node))
+            continue;
+        const images = node.images;
+        if (Array.isArray(images)) {
+            for (const img of images) {
+                const filename = stringField(img, 'filename');
+                if (filename) {
+                    return {
+                        filename,
+                        subfolder: stringField(img, 'subfolder') ?? '',
+                        type: stringField(img, 'type') ?? 'output',
+                    };
+                }
+            }
+        }
+    }
+    return null;
+}
+function comfyDelay(ms, signal) {
+    throwIfAborted(signal);
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(abortError(signal));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+export async function getImageEditCapabilities(runtime = {}) {
+    const config = resolveImageProvider(runtime.env ?? process.env);
+    if (config.provider === 'openai') {
+        return { provider: config.provider, available: true, alphaMasking: true };
+    }
+    if (config.provider === 'xai') {
+        return { provider: config.provider, available: true, alphaMasking: false };
+    }
+    if (config.provider !== 'comfyui') {
+        return { provider: config.provider, available: false, alphaMasking: false, reason: 'Provider does not support image editing' };
+    }
+    try {
+        await loadComfyInpaintTemplate(runtime);
+        return { provider: 'comfyui', available: true, alphaMasking: true };
+    }
+    catch (error) {
+        return {
+            provider: 'comfyui',
+            available: false,
+            alphaMasking: false,
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+async function editComfyUIImage(input, config, runtime, generatedAt) {
+    throwIfAborted(runtime.signal);
+    const template = await loadComfyInpaintTemplate(runtime);
+    if (!input.imageUrl.startsWith('data:')) {
+        throw new Error('ComfyUI inpainting requires a bounded source image data URL');
+    }
+    if (!input.maskUrl) {
+        throw new Error('ComfyUI inpainting requires an explicit PNG alpha mask');
+    }
+    if (!input.maskUrl.toLowerCase().startsWith('data:image/png;base64,')) {
+        throw new Error('ComfyUI inpainting requires a PNG alpha mask');
+    }
+    if (input.effectivePrompt.length > 20_000) {
+        throw new Error('ComfyUI inpainting prompt exceeds 20000 characters');
+    }
+    const fetchImpl = runtime.fetch ?? fetch;
+    const envSource = runtime.env ?? process.env;
+    const clientId = sanitizeId(runtime.createId?.() ?? randomUUID()).slice(0, 80);
+    const source = await uploadComfyInput({
+        baseUrl: config.baseUrl,
+        dataUrl: input.imageUrl,
+        filename: `codebuddy-source-${clientId}`,
+        fetchImpl,
+        signal: runtime.signal,
+    });
+    const mask = await uploadComfyInput({
+        baseUrl: config.baseUrl,
+        dataUrl: input.maskUrl,
+        filename: `codebuddy-mask-${clientId}`,
+        fetchImpl,
+        signal: runtime.signal,
+        maskFor: source,
+    });
+    const workflow = instantiateComfyInpaintWorkflow(template, {
+        source: source.workflowPath,
+        mask: mask.workflowPath,
+        prompt: input.effectivePrompt,
+        negativePrompt: env(envSource, 'CODEBUDDY_IMAGE_NEGATIVE') ?? 'blurry, low quality, deformed, watermark',
+        outputPrefix: `codebuddy-inpaint-${clientId}`,
+    });
+    const submit = await postJson(fetchImpl, joinUrl(config.baseUrl, '/prompt'), {
+        headers: { 'Content-Type': 'application/json' },
+        body: { prompt: workflow, client_id: clientId },
+        timeoutMs: comfyDuration(envSource, 'CODEBUDDY_COMFYUI_SUBMIT_TIMEOUT_MS', 120_000, 1_000, 300_000),
+        signal: runtime.signal,
+    });
+    const promptId = stringField(submit, 'prompt_id');
+    if (!promptId || !SAFE_COMFY_ID.test(promptId) || isDangerousKey(promptId)) {
+        const detail = submit.error ?? submit.node_errors;
+        throw new Error(`ComfyUI rejected the inpaint workflow${detail ? `: ${JSON.stringify(detail).slice(0, 300)}` : ' (no valid prompt_id)'}`);
+    }
+    const outputRef = await pollComfyOutput({
+        baseUrl: config.baseUrl,
+        promptId,
+        outputNodeId: template.bindings.output.nodeId,
+        fetchImpl,
+        signal: runtime.signal,
+        timeoutMs: comfyDuration(envSource, 'CODEBUDDY_COMFYUI_INPAINT_TIMEOUT_MS', comfyDuration(envSource, 'CODEBUDDY_COMFYUI_TIMEOUT_MS', 300_000, 0, 900_000), 0, 900_000),
+        intervalMs: comfyDuration(envSource, 'CODEBUDDY_COMFYUI_POLL_MS', 1_500, 10, 10_000),
+        now: runtime.now ?? (() => new Date()),
+    });
+    const viewUrl = joinUrl(config.baseUrl, `/view?filename=${encodeURIComponent(outputRef.filename)}&subfolder=${encodeURIComponent(outputRef.subfolder)}&type=output`);
+    const viewResponse = await fetchWithTimeout(fetchImpl, viewUrl, {
+        headers: { Accept: 'image/png' },
+    }, 120_000, runtime.signal);
+    if (!viewResponse.ok) {
+        throw new Error(`ComfyUI /view returned ${viewResponse.status} for the configured inpaint output`);
+    }
+    const bytes = await readBoundedResponseBytes(viewResponse, MAX_EDIT_REFERENCE_BYTES, 120_000, runtime.signal, 'ComfyUI inpaint output');
+    if (bytes.length <= 0 || bytes.length > MAX_EDIT_REFERENCE_BYTES || !isPng(bytes)) {
+        throw new Error('ComfyUI inpaint output must be a PNG smaller than 50 MB');
+    }
+    const outputPath = await saveGeneratedAsset(bytes, {
+        rootDir: runtime.rootDir,
+        dirName: 'images',
+        prefix: 'image-edit',
+        extension: 'png',
+        createId: runtime.createId,
+    });
+    const sourceReference = sanitizeImageSourceReference(input.sourceRef) ?? redactDataUrl(input.imageUrl);
+    await writeMediaSidecar(outputPath, {
+        kind: 'image-edit',
+        prompt: input.prompt,
+        provider: 'comfyui',
+        model: config.model,
+        source: sourceReference,
+        masked: true,
+        maskMode: 'alpha',
+        selections: input.selections,
+        generatedAt,
+    });
+    return {
+        kind: 'image_edit_result',
+        success: true,
+        image: outputPath,
+        outputPath,
+        mediaPath: `MEDIA:${outputPath}`,
+        provider: 'comfyui',
+        model: config.model,
+        prompt: input.prompt,
+        generatedAt,
+        source: sourceReference,
+        masked: true,
+        maskMode: 'alpha',
+        selections: input.selections,
+    };
+}
+async function loadComfyInpaintTemplate(runtime) {
+    const envSource = runtime.env ?? process.env;
+    const configuredPath = env(envSource, 'CODEBUDDY_COMFYUI_INPAINT_WORKFLOW');
+    const inline = env(envSource, 'CODEBUDDY_COMFYUI_INPAINT_WORKFLOW_JSON');
+    if (configuredPath && inline) {
+        throw new Error('Configure either CODEBUDDY_COMFYUI_INPAINT_WORKFLOW or CODEBUDDY_COMFYUI_INPAINT_WORKFLOW_JSON, not both');
+    }
+    if (!configuredPath && !inline) {
+        throw new Error('ComfyUI image editing requires an explicit inpaint workflow (CODEBUDDY_COMFYUI_INPAINT_WORKFLOW or CODEBUDDY_COMFYUI_INPAINT_WORKFLOW_JSON)');
+    }
+    let raw;
+    if (inline) {
+        if (Buffer.byteLength(inline) > MAX_COMFY_WORKFLOW_BYTES)
+            throw new Error('ComfyUI inpaint workflow JSON exceeds 1 MB');
+        raw = inline;
+    }
+    else {
+        const requested = configuredPath;
+        if (requested.includes('\0'))
+            throw new Error('ComfyUI inpaint workflow path is invalid');
+        const workflowPath = path.resolve(runtime.rootDir ?? process.cwd(), requested);
+        const metadata = await fs.lstat(workflowPath);
+        if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size > MAX_COMFY_WORKFLOW_BYTES) {
+            throw new Error('ComfyUI inpaint workflow must be a regular JSON file smaller than 1 MB');
+        }
+        raw = await fs.readFile(workflowPath, 'utf8');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`ComfyUI inpaint workflow is invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isPlainRecord(parsed))
+        throw new Error('ComfyUI inpaint workflow must be a JSON object');
+    let workflowValue;
+    let bindingsValue;
+    if ('workflow' in parsed || 'bindings' in parsed) {
+        if (!('workflow' in parsed) || !('bindings' in parsed)) {
+            throw new Error('ComfyUI inpaint workflow bundle requires both workflow and bindings');
+        }
+        if (Object.keys(parsed).some((key) => !['schemaVersion', 'workflow', 'bindings'].includes(key))
+            || (parsed.schemaVersion !== undefined && parsed.schemaVersion !== 1)) {
+            throw new Error('ComfyUI inpaint workflow bundle contains unsupported fields or schemaVersion');
+        }
+        workflowValue = parsed.workflow;
+        bindingsValue = parsed.bindings;
+        if (env(envSource, 'CODEBUDDY_COMFYUI_INPAINT_BINDINGS_JSON')) {
+            throw new Error('Do not combine bundled ComfyUI bindings with CODEBUDDY_COMFYUI_INPAINT_BINDINGS_JSON');
+        }
+    }
+    else {
+        workflowValue = parsed;
+        const bindingsJson = env(envSource, 'CODEBUDDY_COMFYUI_INPAINT_BINDINGS_JSON');
+        if (!bindingsJson || Buffer.byteLength(bindingsJson) > 32_768) {
+            throw new Error('A direct ComfyUI API workflow requires bounded CODEBUDDY_COMFYUI_INPAINT_BINDINGS_JSON');
+        }
+        try {
+            bindingsValue = JSON.parse(bindingsJson);
+        }
+        catch (error) {
+            throw new Error(`ComfyUI inpaint bindings are invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return validateComfyInpaintTemplate(workflowValue, bindingsValue);
+}
+function validateComfyInpaintTemplate(workflowValue, bindingsValue) {
+    if (!isPlainRecord(workflowValue))
+        throw new Error('ComfyUI inpaint workflow graph must be an object');
+    const entries = Object.entries(workflowValue);
+    if (entries.length === 0 || entries.length > MAX_COMFY_WORKFLOW_NODES) {
+        throw new Error(`ComfyUI inpaint workflow must contain 1..${MAX_COMFY_WORKFLOW_NODES} nodes`);
+    }
+    const workflow = Object.create(null);
+    for (const [nodeId, rawNode] of entries) {
+        if (!SAFE_COMFY_ID.test(nodeId) || isDangerousKey(nodeId) || !isPlainRecord(rawNode)
+            || typeof rawNode.class_type !== 'string' || !SAFE_COMFY_ID.test(rawNode.class_type) || isDangerousKey(rawNode.class_type)
+            || !isPlainRecord(rawNode.inputs)) {
+            throw new Error(`ComfyUI inpaint workflow node ${nodeId.slice(0, 80)} is invalid`);
+        }
+        if (Object.keys(rawNode).some((key) => !['class_type', 'inputs', '_meta'].includes(key))) {
+            throw new Error(`ComfyUI inpaint workflow node ${nodeId} contains unsupported fields`);
+        }
+        validateSafeJson(rawNode.inputs, `node ${nodeId} inputs`, 0);
+        if (rawNode._meta !== undefined) {
+            if (!isPlainRecord(rawNode._meta))
+                throw new Error(`ComfyUI node ${nodeId} metadata is invalid`);
+            validateSafeJson(rawNode._meta, `node ${nodeId} metadata`, 0);
+        }
+        workflow[nodeId] = {
+            class_type: rawNode.class_type,
+            inputs: cloneJsonRecord(rawNode.inputs),
+            ...(rawNode._meta ? { _meta: cloneJsonRecord(rawNode._meta) } : {}),
+        };
+    }
+    validateComfyNodeReferences(workflow);
+    const bindings = parseComfyBindings(bindingsValue);
+    validateComfyBinding(workflow, bindings.source, 'source', 'LoadImage', COMFY_INPAINT_PLACEHOLDERS.source);
+    validateComfyBinding(workflow, bindings.mask, 'mask', 'LoadImage', COMFY_INPAINT_PLACEHOLDERS.mask);
+    validateComfyBinding(workflow, bindings.prompt, 'prompt', 'CLIPTextEncode', COMFY_INPAINT_PLACEHOLDERS.prompt);
+    if (bindings.negativePrompt) {
+        validateComfyBinding(workflow, bindings.negativePrompt, 'negativePrompt', 'CLIPTextEncode', COMFY_INPAINT_PLACEHOLDERS.negativePrompt);
+    }
+    validateComfyBinding(workflow, bindings.output, 'output', 'SaveImage', COMFY_INPAINT_PLACEHOLDERS.output);
+    if (bindings.source.nodeId === bindings.mask.nodeId) {
+        throw new Error('ComfyUI inpaint source and mask require distinct LoadImage nodes');
+    }
+    const outputNode = workflow[bindings.output.nodeId];
+    if (!isComfyNodeReference(outputNode.inputs.images) || !workflow[outputNode.inputs.images[0]]) {
+        throw new Error('Configured ComfyUI SaveImage output must reference an existing image-producing node');
+    }
+    validateComfyInpaintDataflow(workflow, bindings);
+    const expected = new Set([
+        COMFY_INPAINT_PLACEHOLDERS.source,
+        COMFY_INPAINT_PLACEHOLDERS.mask,
+        COMFY_INPAINT_PLACEHOLDERS.prompt,
+        COMFY_INPAINT_PLACEHOLDERS.output,
+        ...(bindings.negativePrompt ? [COMFY_INPAINT_PLACEHOLDERS.negativePrompt] : []),
+    ]);
+    const placeholders = collectComfyPlaceholders(workflow);
+    if (placeholders.length !== expected.size || placeholders.some((placeholder) => !expected.has(placeholder))) {
+        throw new Error('ComfyUI inpaint workflow contains missing, duplicate, or unsupported CODEBUDDY placeholders');
+    }
+    return { workflow, bindings };
+}
+function parseComfyBindings(value) {
+    if (!isPlainRecord(value) || Object.keys(value).some((key) => !['source', 'mask', 'prompt', 'negativePrompt', 'output'].includes(key))) {
+        throw new Error('ComfyUI inpaint bindings must define only source, mask, prompt, optional negativePrompt, and output');
+    }
+    return {
+        source: parseComfyBinding(value.source, 'source'),
+        mask: parseComfyBinding(value.mask, 'mask'),
+        prompt: parseComfyBinding(value.prompt, 'prompt'),
+        ...(value.negativePrompt !== undefined ? { negativePrompt: parseComfyBinding(value.negativePrompt, 'negativePrompt') } : {}),
+        output: parseComfyBinding(value.output, 'output'),
+    };
+}
+function parseComfyBinding(value, label) {
+    if (!isPlainRecord(value) || Object.keys(value).some((key) => !['nodeId', 'input'].includes(key))
+        || typeof value.nodeId !== 'string' || !SAFE_COMFY_ID.test(value.nodeId) || isDangerousKey(value.nodeId)
+        || typeof value.input !== 'string' || !SAFE_COMFY_INPUT.test(value.input) || isDangerousKey(value.input)) {
+        throw new Error(`ComfyUI ${label} binding must contain safe nodeId and input fields`);
+    }
+    return { nodeId: value.nodeId, input: value.input };
+}
+function validateComfyBinding(workflow, binding, label, expectedClass, placeholder) {
+    const node = workflow[binding.nodeId];
+    if (!node || node.class_type !== expectedClass || node.inputs[binding.input] !== placeholder) {
+        throw new Error(`ComfyUI ${label} binding must target ${expectedClass}.${binding.input} containing ${placeholder}`);
+    }
+}
+function instantiateComfyInpaintWorkflow(template, values) {
+    const workflow = cloneJsonRecord(template.workflow);
+    setComfyBinding(workflow, template.bindings.source, values.source);
+    setComfyBinding(workflow, template.bindings.mask, values.mask);
+    setComfyBinding(workflow, template.bindings.prompt, values.prompt);
+    if (template.bindings.negativePrompt)
+        setComfyBinding(workflow, template.bindings.negativePrompt, values.negativePrompt);
+    setComfyBinding(workflow, template.bindings.output, values.outputPrefix);
+    return workflow;
+}
+function setComfyBinding(workflow, binding, value) {
+    workflow[binding.nodeId].inputs[binding.input] = value;
+}
+async function uploadComfyInput(options) {
+    throwIfAborted(options.signal);
+    const match = options.dataUrl.match(/^data:(image\/(?:png|jpe?g|webp));base64,([A-Za-z0-9+/=]+)$/i);
+    if (!match)
+        throw new Error('ComfyUI upload requires a bounded PNG, JPEG, or WebP data URL');
+    const mime = match[1].toLowerCase();
+    if (options.maskFor && mime !== 'image/png')
+        throw new Error('ComfyUI mask upload requires PNG');
+    const extension = mime === 'image/png' ? 'png' : mime === 'image/webp' ? 'webp' : 'jpg';
+    const bytes = Buffer.from(match[2], 'base64');
+    if (bytes.length <= 0 || bytes.length > MAX_EDIT_REFERENCE_BYTES)
+        throw new Error('ComfyUI upload exceeds 50 MB');
+    if (!isImageBytesForMime(bytes, mime))
+        throw new Error(`ComfyUI upload content does not match ${mime}`);
+    const form = new FormData();
+    form.append('image', new Blob([bytes], { type: mime }), `${options.filename}.${extension}`);
+    form.append('type', 'input');
+    if (options.maskFor) {
+        form.append('subfolder', options.maskFor.subfolder);
+        form.append('original_ref', JSON.stringify({
+            filename: options.maskFor.filename,
+            subfolder: options.maskFor.subfolder,
+            type: 'input',
+        }));
+    }
+    else {
+        form.append('overwrite', 'false');
+    }
+    const endpoint = options.maskFor ? '/upload/mask' : '/upload/image';
+    const response = await fetchWithTimeout(options.fetchImpl, joinUrl(options.baseUrl, endpoint), {
+        method: 'POST',
+        body: form,
+    }, 120_000, options.signal);
+    const body = await readJsonResponse(response, joinUrl(options.baseUrl, endpoint));
+    const filename = stringField(body, 'name') ?? stringField(body, 'filename');
+    const subfolder = stringField(body, 'subfolder') ?? '';
+    const type = stringField(body, 'type') ?? 'input';
+    if (!filename || !isSafeComfyFilename(filename) || !isSafeComfySubfolder(subfolder) || type !== 'input') {
+        throw new Error(`ComfyUI ${endpoint} returned an unsafe file reference`);
+    }
+    return {
+        filename,
+        subfolder,
+        type,
+        workflowPath: subfolder ? `${subfolder.replace(/\\/g, '/')}/${filename}` : filename,
+    };
+}
+async function pollComfyOutput(options) {
+    const deadline = options.now().getTime() + options.timeoutMs;
+    for (;;) {
+        throwIfAborted(options.signal);
+        const history = await getJson(options.fetchImpl, joinUrl(options.baseUrl, `/history/${options.promptId}`), {
+            Accept: 'application/json',
+        }, 60_000, options.signal);
+        const entry = history[options.promptId];
+        const status = entry?.status?.status_str?.toLowerCase();
+        if (status && ['error', 'failed', 'cancelled', 'canceled'].includes(status)) {
+            throw new Error(`ComfyUI inpaint execution failed (${status}): ${JSON.stringify(entry?.status?.messages ?? '').slice(0, 300)}`);
+        }
+        if (entry?.outputs) {
+            const output = entry.outputs[options.outputNodeId];
+            if (output !== undefined) {
+                const image = firstComfyImage({ [options.outputNodeId]: output });
+                if (!image || image.type !== 'output' || !isSafeComfyFilename(image.filename) || !isSafeComfySubfolder(image.subfolder)) {
+                    throw new Error('Configured ComfyUI inpaint output node finished without a safe SaveImage output');
+                }
+                return image;
+            }
+        }
+        if (entry?.status?.completed) {
+            throw new Error('ComfyUI inpaint completed without the configured SaveImage output');
+        }
+        if (options.now().getTime() >= deadline) {
+            throw new Error(`ComfyUI inpainting timed out after ${options.timeoutMs}ms (prompt ${options.promptId})`);
+        }
+        await comfyDelay(options.intervalMs, options.signal);
+    }
+}
+function comfyDuration(envSource, key, fallback, min, max) {
+    const raw = env(envSource, key);
+    if (!raw)
+        return fallback;
+    const value = Number(raw);
+    return Number.isFinite(value) ? Math.max(min, Math.min(max, Math.round(value))) : fallback;
+}
+function validateComfyNodeReferences(workflow) {
+    for (const [nodeId, node] of Object.entries(workflow)) {
+        const references = [];
+        collectComfyNodeReferences(node.inputs, references);
+        for (const [dependency] of references) {
+            if (!workflow[dependency]) {
+                throw new Error(`ComfyUI node ${nodeId} references missing node ${dependency}`);
+            }
+        }
+    }
+}
+function validateComfyInpaintDataflow(workflow, bindings) {
+    const reachable = new Set();
+    const pending = [bindings.output.nodeId];
+    while (pending.length > 0) {
+        const nodeId = pending.pop();
+        if (reachable.has(nodeId))
+            continue;
+        reachable.add(nodeId);
+        const node = workflow[nodeId];
+        if (!node)
+            continue;
+        const dependencies = [];
+        collectComfyNodeReferences(node.inputs, dependencies);
+        for (const [dependency] of dependencies) {
+            if (!reachable.has(dependency))
+                pending.push(dependency);
+        }
+    }
+    const reachableReferences = [];
+    for (const nodeId of reachable) {
+        collectComfyNodeReferences(workflow[nodeId].inputs, reachableReferences);
+    }
+    const required = [
+        [bindings.source.nodeId, 0, 'source image'],
+        [bindings.mask.nodeId, 1, 'alpha mask'],
+        [bindings.prompt.nodeId, 0, 'positive prompt'],
+        ...(bindings.negativePrompt ? [[bindings.negativePrompt.nodeId, 0, 'negative prompt']] : []),
+    ];
+    for (const [nodeId, outputIndex, label] of required) {
+        if (!reachableReferences.some(([candidateId, candidateIndex]) => candidateId === nodeId && candidateIndex === outputIndex)) {
+            throw new Error(`ComfyUI inpaint ${label} is not connected to the configured SaveImage output`);
+        }
+    }
+}
+function collectComfyNodeReferences(value, output) {
+    if (isComfyNodeReference(value)) {
+        output.push(value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            collectComfyNodeReferences(entry, output);
+    }
+    else if (isPlainRecord(value)) {
+        for (const entry of Object.values(value))
+            collectComfyNodeReferences(entry, output);
+    }
+}
+function isComfyNodeReference(value) {
+    return Array.isArray(value) && value.length === 2 && typeof value[0] === 'string'
+        && typeof value[1] === 'number' && Number.isInteger(value[1]) && value[1] >= 0;
+}
+function collectComfyPlaceholders(value, output = []) {
+    if (typeof value === 'string') {
+        const matches = value.match(/\{\{CODEBUDDY_[A-Z0-9_]+\}\}/g);
+        if (matches)
+            output.push(...matches);
+    }
+    else if (Array.isArray(value)) {
+        for (const entry of value)
+            collectComfyPlaceholders(entry, output);
+    }
+    else if (isPlainRecord(value)) {
+        for (const entry of Object.values(value))
+            collectComfyPlaceholders(entry, output);
+    }
+    return output;
+}
+function validateSafeJson(value, label, depth) {
+    if (depth > 12)
+        throw new Error(`${label} exceeds the maximum nesting depth`);
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new Error(`${label} contains a non-finite number`);
+        return;
+    }
+    if (Array.isArray(value)) {
+        if (value.length > 10_000)
+            throw new Error(`${label} contains an oversized array`);
+        for (const entry of value)
+            validateSafeJson(entry, label, depth + 1);
+        return;
+    }
+    if (!isPlainRecord(value))
+        throw new Error(`${label} contains a non-JSON value`);
+    const keys = Object.keys(value);
+    if (keys.length > 10_000 || keys.some((key) => !SAFE_COMFY_INPUT.test(key) || isDangerousKey(key))) {
+        throw new Error(`${label} contains an unsafe key`);
+    }
+    for (const entry of Object.values(value))
+        validateSafeJson(entry, label, depth + 1);
+}
+function isPlainRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function cloneJsonRecord(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function isDangerousKey(key) {
+    return key === '__proto__' || key === 'prototype' || key === 'constructor';
+}
+function isSafeComfyFilename(value) {
+    return value.length <= 255 && value !== '.' && value !== '..' && /^[A-Za-z0-9_.-]+$/.test(value);
+}
+function isSafeComfySubfolder(value) {
+    if (!value)
+        return true;
+    if (value.length > 256 || value.startsWith('/') || value.startsWith('\\'))
+        return false;
+    return value.replace(/\\/g, '/').split('/').every((segment) => SAFE_COMFY_ID.test(segment) && segment !== '.' && segment !== '..');
+}
+function isPng(bytes) {
+    return bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]));
+}
+function isImageBytesForMime(bytes, mime) {
+    if (mime === 'image/png')
+        return isPng(bytes);
+    if (mime === 'image/jpeg' || mime === 'image/jpg') {
+        return bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff;
+    }
+    return mime === 'image/webp'
+        && bytes.length >= 12
+        && bytes.subarray(0, 4).toString('ascii') === 'RIFF'
+        && bytes.subarray(8, 12).toString('ascii') === 'WEBP';
+}
+export async function readBoundedResponseBytes(response, maxBytes, timeoutMs, signal, label) {
+    const declaredLength = Number(response.headers.get('content-length') ?? '0');
+    if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+        throw new Error(`${label} exceeds ${Math.round(maxBytes / (1024 * 1024))} MB`);
+    }
+    if (!response.body)
+        throw new Error(`${label} returned an empty body`);
+    const reader = response.body.getReader();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        void reader.cancel(`${label} timed out`);
+    }, timeoutMs);
+    const onAbort = () => { void reader.cancel('aborted'); };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            throwIfAborted(signal);
+            const part = await reader.read();
+            throwIfAborted(signal);
+            if (timedOut)
+                throw new Error(`${label} body timed out after ${timeoutMs}ms`);
+            if (part.done)
+                break;
+            const chunk = Buffer.from(part.value);
+            total += chunk.length;
+            if (total > maxBytes) {
+                await reader.cancel(`${label} too large`);
+                throw new Error(`${label} exceeds ${Math.round(maxBytes / (1024 * 1024))} MB`);
+            }
+            chunks.push(chunk);
+        }
+        return Buffer.concat(chunks, total);
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
+        reader.releaseLock();
+    }
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw abortError(signal);
+}
+function abortError(signal) {
+    const error = new Error(typeof signal?.reason === 'string' ? signal.reason : 'Media generation aborted');
+    error.name = 'AbortError';
+    return error;
+}
+async function generateComfyUIImage(prompt, aspect, config, runtime, generatedAt) {
+    const fetchImpl = runtime.fetch ?? fetch;
+    const envSource = runtime.env ?? process.env;
+    const now = runtime.now ?? (() => new Date());
+    const base = config.baseUrl;
+    const negative = (env(envSource, 'CODEBUDDY_IMAGE_NEGATIVE') ?? 'blurry, low quality, deformed, watermark').trim();
+    const params = comfyParamsForModel(config.model);
+    const dims = comfyDimensionsForModel(config.model, aspect);
+    const configuredSeed = Number(env(envSource, 'CODEBUDDY_COMFYUI_SEED'));
+    const seed = Number.isFinite(configuredSeed) && configuredSeed >= 0
+        ? Math.floor(configuredSeed % 2_000_000_000)
+        : Math.floor(now().getTime() % 2_000_000_000);
+    const clientId = runtime.createId?.() ?? randomUUID();
+    const loraName = resolveComfyLoraName(envSource);
+    const loraStrength = resolveComfyLoraStrength(envSource);
+    const lora = loraName ? { name: loraName, strength: loraStrength } : undefined;
+    const workflow = isKrea2Model(config.model)
+        ? buildKrea2ComfyWorkflow(prompt, config.model, (env(envSource, 'CODEBUDDY_COMFYUI_KREA2_TEXT_ENCODER')
+            ?? 'qwen3vl_4b_fp8_scaled.safetensors').trim(), (env(envSource, 'CODEBUDDY_COMFYUI_KREA2_VAE')
+            ?? 'qwen_image_vae.safetensors').trim(), dims, params, seed, lora)
+        : buildComfyWorkflow(prompt, negative, config.model, dims, params, seed, lora);
+    const submit = await postJson(fetchImpl, joinUrl(base, '/prompt'), {
+        headers: { 'Content-Type': 'application/json' },
+        body: { prompt: workflow, client_id: clientId },
+        timeoutMs: comfyEndpointTimeout(envSource),
+        signal: runtime.signal,
+    });
+    const promptId = stringField(submit, 'prompt_id');
+    if (!promptId) {
+        const errNode = submit.error ?? submit.node_errors;
+        throw new Error(`ComfyUI rejected the workflow${errNode ? `: ${JSON.stringify(errNode).slice(0, 300)}` : ' (no prompt_id)'}`);
+    }
+    const timeoutMs = Number(env(envSource, 'CODEBUDDY_COMFYUI_TIMEOUT_MS') ?? '300000');
+    const intervalMs = Number(env(envSource, 'CODEBUDDY_COMFYUI_POLL_MS') ?? '1500');
+    const deadline = now().getTime() + (Number.isFinite(timeoutMs) ? timeoutMs : 300000);
+    let image = null;
+    for (;;) {
+        const history = await getJson(fetchImpl, joinUrl(base, `/history/${promptId}`), {
+            Accept: 'application/json',
+        }, comfyEndpointTimeout(envSource), runtime.signal);
+        const entry = history[promptId];
+        if (entry?.outputs) {
+            image = firstComfyImage(entry.outputs);
+            if (image)
+                break;
+            throw new Error(`ComfyUI finished without an image (status: ${entry.status?.status_str ?? 'unknown'})`);
+        }
+        if (now().getTime() >= deadline) {
+            throw new Error(`ComfyUI generation timed out after ${timeoutMs}ms (prompt ${promptId})`);
+        }
+        await comfyDelay(Number.isFinite(intervalMs) ? intervalMs : 1500);
+    }
+    const viewUrl = joinUrl(base, `/view?filename=${encodeURIComponent(image.filename)}&subfolder=${encodeURIComponent(image.subfolder)}&type=${encodeURIComponent(image.type)}`);
+    const viewResponse = await fetchImpl(viewUrl);
+    if (!viewResponse.ok) {
+        throw new Error(`ComfyUI /view returned ${viewResponse.status} for ${image.filename}`);
+    }
+    const bytes = await readBoundedResponseBytes(viewResponse, MAX_EDIT_REFERENCE_BYTES, 120_000, runtime.signal, 'ComfyUI image output');
+    const outputPath = await saveGeneratedAsset(bytes, {
+        rootDir: runtime.rootDir,
+        dirName: 'images',
+        prefix: 'image',
+        extension: 'png',
+        createId: runtime.createId,
+    });
+    await writeMediaSidecar(outputPath, {
+        kind: 'image',
+        prompt,
+        provider: 'comfyui',
+        model: config.model,
+        aspect_ratio: aspect,
+        generatedAt,
+    });
+    return {
+        kind: 'image_generate_result',
+        success: true,
+        image: outputPath,
+        outputPath,
+        mediaPath: `MEDIA:${outputPath}`,
+        provider: 'comfyui',
+        model: config.model,
+        prompt,
+        aspect_ratio: aspect,
+        generatedAt,
+    };
+}
+function comfyEndpointTimeout(envSource) {
+    const configured = Number(env(envSource, 'CODEBUDDY_COMFYUI_ENDPOINT_TIMEOUT_MS') ?? '10000');
+    return Number.isFinite(configured) && configured >= 250 ? configured : 10_000;
+}
+/**
+ * Declared ComfyUI fallback endpoints. Two spellings are in field use
+ * (`CODEBUDDY_COMFYUI_FALLBACK_URLS` and the shorter `COMFYUI_FALLBACK_URLS`
+ * that sits next to `COMFYUI_URL`); honour both, in that order, de-duplicated.
+ */
+function comfyFallbackUrls(envSource) {
+    const declared = ['CODEBUDDY_COMFYUI_FALLBACK_URLS', 'COMFYUI_FALLBACK_URLS'].flatMap((key) => (env(envSource, key) ?? '')
+        .split(/[\s,;]+/)
+        .map((value) => value.trim().replace(/\/+$/, ''))
+        .filter(Boolean));
+    return [...new Set(declared)];
+}
+function comfyBaseUrls(config, envSource) {
+    return [...new Set([config.baseUrl.replace(/\/+$/, ''), ...comfyFallbackUrls(envSource)])];
+}
+const HEALTHY_COMFY_TTL_MS = 5 * 60 * 1000;
+let healthyComfyEndpoint = null;
+function getPrioritizedComfyUrls(cfg, envSrc) {
+    const urls = comfyBaseUrls(cfg, envSrc);
+    if (healthyComfyEndpoint && Date.now() < healthyComfyEndpoint.expiresAt && urls.includes(healthyComfyEndpoint.url)) {
+        return [healthyComfyEndpoint.url, ...urls.filter((u) => u !== healthyComfyEndpoint.url)];
+    }
+    return urls;
+}
+export function resetHealthyComfyEndpointForTests() {
+    healthyComfyEndpoint = null;
+}
+async function generateComfyUIImageWithFallback(prompt, aspect, config, runtime, generatedAt) {
+    const envSource = runtime.env ?? process.env;
+    const declared = comfyBaseUrls(config, envSource);
+    const endpoints = getPrioritizedComfyUrls(config, envSource);
+    const failures = [];
+    for (const [index, baseUrl] of endpoints.entries()) {
+        try {
+            const isFallback = baseUrl !== declared[0];
+            const fallbackModel = env(envSource, 'CODEBUDDY_COMFYUI_FALLBACK_MODEL')?.trim();
+            const fallbackLora = env(envSource, 'CODEBUDDY_COMFYUI_FALLBACK_LORA')?.trim();
+            const endpointConfig = isFallback && fallbackModel
+                ? { ...config, model: fallbackModel, baseUrl }
+                : { ...config, baseUrl };
+            const endpointRuntime = isFallback && fallbackLora !== undefined
+                ? {
+                    ...runtime,
+                    env: {
+                        ...envSource,
+                        CODEBUDDY_COMFYUI_LORA: fallbackLora,
+                    },
+                }
+                : runtime;
+            const generated = await generateComfyUIImage(prompt, aspect, endpointConfig, endpointRuntime, generatedAt);
+            healthyComfyEndpoint = { url: baseUrl, expiresAt: Date.now() + HEALTHY_COMFY_TTL_MS };
+            return generated;
+        }
+        catch (error) {
+            // A per-endpoint fetch timeout also surfaces as AbortError. Only a caller
+            // cancellation should stop the chain; endpoint timeouts must fail over.
+            if (runtime.signal?.aborted) {
+                throw error;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            failures.push(`${baseUrl}: ${message}`);
+            const next = endpoints[index + 1];
+            if (next) {
+                logger.warn(`[comfyui] ${baseUrl} failed; trying fallback ${next}: ${message}`);
+            }
+        }
+    }
+    throw new Error(endpoints.length > 1
+        ? `All ComfyUI endpoints failed: ${failures.join(' | ')}`
+        : failures[0] ?? 'ComfyUI generation failed');
 }
 export async function generateVideo(input, runtime = {}) {
     const prompt = input.prompt.trim();
@@ -116,6 +1269,9 @@ export async function generateVideo(input, runtime = {}) {
     if (config.provider === 'fal') {
         return generateFalVideo(input, config, fetchImpl, runtime, generatedAt);
     }
+    if (config.provider === 'comfyui') {
+        return generateComfyUiH3Video(input, config, fetchImpl, runtime, generatedAt);
+    }
     return generateXaiVideo(input, config, fetchImpl, runtime, generatedAt);
 }
 async function generateXaiVideo(input, config, fetchImpl, runtime, generatedAt) {
@@ -302,6 +1458,15 @@ async function materializeVideoResult(videoUrl, options) {
     });
     const outputPath = downloaded.outputPath;
     const videoRef = outputPath ?? videoUrl;
+    await writeMediaSidecar(outputPath, {
+        kind: 'video',
+        prompt: options.prompt,
+        provider: options.provider,
+        model: options.model,
+        modality: options.modality,
+        aspect_ratio: options.aspectRatio,
+        duration: options.duration,
+    });
     return {
         kind: 'video_generate_result',
         success: true,
@@ -319,7 +1484,37 @@ async function materializeVideoResult(videoUrl, options) {
     };
 }
 function resolveImageProvider(envSource) {
-    const requested = (envSource.CODEBUDDY_IMAGE_PROVIDER ?? '').trim().toLowerCase();
+    let requested = (envSource.CODEBUDDY_IMAGE_PROVIDER ?? '').trim().toLowerCase();
+    // Prefer ComfyUI when explicitly requested OR when a ComfyUI endpoint is
+    // declared and no other provider was chosen (selfie / local-first companion
+    // path). A declared FALLBACK endpoint counts: an installation whose primary
+    // box is off keeps only fallbacks, and dropping to the cloud provider there
+    // fails with "No image generation credentials configured for provider openai"
+    // even though a reachable local ComfyUI was configured all along.
+    const declaredFallbacks = comfyFallbackUrls(envSource);
+    if (!requested &&
+        (envSource.COMFYUI_URL?.trim()
+            || envSource.CODEBUDDY_IMAGE_BASE_URL?.includes('8188')
+            || declaredFallbacks.length > 0)) {
+        requested = 'comfyui';
+    }
+    // Local ComfyUI backend (offline, GPU) — no API key, workflow-based API.
+    if (requested === 'comfyui') {
+        const baseUrl = (envSource.COMFYUI_URL
+            ?? envSource.CODEBUDDY_IMAGE_BASE_URL
+            ?? declaredFallbacks[0]
+            ?? 'http://127.0.0.1:8188').trim().replace(/\/+$/, '');
+        // Prefer CODEBUDDY_LORA_INFER_CHECKPOINT when set so LoRA train/infer stay monostack
+        // (e.g. both Krea 2). Falls back to CODEBUDDY_IMAGE_MODEL / COMFYUI_CHECKPOINT / sd_turbo.
+        const model = (envSource.CODEBUDDY_LORA_INFER_CHECKPOINT
+            ?? envSource.CODEBUDDY_IMAGE_MODEL
+            ?? envSource.COMFYUI_CHECKPOINT
+            ?? 'sd_turbo.safetensors').trim();
+        if (!baseUrl) {
+            throw new Error('No ComfyUI base URL configured (set COMFYUI_URL)');
+        }
+        return { provider: 'comfyui', model, baseUrl, apiKey: '' };
+    }
     const provider = requested === 'xai' ? 'xai' : 'openai';
     const baseUrl = (envSource.CODEBUDDY_IMAGE_BASE_URL
         ?? (provider === 'xai' ? envSource.XAI_BASE_URL : envSource.OPENAI_BASE_URL)
@@ -339,9 +1534,239 @@ function resolveImageProvider(envSource) {
     assertProviderReady(provider, effectiveApiKey, effectiveBaseUrl, 'image');
     return { provider, model, baseUrl: effectiveBaseUrl, apiKey: effectiveApiKey };
 }
+/** Snap a wanted frame count onto H3's 17k+5 grid (24 fps), within the trained range. */
+function snapH3Frames(durationSeconds) {
+    const wanted = Math.round(24 * (durationSeconds && durationSeconds > 0 ? Math.min(durationSeconds, 15) : 5));
+    const snapped = 5 + 17 * Math.max(1, Math.ceil((wanted - 5) / 17));
+    return Math.min(362, Math.max(22, snapped));
+}
+/** H3 dimensions: trained short side (default 768), aspect from "W:H", both snapped to /32. */
+function h3VideoDimensions(aspectRatio, envSource) {
+    const configured = Number(env(envSource, 'CODEBUDDY_H3_SHORT_SIDE') ?? '768');
+    const short = Number.isFinite(configured) && configured >= 256 ? Math.round(configured / 32) * 32 : 768;
+    const match = /^(\d+)\s*:\s*(\d+)$/.exec((aspectRatio ?? '16:9').trim());
+    const [w, h] = match ? [Number(match[1]), Number(match[2])] : [16, 9];
+    const ratio = w > 0 && h > 0 ? w / h : 16 / 9;
+    // Plancher au multiple de 32 : le défaut natif du nœud est 1344×768 (pas 1376).
+    const long = Math.max(32, Math.floor((short * Math.max(ratio, 1 / ratio)) / 32) * 32);
+    return ratio >= 1 ? { width: long, height: short } : { width: short, height: long };
+}
+/** Resolve a reference (data URL, http(s) URL, or local path) to bytes and upload it to ComfyUI. */
+async function uploadComfyH3Reference(fetchImpl, baseUrl, reference, index) {
+    const trimmed = reference.trim();
+    let bytes;
+    let filename = `codebuddy-h3-ref-${index}.png`;
+    const dataMatch = /^data:image\/(png|jpe?g|webp);base64,(.+)$/i.exec(trimmed);
+    if (dataMatch) {
+        bytes = Buffer.from(dataMatch[2] ?? '', 'base64');
+        filename = `codebuddy-h3-ref-${index}.${(dataMatch[1] ?? 'png').replace('jpeg', 'jpg')}`;
+    }
+    else if (/^https?:\/\//i.test(trimmed)) {
+        const response = await fetchImpl(trimmed);
+        if (!response.ok)
+            throw new Error(`Reference image fetch returned ${response.status} for ${trimmed}`);
+        bytes = Buffer.from(await response.arrayBuffer());
+    }
+    else {
+        bytes = await fs.readFile(path.resolve(trimmed));
+        filename = `codebuddy-h3-ref-${index}${path.extname(trimmed) || '.png'}`;
+    }
+    if (bytes.length === 0 || bytes.length > MAX_EDIT_REFERENCE_BYTES) {
+        throw new Error(`Reference image ${index + 1} is empty or exceeds ${MAX_EDIT_REFERENCE_BYTES} bytes`);
+    }
+    const form = new FormData();
+    form.append('image', new Blob([new Uint8Array(bytes)]), filename);
+    form.append('overwrite', 'true');
+    const response = await fetchImpl(joinUrl(baseUrl, '/upload/image'), { method: 'POST', body: form });
+    if (!response.ok)
+        throw new Error(`ComfyUI /upload/image returned ${response.status}`);
+    const body = await response.json();
+    if (!body.name)
+        throw new Error('ComfyUI /upload/image returned no file name');
+    return body.subfolder ? `${body.subfolder}/${body.name}` : body.name;
+}
+/**
+ * MiniMax H3 ref2va graph, as validated live on 2026-08-10: UNETLoader -> SigmaShift
+ * -> KSampler fed by MiniMaxH3ReferenceToVideo (autogrow refs passed NESTED under
+ * `ref_images`, prompts address them as <Picture i>), decoded twice (video + audio
+ * VAE) into CreateVideo/SaveVideo. Values only — node ids are contract-free.
+ */
+function buildMiniMaxH3VideoWorkflow(options) {
+    const e = options.envSource;
+    const unet = (env(e, 'CODEBUDDY_H3_UNET') ?? 'minimax_h3_ref2va_pruned_fp8_scaled.safetensors').trim();
+    const textEncoder = (env(e, 'CODEBUDDY_H3_TEXT_ENCODER') ?? 'qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors').trim();
+    const videoVae = (env(e, 'CODEBUDDY_H3_VIDEO_VAE') ?? 'minimax_h3_video_vae_fp16.safetensors').trim();
+    const audioVae = (env(e, 'CODEBUDDY_H3_AUDIO_VAE') ?? 'minimax_h3_audio_vae_fp32.safetensors').trim();
+    const graph = {
+        '1': { class_type: 'UNETLoader', inputs: { unet_name: unet, weight_dtype: 'default' } },
+        '2': { class_type: 'MiniMaxH3SigmaShift', inputs: { model: ['1', 0], shift_video: 12.0, shift_audio: 3.0 } },
+        '3': { class_type: 'CLIPLoader', inputs: { clip_name: textEncoder, type: 'minimax', device: 'default' } },
+        '4': { class_type: 'VAELoader', inputs: { vae_name: videoVae } },
+        '5': { class_type: 'VAELoader', inputs: { vae_name: audioVae } },
+        '7': {
+            class_type: 'MiniMaxH3ReferenceToVideo',
+            inputs: {
+                clip: ['3', 0],
+                vae: ['4', 0],
+                audio_vae: ['5', 0],
+                prompt: options.prompt,
+                width: options.width,
+                height: options.height,
+                length: options.frames,
+                ref_image_size: options.refImageSize,
+                ...(options.refNames.length > 0
+                    ? {
+                        ref_images: Object.fromEntries(options.refNames.map((_, i) => [`ref_image_${i + 1}`, [`${20 + i}`, 0]])),
+                    }
+                    : {}),
+            },
+        },
+        '8': { class_type: 'ConditioningZeroOut', inputs: { conditioning: ['7', 0] } },
+        '9': {
+            class_type: 'KSampler',
+            inputs: {
+                model: ['2', 0],
+                positive: ['7', 0],
+                negative: ['8', 0],
+                latent_image: ['7', 1],
+                seed: options.seed,
+                steps: options.steps,
+                cfg: 4.0,
+                sampler_name: 'euler',
+                scheduler: 'simple',
+                denoise: 1.0,
+            },
+        },
+        '10': { class_type: 'VAEDecode', inputs: { samples: ['9', 0], vae: ['4', 0] } },
+        '12': {
+            class_type: 'CreateVideo',
+            inputs: {
+                images: ['10', 0],
+                fps: 24.0,
+                bit_depth: 8,
+                ...(options.withAudio ? { audio: ['11', 0] } : {}),
+            },
+        },
+        '13': {
+            class_type: 'SaveVideo',
+            inputs: { video: ['12', 0], filename_prefix: 'codebuddy/h3', format: 'auto', codec: 'auto' },
+        },
+    };
+    if (options.withAudio) {
+        graph['11'] = { class_type: 'VAEDecodeAudio', inputs: { samples: ['9', 0], vae: ['5', 0] } };
+    }
+    options.refNames.forEach((name, i) => {
+        graph[`${20 + i}`] = { class_type: 'LoadImage', inputs: { image: name } };
+    });
+    return graph;
+}
+async function generateComfyUiH3Video(input, config, fetchImpl, runtime, generatedAt) {
+    const envSource = runtime.env ?? process.env;
+    const prompt = input.prompt.trim();
+    const dims = h3VideoDimensions(input.aspectRatio, envSource);
+    const frames = snapH3Frames(input.duration);
+    const now = runtime.now ?? (() => new Date());
+    const seed = input.seed !== undefined && Number.isFinite(input.seed)
+        ? Math.floor(Math.abs(input.seed) % 2_000_000_000)
+        : Math.floor(now().getTime() % 2_000_000_000);
+    const configuredSteps = Number(env(envSource, 'CODEBUDDY_H3_STEPS') ?? '30');
+    const steps = Number.isFinite(configuredSteps) && configuredSteps >= 4 ? Math.min(60, Math.floor(configuredSteps)) : 30;
+    const refImageSize = (env(envSource, 'CODEBUDDY_H3_REF_SIZE') ?? 'max').trim() === 'match' ? 'match' : 'max';
+    const references = [
+        ...(input.imageUrl?.trim() ? [input.imageUrl.trim()] : []),
+        ...(input.referenceImageUrls ?? []).map((value) => value.trim()).filter(Boolean),
+    ].slice(0, 9);
+    const refNames = [];
+    for (const [index, reference] of references.entries()) {
+        refNames.push(await uploadComfyH3Reference(fetchImpl, config.baseUrl, reference, index));
+    }
+    const workflow = buildMiniMaxH3VideoWorkflow({
+        prompt,
+        width: dims.width,
+        height: dims.height,
+        frames,
+        seed,
+        steps,
+        refImageSize,
+        refNames,
+        withAudio: input.audio !== false,
+        envSource,
+    });
+    const submit = await postJson(fetchImpl, joinUrl(config.baseUrl, '/prompt'), {
+        headers: {},
+        body: { prompt: workflow, client_id: runtime.createId?.() ?? randomUUID() },
+        timeoutMs: 60_000,
+    });
+    const promptId = stringField(submit, 'prompt_id');
+    if (!promptId) {
+        throw new Error(`ComfyUI /prompt returned no prompt_id: ${JSON.stringify(submit).slice(0, 300)}`);
+    }
+    const timeoutMs = Number(env(envSource, 'CODEBUDDY_H3_TIMEOUT_MS') ?? '1800000');
+    const intervalMs = Number(env(envSource, 'CODEBUDDY_H3_POLL_MS') ?? '5000');
+    const deadline = Date.now() + (Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 1_800_000);
+    let videoRef;
+    while (Date.now() < deadline) {
+        const history = await getJson(fetchImpl, joinUrl(config.baseUrl, `/history/${promptId}`), {});
+        const entry = objectField(history, promptId);
+        if (entry) {
+            const status = objectField(entry, 'status');
+            const statusStr = status ? stringField(status, 'status_str') : undefined;
+            if (statusStr === 'error') {
+                throw new Error(`ComfyUI H3 execution failed: ${JSON.stringify(status).slice(0, 500)}`);
+            }
+            const outputs = objectField(entry, 'outputs');
+            if (outputs) {
+                for (const nodeOutput of Object.values(outputs)) {
+                    if (!nodeOutput || typeof nodeOutput !== 'object')
+                        continue;
+                    const images = nodeOutput.images;
+                    if (!Array.isArray(images))
+                        continue;
+                    for (const item of images) {
+                        if (item && typeof item === 'object' && typeof item.filename === 'string'
+                            && /\.(mp4|webm|mov)$/i.test(item.filename)) {
+                            const found = item;
+                            videoRef = { filename: found.filename, subfolder: found.subfolder ?? '', type: found.type ?? 'output' };
+                        }
+                    }
+                }
+                if (videoRef)
+                    break;
+            }
+        }
+        await sleep(Math.max(100, Number.isFinite(intervalMs) ? intervalMs : 5000));
+    }
+    if (!videoRef) {
+        throw new Error(`Timed out waiting for ComfyUI H3 video after ${timeoutMs}ms (prompt ${promptId})`);
+    }
+    const viewUrl = joinUrl(config.baseUrl, `/view?filename=${encodeURIComponent(videoRef.filename)}&subfolder=${encodeURIComponent(videoRef.subfolder)}&type=${encodeURIComponent(videoRef.type)}`);
+    return materializeVideoResult(viewUrl, {
+        runtime,
+        fetchImpl,
+        provider: 'comfyui',
+        model: config.model,
+        prompt,
+        modality: references.length > 0 ? 'image' : 'text',
+        aspectRatio: input.aspectRatio?.trim() || '16:9',
+        duration: frames / 24,
+        generatedAt,
+        requestId: promptId,
+        endpoint: config.baseUrl,
+    });
+}
 function resolveVideoProvider(modelOverride, envSource) {
     const requested = (envSource.CODEBUDDY_VIDEO_PROVIDER ?? '').trim().toLowerCase();
-    const provider = requested === 'fal' ? 'fal' : 'xai';
+    const provider = requested === 'fal' ? 'fal'
+        : requested === 'comfyui' ? 'comfyui'
+            : 'xai';
+    if (provider === 'comfyui') {
+        // Local ComfyUI running the MiniMax H3 graph (self-hosted, no credentials).
+        const comfyBase = (envSource.CODEBUDDY_VIDEO_BASE_URL
+            ?? envSource.COMFYUI_URL
+            ?? 'http://127.0.0.1:8188').trim().replace(/\/+$/, '');
+        const comfyModel = (modelOverride ?? envSource.CODEBUDDY_VIDEO_MODEL ?? 'minimax-h3').trim();
+        return { provider, model: comfyModel, baseUrl: comfyBase, apiKey: '' };
+    }
     const baseUrl = (envSource.CODEBUDDY_VIDEO_BASE_URL
         ?? (provider === 'fal' ? envSource.FAL_BASE_URL : envSource.XAI_BASE_URL)
         ?? (provider === 'fal' ? 'https://queue.fal.run' : 'https://api.x.ai/v1')).trim().replace(/\/+$/, '');
@@ -373,6 +1798,61 @@ function resolveImageAspect(value) {
     }
     return 'landscape';
 }
+const MAX_EDIT_REFERENCE_BYTES = 50 * 1024 * 1024;
+function validateImageReference(value, label) {
+    const trimmed = value.trim();
+    if (/^data:image\/(?:png|jpe?g|webp);base64,/i.test(trimmed)) {
+        validateDataImage(trimmed, label);
+        return trimmed;
+    }
+    if (/^https:\/\//i.test(trimmed))
+        return trimmed;
+    throw new Error(`${label} must be an HTTPS URL or a base64 image data URL`);
+}
+function validateDataImage(value, label) {
+    const match = value.match(/^data:(image\/(?:png|jpe?g|webp));base64,([A-Za-z0-9+/=]+)$/i);
+    if (!match)
+        throw new Error(`${label} must be a PNG, JPEG, or WebP base64 data URL`);
+    const estimatedBytes = Math.floor((match[2].length * 3) / 4);
+    if (estimatedBytes <= 0 || estimatedBytes > MAX_EDIT_REFERENCE_BYTES) {
+        throw new Error(`${label} must be smaller than 50 MB`);
+    }
+    return value;
+}
+function dataUrlToBlob(value, label) {
+    validateDataImage(value, label);
+    const comma = value.indexOf(',');
+    const mime = value.slice(5, value.indexOf(';'));
+    const bytes = Buffer.from(value.slice(comma + 1), 'base64');
+    return new Blob([bytes], { type: mime });
+}
+function normalizeEditSelections(value) {
+    return (value ?? []).slice(0, 20).flatMap((selection) => {
+        const x = clampUnit(selection?.x);
+        const y = clampUnit(selection?.y);
+        const width = Math.min(clampUnit(selection?.width), 1 - x);
+        const height = Math.min(clampUnit(selection?.height), 1 - y);
+        if (width < 0.002 || height < 0.002)
+            return [];
+        return [{ x, y, width, height }];
+    });
+}
+function clampUnit(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.max(0, Math.min(1, value));
+}
+function redactDataUrl(value) {
+    return value.startsWith('data:') ? `[inline image ${Math.round(value.length / 1024)} KiB]` : value;
+}
+function sanitizeImageSourceReference(value) {
+    const reference = value?.trim();
+    if (!reference || reference.length > 4_096
+        || [...reference].some((character) => character.charCodeAt(0) < 0x20 || character.charCodeAt(0) === 0x7f)) {
+        return undefined;
+    }
+    return reference.startsWith('data:') ? undefined : reference;
+}
 function aspectToProviderRatio(aspect) {
     if (aspect === 'square')
         return '1:1';
@@ -391,11 +1871,11 @@ async function postJson(fetchImpl, url, options) {
         method: 'POST',
         headers: options.headers,
         body: JSON.stringify(options.body),
-    }, options.timeoutMs ?? 120_000);
+    }, options.timeoutMs ?? 120_000, options.signal);
     return readJsonResponse(response, url);
 }
-async function getJson(fetchImpl, url, headers) {
-    const response = await fetchWithTimeout(fetchImpl, url, { headers }, 60_000);
+async function getJson(fetchImpl, url, headers, timeoutMs = 60_000, signal) {
+    const response = await fetchWithTimeout(fetchImpl, url, { headers }, timeoutMs, signal);
     return readJsonResponse(response, url);
 }
 async function readJsonResponse(response, url) {
@@ -454,7 +1934,7 @@ async function tryDownloadAsset(url, options) {
     if (!response.ok) {
         return {};
     }
-    const bytes = Buffer.from(await response.arrayBuffer());
+    const bytes = await readBoundedResponseBytes(response, options.maxBytes, 120_000, undefined, 'Generated media download');
     if (bytes.length <= 0 || bytes.length > options.maxBytes) {
         return {};
     }
@@ -468,23 +1948,85 @@ async function tryDownloadAsset(url, options) {
     });
     return { outputPath };
 }
+/**
+ * Sidecar metadata next to a generated asset (`<file>.meta.json`) so the
+ * media library can show the ORIGINAL prompt/provider/model (ChatGPT-library
+ * parity) and regenerate variants from the real prompt. Fail-open: metadata
+ * must never break a successful generation.
+ */
+export async function writeMediaSidecar(outputPath, meta) {
+    if (!outputPath)
+        return;
+    try {
+        await fs.writeFile(`${outputPath}.meta.json`, JSON.stringify(meta, null, 1));
+    }
+    catch {
+        /* sidecar is best-effort */
+    }
+}
 async function saveGeneratedAsset(bytes, options) {
     const rootDir = path.resolve(options.rootDir ?? process.cwd());
+    const rootReal = await fs.realpath(rootDir);
     const id = sanitizeId(options.createId?.() ?? `${Date.now()}-${randomUUID()}`);
-    const outputDir = path.join(rootDir, '.codebuddy', 'media-generation', options.dirName);
-    await fs.mkdir(outputDir, { recursive: true });
+    if (!/^[A-Za-z0-9_.-]{1,64}$/.test(options.dirName)
+        || !/^[A-Za-z0-9_.-]{1,64}$/.test(options.prefix)
+        || !/^[A-Za-z0-9]{2,5}$/.test(options.extension)) {
+        throw new Error('Generated media output configuration is invalid');
+    }
+    const outputDir = await ensureConfinedMediaDirectory(rootDir, rootReal, [
+        '.codebuddy',
+        'media-generation',
+        options.dirName,
+    ]);
     const outputPath = path.join(outputDir, `${options.prefix}-${id}.${options.extension}`);
-    await fs.writeFile(outputPath, bytes);
+    const flags = fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | (fsConstants.O_NOFOLLOW ?? 0);
+    const handle = await fs.open(outputPath, flags, 0o600);
+    try {
+        await handle.writeFile(bytes);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
     return outputPath;
 }
-async function fetchWithTimeout(fetchImpl, url, init, timeoutMs) {
+export async function ensureConfinedMediaDirectory(rootPath, rootReal, segments) {
+    let cursor = rootPath;
+    for (const segment of segments) {
+        cursor = path.join(cursor, segment);
+        try {
+            await fs.mkdir(cursor, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        const metadata = await fs.lstat(cursor);
+        if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+            throw new Error('Generated media output directory contains a symbolic link');
+        }
+        const cursorReal = await fs.realpath(cursor);
+        const child = path.relative(rootReal, cursorReal);
+        if (child === '..' || child.startsWith(`..${path.sep}`) || path.isAbsolute(child)) {
+            throw new Error('Generated media output directory escapes its workspace');
+        }
+    }
+    return fs.realpath(cursor);
+}
+async function fetchWithTimeout(fetchImpl, url, init, timeoutMs, signal) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    const onAbort = () => controller.abort();
+    if (signal?.aborted)
+        controller.abort();
+    else
+        signal?.addEventListener('abort', onAbort, { once: true });
     try {
         return await fetchImpl(url, { ...init, signal: controller.signal });
     }
     finally {
         clearTimeout(timeout);
+        signal?.removeEventListener('abort', onAbort);
     }
 }
 function joinUrl(baseUrl, suffix) {