Add Image v2 as a sibling of Image edit, with separate Klein graphs.

Keep the v1 Image tab on its dual-branch template. The host agent follows Desktop's live port so Coolify stays on :8198.

Co-authored-by: Cursor <cursoragent@cursor.com>

server/utils/comfy.ts

@@ -15,8 +15,8 @@ export function comfyConfigured() {
 function comfyBase() {
   if (comfyHostOverride) return comfyHostOverride
   const config = useRuntimeConfig()
-  let host = String(config.comfyHost || process.env.COMFY_HOST || '').trim().replace(/\/$/, '')
-  const port = String(config.comfyPort || process.env.COMFY_PORT || '').trim()
+  let host = String(process.env.COMFY_HOST || config.comfyHost || '').trim().replace(/\/$/, '')
+  const port = String(process.env.COMFY_PORT || config.comfyPort || '').trim()
   if (!host) {
     throw createError({ statusCode: 500, statusMessage: 'COMFY_HOST is not configured' })
   }

server/utils/generationPresets.ts

@@ -14,6 +14,18 @@ import {
   type ImagePresetSettings,
   type VideoPresetSettings
 } from '~/utils/generationPresets'
+import {
+  IMAGE_V2_CFG_DEFAULT,
+  IMAGE_V2_CONSISTENCY_CLIP,
+  IMAGE_V2_CONSISTENCY_MODEL,
+  IMAGE_V2_SNOFS_CLIP,
+  IMAGE_V2_SNOFS_MODEL,
+  IMAGE_V2_STEPS_DEFAULT,
+  clampImageV2Strength,
+  parseImageV2Mode,
+  parseImageV2Task,
+  type ImageV2PresetSettings
+} from '~/utils/imageV2'
 import { coerceVideoWorkflow, isXaigenStudio, parseVideoWorkflow } from '~/utils/videoModels'
 
 const writeChains = new Map<string, Promise<unknown>>()
@@ -96,6 +108,31 @@ function sanitizeImageSettings(raw: unknown): ImagePresetSettings {
   }
 }
 
+function sanitizeImageV2Settings(raw: unknown): ImageV2PresetSettings {
+  const rec = raw && typeof raw === 'object' ? raw as Record<string, unknown> : {}
+  const mode = parseImageV2Mode(rec.mode) || 'edit'
+  const turbo = rec.turbo === true
+  return {
+    mode,
+    task: mode === 'compose' ? parseImageV2Task(rec.task, 'scene') : 'scene',
+    negative: String(rec.negative || '').slice(0, 2000),
+    snofsModel: clampImageV2Strength(rec.snofsModel ?? rec.snofs_model, IMAGE_V2_SNOFS_MODEL),
+    snofsClip: clampImageV2Strength(rec.snofsClip ?? rec.snofs_clip, IMAGE_V2_SNOFS_CLIP),
+    consistencyModel: clampImageV2Strength(rec.consistencyModel ?? rec.consistency_model, IMAGE_V2_CONSISTENCY_MODEL),
+    consistencyClip: clampImageV2Strength(rec.consistencyClip ?? rec.consistency_clip, IMAGE_V2_CONSISTENCY_CLIP),
+    steps: turbo ? 8 : clampImageSteps(rec.steps, IMAGE_V2_STEPS_DEFAULT),
+    cfg: turbo ? 1 : clampImageCfg(rec.cfg, IMAGE_V2_CFG_DEFAULT),
+    megapixels: clampImageScaleMegapixels(rec.megapixels ?? rec.scaleMegapixels, 1),
+    turbo
+  }
+}
+
+function sanitizeSettings(kind: GenerationPresetKind, raw: unknown) {
+  if (kind === 'image') return sanitizeImageSettings(raw)
+  if (kind === 'imagev2') return sanitizeImageV2Settings(raw)
+  return sanitizeVideoSettings(raw)
+}
+
 function normalizeStoredPreset(raw: unknown): GenerationPreset | null {
   if (!raw || typeof raw !== 'object') return null
   const rec = raw as Record<string, unknown>
@@ -111,7 +148,7 @@ function normalizeStoredPreset(raw: unknown): GenerationPreset | null {
     createdAt,
     updatedAt: Number(rec.updatedAt) || createdAt,
     loraStack: normalizeLoraStack(rec.loraStack),
-    settings: kind === 'image' ? sanitizeImageSettings(rec.settings) : sanitizeVideoSettings(rec.settings)
+    settings: sanitizeSettings(kind, rec.settings)
   }
 }
 
@@ -147,7 +184,7 @@ export async function saveGenerationPreset(owner: string, input: {
   const kind = parseGenerationPresetKind(input.kind)
   const xaigen = isXaigenStudio()
   const loraStack = filterLoraStackForStudio(input.loraStack, xaigen)
-  const settings = kind === 'image' ? sanitizeImageSettings(input.settings) : sanitizeVideoSettings(input.settings)
+  const settings = sanitizeSettings(kind, input.settings)
   const now = Date.now()
   return mutate(owner, (presets) => {
     const existing = presets.find(item => item.kind === kind && item.name.toLowerCase() === name.toLowerCase())

server/utils/imageChainV2.ts

@@ -0,0 +1,168 @@
+import { createJob, emitJob, type Job } from '~/server/utils/jobs'
+import { ensureComfyReady } from '~/server/utils/comfyLifecycle'
+import { assertImageScaleToTotalPixelsNode, getComfyHost, uploadImage, queuePrompt, purgeComfyArtifacts } from '~/server/utils/comfy'
+import { withImageComfyHost, waitForImageEdit, downloadEditedImage } from '~/server/utils/imageComfy'
+import { buildImageV2Workflow } from '~/server/utils/imageWorkflowV2'
+import { ensureComfyLoraNames } from '~/server/utils/loras'
+import { imageDimensions } from '~/server/utils/resolution'
+import { emitChainJob } from '~/server/utils/watch'
+import { saveStill } from '~/server/utils/library'
+import type { ImageV2Mode, ImageV2Task } from '~/utils/imageV2'
+import type { EditImageFile } from '~/server/utils/imageChain'
+
+export type EditV2RunParams = {
+  mode: ImageV2Mode
+  task: ImageV2Task
+  image: EditImageFile
+  reference: EditImageFile | null
+  prompt: string
+  negative: string
+  steps: number
+  seed: number
+  cfg: number
+  snofsModel: number
+  snofsClip: number
+  consistencyModel: number
+  consistencyClip: number
+  megapixels: number
+}
+
+export async function runEditV2(job: Job, params: EditV2RunParams) {
+  const library = job.library
+  if (!library) throw new Error('Edit job is missing library metadata')
+  if (params.mode === 'compose' && !params.reference) {
+    throw new Error('Compose requires image B. Refusing to fall back to one-image generation.')
+  }
+  if (params.mode === 'edit' && params.reference) {
+    throw new Error('Edit mode takes one image. Use Compose for two stills.')
+  }
+
+  try {
+    await ensureComfyReady((status) => {
+      emitChainJob(job, {
+        type: status.state === 'busy' ? 'busy' : 'status',
+        message: status.message,
+        progress: status.state === 'online' ? Math.max(job.progress, 6) : Math.max(job.progress, 3),
+        busy: status.state === 'busy'
+      })
+    }, { skipBusyWait: true })
+    if (job.status === 'cancelled') throw new Error('Job interrupted.')
+    job.imageComfyHost = getComfyHost()
+
+    await withImageComfyHost(job.imageComfyHost, async () => {
+      emitChainJob(job, {
+        type: 'status',
+        message: params.mode === 'compose' ? 'Uploading stills A and B to Beast...' : 'Uploading still A to Beast...',
+        progress: 8
+      })
+      const uploaded = await uploadImage(params.image, job.id)
+      const uploadedRef = params.reference
+        ? await uploadImage({
+          ...params.reference,
+          filename: `ref_${params.reference.filename || 'image_b.png'}`
+        }, job.id)
+        : null
+      if (job.status === 'cancelled') throw new Error('Job interrupted.')
+
+      emitChainJob(job, {
+        type: 'status',
+        message: params.mode === 'compose'
+          ? `Queueing Klein v2 compose (${params.task}) on Beast...`
+          : 'Queueing Klein v2 edit on Beast...',
+        progress: 12
+      })
+      await ensureComfyLoraNames('image')
+      await assertImageScaleToTotalPixelsNode()
+      const built = buildImageV2Workflow({
+        mode: params.mode,
+        task: params.task,
+        prompt: params.prompt,
+        negative: params.negative,
+        imageAName: uploaded.name,
+        imageBName: uploadedRef?.name,
+        snofsModel: params.snofsModel,
+        snofsClip: params.snofsClip,
+        consistencyModel: params.consistencyModel,
+        consistencyClip: params.consistencyClip,
+        steps: params.steps,
+        cfg: params.cfg,
+        seed: params.seed,
+        megapixels: params.megapixels,
+        filenamePrefix: `aigen_v2_${job.id.slice(0, 8)}`
+      })
+      const queued = await queuePrompt(built.graph, job.clientId)
+      job.promptId = queued.prompt_id
+      job.status = 'running'
+      emitChainJob(job, {
+        type: 'status',
+        message: `Running ${built.workflowFile}...`,
+        progress: 18,
+        maxStep: params.steps
+      })
+
+      const output = await waitForImageEdit({
+        promptId: queued.prompt_id,
+        clientId: job.clientId,
+        timeoutMs: 10 * 60 * 1000,
+        onProgress: (event) => {
+          emitChainJob(job, {
+            type: 'status',
+            message: event.message,
+            progress: event.progress,
+            step: event.step,
+            maxStep: event.maxStep || params.steps,
+            node: event.node
+          })
+        },
+        isCancelled: () => job.status === 'cancelled'
+      })
+
+      emitChainJob(job, { type: 'status', message: 'Saving Klein v2 still...', progress: 94 })
+      const buffer = await downloadEditedImage(output)
+      const size = imageDimensions(buffer)
+      const still = await saveStill({
+        ownerKey: library.ownerKey,
+        folderId: library.folderId,
+        filename: output.filename,
+        data: buffer,
+        width: size?.width || 0,
+        height: size?.height || 0,
+        hideInput: job.hideThumbnail === true,
+        role: 'output',
+        name: library.name || undefined,
+        prompt: built.prompt
+      })
+      job.stillId = still?.id
+      await purgeComfyArtifacts({
+        video: { filename: output.filename, subfolder: output.subfolder, type: output.type },
+        imageName: uploaded.name,
+        imageSubfolder: uploaded.subfolder,
+        extraImageNames: uploadedRef?.name ? [uploadedRef.name] : [],
+        promptId: job.promptId
+      })
+
+      job.status = 'complete'
+      emitChainJob(job, {
+        type: 'complete',
+        message: 'Klein v2 finished on Beast',
+        progress: 100,
+        stillId: still?.id,
+        filename: output.filename,
+        subfolder: output.subfolder,
+        mediaType: 'image',
+        hideThumbnail: job.hideThumbnail,
+        folderLocked: library.folderLocked
+      })
+    })
+  } catch (error) {
+    if (job.status !== 'error' && job.status !== 'cancelled') {
+      const message = error instanceof Error ? error.message : String(error)
+      job.status = 'error'
+      job.error = message
+      emitJob(job, { type: 'error', error: message, message })
+    }
+  } finally {
+    const { onLiveVideoSettled } = await import('~/server/utils/studioQueue')
+    await onLiveVideoSettled(job)
+  }
+}

server/utils/imageComfy.ts

@@ -292,7 +292,7 @@ export async function waitForImageEdit(opts: {
       if (payload.type === 'executing' && payload.data?.node) {
         opts.onProgress?.({
           message: 'Running Flux.2 Klein...',
-          progress: payload.data.node === '9' || payload.data.node === '94' ? 92 : 30,
+          progress: payload.data.node === '9' || payload.data.node === '94' || payload.data.node === '21' ? 92 : 30,
           node: payload.data.node
         })
       }

server/utils/imageWorkflowV2.ts

@@ -0,0 +1,193 @@
+import editTemplate from '../assets/klein_v2_edit.json'
+import composeTemplate from '../assets/klein_v2_compose.json'
+import { IMAGE_SCALE_TO_TOTAL_PIXELS } from '~/server/utils/comfy'
+import { cachedComfyLoraNames } from '~/server/utils/loras'
+import { resolveComfyLoraName, loraIdentityKey } from '~/utils/loras'
+import { clampImageCfg, clampImageScaleMegapixels, clampImageSteps } from '~/utils/generationPresets'
+import {
+  IMAGE_V2_CONSISTENCY_CLIP,
+  IMAGE_V2_CONSISTENCY_LORA,
+  IMAGE_V2_CONSISTENCY_MODEL,
+  IMAGE_V2_SNOFS_CLIP,
+  IMAGE_V2_SNOFS_LORA,
+  IMAGE_V2_SNOFS_MODEL,
+  clampImageV2Strength,
+  composeImageV2Prompt,
+  type ImageV2Mode,
+  type ImageV2Task
+} from '~/utils/imageV2'
+
+type WorkflowNode = { class_type: string; inputs: Record<string, unknown>; _meta?: { title?: string } }
+type WorkflowGraph = Record<string, WorkflowNode>
+
+const LOAD_A = '1'
+const LOAD_B = '22'
+const SCALE_A = '2'
+const SCALE_B = '23'
+const PROMPT = '9'
+const NEGATIVE = '10'
+const NOISE = '15'
+const SCHEDULER = '17'
+const CFG = '18'
+const SAVE = '21'
+const SNOFS = '7'
+const CONSISTENCY = '8'
+
+export const IMAGE_V2_EDIT_WORKFLOW = 'klein_v2_edit.json'
+export const IMAGE_V2_COMPOSE_WORKFLOW = 'klein_v2_compose.json'
+
+export interface ImageV2BuildParams {
+  mode: ImageV2Mode
+  task: ImageV2Task
+  prompt: string
+  negative?: string
+  imageAName: string
+  imageBName?: string
+  snofsModel?: number
+  snofsClip?: number
+  consistencyModel?: number
+  consistencyClip?: number
+  steps: number
+  cfg: number
+  seed: number
+  megapixels?: number
+  filenamePrefix?: string
+}
+
+function setInput(graph: WorkflowGraph, id: string, key: string, value: unknown) {
+  if (graph[id]) graph[id].inputs[key] = value
+}
+
+function loadImageNames(graph: WorkflowGraph) {
+  return Object.entries(graph)
+    .filter(([, node]) => node.class_type === 'LoadImage')
+    .map(([id, node]) => ({
+      id,
+      title: String(node._meta?.title || id),
+      image: String(node.inputs.image || '')
+    }))
+}
+
+function resolveRequiredLora(wanted: string, label: string) {
+  const names = cachedComfyLoraNames('image')
+  const resolved = names.length ? resolveComfyLoraName(wanted, names) : wanted
+  const hit = names.some(name => loraIdentityKey(name) === loraIdentityKey(wanted) || loraIdentityKey(name) === loraIdentityKey(resolved))
+  if (names.length && !hit) {
+    throw createError({ statusCode: 503, statusMessage: `Missing ${label} LoRA (${wanted}) on Beast Comfy` })
+  }
+  return resolved
+}
+
+function patchScaleMegapixels(graph: WorkflowGraph, megapixels: number) {
+  const mp = clampImageScaleMegapixels(megapixels)
+  for (const node of Object.values(graph)) {
+    if (node.class_type !== IMAGE_SCALE_TO_TOTAL_PIXELS) continue
+    node.inputs.megapixels = mp
+    node.inputs.upscale_method = 'lanczos'
+  }
+}
+
+export function assertImageV2Graph(graph: WorkflowGraph, mode: ImageV2Mode, imageBName?: string) {
+  const loaders = loadImageNames(graph)
+  if (mode === 'compose') {
+    if (loaders.length < 2) {
+      throw createError({
+        statusCode: 500,
+        statusMessage: 'Compose graph has no second image input. Refusing to run a one-image fallback.'
+      })
+    }
+    const b = graph[LOAD_B]
+    if (!b || b.class_type !== 'LoadImage' || !String(b.inputs.image || '').trim()) {
+      throw createError({
+        statusCode: 500,
+        statusMessage: 'Compose job is missing Load Image B. Refusing to run.'
+      })
+    }
+  }
+  if (imageBName && loaders.length < 2) {
+    throw createError({
+      statusCode: 500,
+      statusMessage: 'image_b was sent but the executed graph has no second image input.'
+    })
+  }
+  const promptNode = graph[PROMPT]
+  if (!promptNode || promptNode.class_type !== 'CLIPTextEncode') {
+    throw createError({ statusCode: 500, statusMessage: 'v2 graph is missing the positive CLIPTextEncode node.' })
+  }
+  if (Array.isArray(promptNode.inputs.text)) {
+    throw createError({ statusCode: 500, statusMessage: 'v2 prompt is a subgraph link. Refusing to run with a leftover widget prompt.' })
+  }
+  if (!String(promptNode.inputs.text || '').trim()) {
+    throw createError({ statusCode: 400, statusMessage: 'v2 prompt was not patched onto the graph.' })
+  }
+}
+
+export function buildImageV2Workflow(params: ImageV2BuildParams) {
+  const compose = params.mode === 'compose'
+  const graph = structuredClone(compose ? composeTemplate : editTemplate) as WorkflowGraph
+  const prompt = composeImageV2Prompt(params.mode, params.task, params.prompt)
+  const negative = String(params.negative || '')
+  const snofsModel = clampImageV2Strength(params.snofsModel, IMAGE_V2_SNOFS_MODEL)
+  const snofsClip = clampImageV2Strength(params.snofsClip, IMAGE_V2_SNOFS_CLIP)
+  const consistencyModel = clampImageV2Strength(params.consistencyModel, IMAGE_V2_CONSISTENCY_MODEL)
+  const consistencyClip = clampImageV2Strength(params.consistencyClip, IMAGE_V2_CONSISTENCY_CLIP)
+  const steps = clampImageSteps(params.steps, 24)
+  const cfg = clampImageCfg(params.cfg, 4)
+  const workflowFile = compose ? IMAGE_V2_COMPOSE_WORKFLOW : IMAGE_V2_EDIT_WORKFLOW
+
+  setInput(graph, LOAD_A, 'image', params.imageAName)
+  if (compose) setInput(graph, LOAD_B, 'image', params.imageBName || '')
+  setInput(graph, PROMPT, 'text', prompt)
+  setInput(graph, NEGATIVE, 'text', negative)
+  setInput(graph, NOISE, 'noise_seed', params.seed)
+  setInput(graph, SCHEDULER, 'steps', steps)
+  setInput(graph, CFG, 'cfg', cfg)
+  setInput(graph, SAVE, 'filename_prefix', params.filenamePrefix || 'aigen-v2')
+  patchScaleMegapixels(graph, params.megapixels ?? 1)
+
+  setInput(graph, SNOFS, 'lora_name', resolveRequiredLora(IMAGE_V2_SNOFS_LORA, 'SNOFS'))
+  setInput(graph, SNOFS, 'strength_model', snofsModel)
+  setInput(graph, SNOFS, 'strength_clip', snofsClip)
+  setInput(graph, CONSISTENCY, 'lora_name', resolveRequiredLora(IMAGE_V2_CONSISTENCY_LORA, 'Consistency'))
+  setInput(graph, CONSISTENCY, 'strength_model', consistencyModel)
+  setInput(graph, CONSISTENCY, 'strength_clip', consistencyClip)
+
+  assertImageV2Graph(graph, params.mode, params.imageBName)
+
+  const loaders = loadImageNames(graph)
+  console.log(JSON.stringify({
+    src: 'image-v2',
+    workflow: workflowFile,
+    mode: params.mode,
+    task: params.task,
+    loadImage: Object.fromEntries(loaders.map(item => [item.id, { title: item.title, file: item.image }])),
+    loras: {
+      snofs: { name: graph[SNOFS]?.inputs.lora_name, model: snofsModel, clip: snofsClip },
+      consistency: { name: graph[CONSISTENCY]?.inputs.lora_name, model: consistencyModel, clip: consistencyClip }
+    },
+    steps,
+    cfg,
+    seed: params.seed,
+    megapixels: clampImageScaleMegapixels(params.megapixels ?? 1)
+  }))
+
+  return { graph, workflowFile, loaders, prompt }
+}
+
+export const IMAGE_V2_NODE_LABELS: Record<string, string> = {
+  '1': 'Loading image A',
+  '22': 'Loading image B',
+  '2': 'Scaling image A',
+  '23': 'Scaling image B',
+  '4': 'Loading Flux.2 Klein 9B',
+  '5': 'Loading CLIP',
+  '6': 'Loading VAE',
+  '7': 'Applying SNOFS',
+  '8': 'Applying Consistency',
+  '9': 'Encoding prompt',
+  '11': 'Encoding image A',
+  '24': 'Encoding image B',
+  '19': 'Sampling Klein v2',
+  '20': 'Decoding still',
+  '21': 'Saving still'
+}

server/utils/studioQueue.ts

@@ -51,6 +51,13 @@ export interface StudioJobPayload {
   referenceStillFilename?: string
   scaleToTotalPixels?: boolean
   scaleMegapixels?: number
+  imagePipeline?: 'v1' | 'v2'
+  v2Mode?: 'edit' | 'compose'
+  v2Task?: 'scene' | 'identity' | 'outfit' | 'face_lock'
+  snofsModel?: number
+  snofsClip?: number
+  consistencyModel?: number
+  consistencyClip?: number
 }
 
 export interface StudioJob {
@@ -210,6 +217,7 @@ export function summarizeStudioJob(job: StudioJob) {
     liveJobId: job.liveJobId,
     stillId: job.payload.stillId,
     workflow: job.payload.workflow,
+    imagePipeline: job.payload.imagePipeline || 'v1',
     duration: job.payload.duration,
     hideThumbnail: job.payload.hideThumbnail,
     folderLocked: job.payload.folderLocked === true,
@@ -665,6 +673,7 @@ async function startStudioEditJob(item: StudioJob) {
     const { stillPath } = await import('~/server/utils/library')
     const { existsSync, readFileSync } = await import('node:fs')
     const { createEditLiveJob, runEdit } = await import('~/server/utils/imageChain')
+    const { runEditV2 } = await import('~/server/utils/imageChainV2')
 
     const payload = item.payload
     if (!payload.stillId || !existsSync(stillPath(item.ownerKey, payload.stillId))) {
@@ -684,6 +693,66 @@ async function startStudioEditJob(item: StudioJob) {
       }
       : null
 
+    if (payload.imagePipeline === 'v2') {
+      const mode = payload.v2Mode === 'compose' ? 'compose' : 'edit'
+      if (mode === 'compose' && !reference) {
+        throw new Error('Compose requires image B. Refusing to fall back to one-image generation.')
+      }
+      if (mode === 'edit' && reference) {
+        throw new Error('Edit mode takes one image. Use Compose for two stills.')
+      }
+      live = createEditLiveJob({
+        steps: payload.steps,
+        hideThumbnail: payload.hideThumbnail,
+        library: {
+          ownerKey: item.ownerKey,
+          folderId: payload.folderId,
+          hideThumbnail: payload.hideThumbnail,
+          hideInput: payload.hideInput,
+          folderLocked: payload.folderLocked,
+          name: payload.name,
+          prompt: payload.prompt,
+          aspect: payload.aspect || 'auto',
+          width: payload.width,
+          height: payload.height,
+          steps: payload.steps,
+          turbo: payload.turbo === true,
+          seed: payload.seed || Math.floor(Math.random() * 2_147_483_647),
+          cfg: payload.cfg,
+          stillId: payload.stillId,
+          stillFilename: payload.stillFilename,
+          familyId: item.familyId,
+          chainIndex: 0,
+          chainStep: 1,
+          chainTotal: 1
+        }
+      })
+      await markStudioLive(item.ownerKey, item.id, live.id)
+      void runEditV2(live, {
+        mode,
+        task: payload.v2Task || 'scene',
+        image,
+        reference,
+        prompt: payload.prompt,
+        negative: payload.negative || '',
+        steps: payload.steps,
+        seed: live.library?.seed || payload.seed,
+        cfg: payload.cfg,
+        snofsModel: payload.snofsModel ?? 0.65,
+        snofsClip: payload.snofsClip ?? 0.35,
+        consistencyModel: payload.consistencyModel ?? 0.7,
+        consistencyClip: payload.consistencyClip ?? 0.7,
+        megapixels: payload.scaleMegapixels ?? 1
+      }).catch((error) => {
+        const message = error instanceof Error ? error.message : String(error)
+        if (live && live.status !== 'error' && live.status !== 'cancelled' && live.status !== 'deferred') {
+          live.status = 'error'
+          live.error = message
+        }
+      })
+      return
+    }
+
     const passes = payload.passes || []
     live = createEditLiveJob({
       steps: payload.steps,