@goodandready/dsh-image-gen 0.11.26 → 0.11.28

package/lib/live-progress.js

@@ -0,0 +1,278 @@
+// lib/live-progress.js — Live progress event hub & presentation transport (#147, #329, #379)
+
+import { isTrustedLocalRequest } from './security.js'
+
+const activeSessions = new Map()
+
+/**
+ * Creates or resets a live progress session for a tool call.
+ *
+ * @param {string} callId
+ * @param {{ signal?: AbortSignal, onProgress?: Function }} [options]
+ * @returns {object}
+ */
+export function createLiveProgressSession(callId, options = {}) {
+  if (!callId) return null
+  const existing = activeSessions.get(callId)
+  if (existing) {
+    existing.listeners.clear()
+  }
+
+  const session = {
+    callId,
+    stage: 'Starting...',
+    step: undefined,
+    progress: undefined,
+    draftUrl: undefined,
+    done: false,
+    error: undefined,
+    timestamp: Date.now(),
+    listeners: new Set(),
+  }
+
+  if (options.signal) {
+    options.signal.addEventListener(
+      'abort',
+      () => {
+        abortLiveProgress(callId, 'Execution aborted')
+      },
+      { once: true },
+    )
+  }
+
+  activeSessions.set(callId, session)
+  return session
+}
+
+/**
+ * Publishes an incremental update to a live progress session.
+ *
+ * @param {string} callId
+ * @param {{ stage?: string, step?: string, progress?: number, draftUrl?: string }} update
+ */
+export function publishLiveProgress(callId, update = {}) {
+  if (!callId) return
+  let session = activeSessions.get(callId)
+  if (!session) {
+    session = createLiveProgressSession(callId)
+  }
+  if (session.done) return
+
+  if (update.stage !== undefined) session.stage = update.stage
+  if (update.step !== undefined) session.step = update.step
+  if (update.progress !== undefined) {
+    session.progress = typeof update.progress === 'number'
+      ? Math.min(100, Math.max(0, Math.round(update.progress)))
+      : undefined
+  }
+  if (update.draftUrl !== undefined) session.draftUrl = update.draftUrl
+  session.timestamp = Date.now()
+
+  const payload = {
+    callId,
+    stage: session.stage,
+    step: session.step,
+    progress: session.progress,
+    draftUrl: session.draftUrl,
+    done: false,
+  }
+
+  for (const listener of session.listeners) {
+    try {
+      listener(payload)
+    } catch (_err) {
+      // Listener notification failure ignored
+    }
+  }
+}
+
+/**
+ * Marks a session as complete and notifies subscribers.
+ *
+ * @param {string} callId
+ * @param {object} [finalData]
+ */
+export function completeLiveProgress(callId, finalData = {}) {
+  if (!callId) return
+  const session = activeSessions.get(callId)
+  if (!session || session.done) return
+
+  session.done = true
+  session.stage = 'Complete'
+  session.progress = 100
+  session.timestamp = Date.now()
+
+  const payload = {
+    callId,
+    stage: 'Complete',
+    progress: 100,
+    draftUrl: session.draftUrl,
+    done: true,
+    ...finalData,
+  }
+
+  for (const listener of session.listeners) {
+    try {
+      listener(payload)
+    } catch (_err) {
+      // Listener notification failure ignored
+    }
+  }
+  session.listeners.clear()
+
+  // Retain briefly for trailing SSE disconnects, then purge
+  setTimeout(() => {
+    activeSessions.delete(callId)
+  }, 15000)
+}
+
+/**
+ * Marks a session as aborted or errored.
+ *
+ * @param {string} callId
+ * @param {string} [reason]
+ */
+export function abortLiveProgress(callId, reason = 'Cancelled') {
+  if (!callId) return
+  const session = activeSessions.get(callId)
+  if (!session || session.done) return
+
+  session.done = true
+  session.error = reason
+  session.timestamp = Date.now()
+
+  const payload = {
+    callId,
+    error: reason,
+    done: true,
+  }
+
+  for (const listener of session.listeners) {
+    try {
+      listener(payload)
+    } catch (_err) {
+      // Listener notification failure ignored
+    }
+  }
+  session.listeners.clear()
+
+  setTimeout(() => {
+    activeSessions.delete(callId)
+  }, 10000)
+}
+
+/**
+ * Returns current snapshot of a live progress session.
+ *
+ * @param {string} callId
+ * @returns {object|null}
+ */
+export function getLiveProgress(callId) {
+  if (!callId) return null
+  const session = activeSessions.get(callId)
+  if (!session) return null
+  return {
+    callId: session.callId,
+    stage: session.stage,
+    step: session.step,
+    progress: session.progress,
+    draftUrl: session.draftUrl,
+    done: session.done,
+    error: session.error,
+  }
+}
+
+/**
+ * Subscribes a listener to progress events for a callId.
+ * Calls listener with current state immediately if present.
+ *
+ * @param {string} callId
+ * @param {Function} listener
+ * @returns {Function} unsubscribe
+ */
+export function subscribeLiveProgress(callId, listener) {
+  if (!callId || typeof listener !== 'function') return () => {}
+  let session = activeSessions.get(callId)
+  if (!session) {
+    session = createLiveProgressSession(callId)
+  }
+
+  session.listeners.add(listener)
+
+  // Initial event replay
+  listener({
+    callId: session.callId,
+    stage: session.stage,
+    step: session.step,
+    progress: session.progress,
+    draftUrl: session.draftUrl,
+    done: session.done,
+    error: session.error,
+  })
+
+  return () => {
+    session.listeners.delete(listener)
+  }
+}
+
+/**
+ * Registers the /dsh-image-gen/live-events SSE route on DSH web server.
+ *
+ * @param {object} ctx cordis context
+ */
+export function registerLiveProgressRoutes(ctx) {
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-image-gen/live-events',
+    handler: async (req, res) => {
+      if (req.method !== 'GET' && req.method !== 'HEAD') {
+        res.writeHead(405, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ error: 'GET only' }))
+        return
+      }
+      if (!isTrustedLocalRequest(req)) {
+        res.writeHead(403, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ error: 'forbidden' }))
+        return
+      }
+
+      const u = new URL(req.url, 'http://localhost')
+      const callId = u.searchParams.get('callId') || ''
+      if (!callId) {
+        res.writeHead(400, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ error: 'callId query parameter required' }))
+        return
+      }
+
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache, no-transform',
+        'Connection': 'keep-alive',
+        'Access-Control-Allow-Origin': '*',
+      })
+
+      res.write(': connected\n\n')
+
+      const unsubscribe = subscribeLiveProgress(callId, (data) => {
+        try {
+          res.write(`data: ${JSON.stringify(data)}\n\n`)
+          if (data.done) {
+            setTimeout(() => {
+              try {
+                res.end()
+              } catch (_err) {
+                // Response end failure ignored
+              }
+            }, 300)
+          }
+        } catch (_err) {
+          // SSE write failure ignored
+        }
+      })
+
+      req.on('close', () => {
+        unsubscribe()
+      })
+    },
+  }), 'dsh-image-gen: live events route')
+}

package/lib/providers/backends/custom.js

@@ -1,6 +1,7 @@
 import {
   normalizeMediaType,
   buildEditForm,
+  normalizeMaskAlpha,
   SIZE_PIXELS,
   formatErrorMessage,
   buildEndpointUrl,
@@ -18,12 +19,18 @@ export function createCustomGenerator(deps, job) {
   const { prompt, size, format, seed, signal, negativePrompt, guidanceScale, source, mask, strength, quality, style, aspectPixels, aspectRatio } = job
 
   async function custom(seedArg = seed, promptArg = prompt) {
+    if (job.faceReference && !source) {
+      throw new Error('Custom provider (OpenAI-compatible) does not support facial identity references (FaceID) — use ComfyUI (IP-Adapter/InstantID) or FAL')
+    }
     const base = String(cfg.customBaseURL || '').replace(/\/+$/, '')
-    if (!base) throw new Error('Custom image provider: base URL is not configured (Settings → Image generation)')
+    if (!base) throw new Error('Custom image provider: base URL is not configured (Settings в†’ Image generation)')
     if (!cfg.customModel) throw new Error('Custom image provider: model is not configured')
 
     // Empty key reference indicates unauthenticated gateway.
     const key = cfg.customKeyEnv ? await resolveKey(cfg.customKeyEnv) : ''
+    if (job.faceReference && !source) {
+      throw new Error('Custom provider (OpenAI-compatible) does not support facial identity references (FaceID) — use ComfyUI (IP-Adapter/InstantID) or FAL')
+    }
     const isEdit = Boolean(source && source.bytes)
     const headers = {}
     if (!isEdit) {
@@ -32,6 +39,11 @@ export function createCustomGenerator(deps, job) {
     if (key) headers.Authorization = `Bearer ${key}`
 
     // Omit response_format; modern models return either base64 or URL.
+    let effectiveMask = mask
+    if (isEdit && mask && mask.bytes) {
+      const normBytes = await normalizeMaskAlpha(mask.bytes)
+      effectiveMask = { ...mask, bytes: normBytes, mediaType: 'image/png' }
+    }
     const endpoint = buildEndpointUrl(base, isEdit ? 'images/edits' : 'images/generations')
     const res = await fetchImpl(endpoint, {
       method: 'POST',
@@ -40,7 +52,7 @@ export function createCustomGenerator(deps, job) {
         ? buildEditForm({
             model: cfg.customModel,
             source,
-            mask,
+            mask: effectiveMask,
             prompt: promptArg,
             size: cfg.customSize || (aspectPixels ? aspectPixels.join('x') : SIZE_PIXELS[size]) || size,
             strength,

package/lib/providers/backends/fal.js

@@ -9,11 +9,11 @@ import {
  * @param {fetchImpl: Function, resolveKey: Function, cfg: object} deps
  * @param {prompt?: string, size?: string, format?: string, seed?: number, signal?: AbortSignal,
  *   negativePrompt?: string, guidanceScale?: number, source?: object, mask?: object, strength?: number,
- *   quality?: string, style?: string, aspectPixels?: number[], aspectRatio?: string} job
+ *   quality?: string, style?: string, aspectPixels?: number[], aspectRatio?: string, onProgress?: Function, callId?: string} job
  */
 export function createFalGenerator(deps, job) {
   const { fetchImpl, resolveKey, cfg } = deps
-  const { prompt, size, format, seed, signal, negativePrompt, guidanceScale, source, mask, strength, quality, style, aspectPixels, aspectRatio } = job
+  const { prompt, size, format, seed, signal, negativePrompt, guidanceScale, source, mask, strength, quality, style, aspectPixels, aspectRatio, onProgress } = job
 
   async function fal(seedArg = seed, promptArg = prompt) {
     const key = await resolveKey(cfg.apiKeyEnv)
@@ -34,11 +34,33 @@ export function createFalGenerator(deps, job) {
       if (strength !== undefined) {
         body.strength = strength
       }
+    } else if (job.faceReference && (job.faceReference.bytes || job.faceReference.url)) {
+      const refDataUri = job.faceReference.bytes
+        ? `data:${job.faceReference.mediaType || 'image/png'};base64,${Buffer.from(job.faceReference.bytes).toString('base64')}`
+        : job.faceReference.url
+      body.reference_image_url = refDataUri
+      body.face_image_url = refDataUri
+      if (job.faceStrength !== undefined) {
+        body.id_weight = job.faceStrength
+        body.reference_weight = job.faceStrength
+      }
+    } else if (job.referenceImage && (job.referenceImage.bytes || job.referenceImage.url)) {
+      const refDataUri = job.referenceImage.bytes
+        ? `data:${job.referenceImage.mediaType || 'image/png'};base64,${Buffer.from(job.referenceImage.bytes).toString('base64')}`
+        : job.referenceImage.url
+      body.reference_image_url = refDataUri
+      if (job.referenceStrength !== undefined) {
+        body.reference_weight = job.referenceStrength
+      }
+    }
+
+    if (typeof onProgress === 'function') {
+      onProgress({ stage: 'Submitting job...', progress: undefined })
     }
 
     const submit = await submitJob(fetchImpl, cfg.baseURL, targetModel, key, body, signal)
     const statusUrl = submit.status_url || `${cfg.baseURL}/${cfg.model}/requests/${submit.request_id}/status`
-    const statusBody = await pollStatus(fetchImpl, statusUrl, key, signal, cfg.pollIntervalMs, cfg.timeoutMs)
+    const statusBody = await pollStatus(fetchImpl, statusUrl, key, signal, cfg.pollIntervalMs, cfg.timeoutMs, onProgress)
 
     const resultRes = await fetchImpl(statusBody.response_url, {
       headers: { Authorization: falAuthHeader(key) },

package/lib/providers/backends/gemini.js

@@ -38,6 +38,18 @@ export function createGeminiGenerator(deps, job) {
           data: sourceBase64,
         },
       })
+    } else {
+      const refTarget = job.faceReference || job.referenceImage
+      if (refTarget && refTarget.bytes) {
+        const refMime = refTarget.mediaType || 'image/png'
+        const refBase64 = Buffer.isBuffer(refTarget.bytes) ? refTarget.bytes.toString('base64') : Buffer.from(refTarget.bytes).toString('base64')
+        parts.push({
+          inlineData: {
+            mimeType: refMime,
+            data: refBase64,
+          },
+        })
+      }
     }
     parts.push({ text: promptArg })
 

package/lib/providers/backends/local.js

@@ -10,15 +10,24 @@ import {
   buildDefaultComfyWorkflow,
 } from '../../comfy-workflow-helpers.js'
 
+function resolveWebSocket() {
+  if (typeof window !== 'undefined' && window.WebSocket) return window.WebSocket
+  try {
+    return (new Function('return typeof WebSocket !== "undefined" ? WebSocket : undefined'))()
+  } catch (_) {
+    return undefined
+  }
+}
+
 /**
  * @param {fetchImpl: Function, resolveKey: Function, cfg: object} deps
  * @param {prompt?: string, size?: string, format?: string, seed?: number, signal?: AbortSignal,
  *   negativePrompt?: string, guidanceScale?: number, source?: object, mask?: object, strength?: number,
- *   quality?: string, style?: string, aspectPixels?: number[], aspectRatio?: string} job
+ *   quality?: string, style?: string, aspectPixels?: number[], aspectRatio?: string, onProgress?: Function, callId?: string} job
  */
 export function createLocalGenerator(deps, job) {
   const { fetchImpl, resolveKey, cfg } = deps
-  const { prompt, size, format, seed, signal, negativePrompt, guidanceScale, source, mask, strength, quality, style, aspectPixels, aspectRatio } = job
+  const { prompt, size, format, seed, signal, negativePrompt, guidanceScale, source, mask, strength, quality, style, aspectPixels, aspectRatio, onProgress } = job
 
   async function local(seedArg = seed, promptArg = prompt) {
     const base = String(cfg.localBaseURL || '').replace(/\/+$/, '')
@@ -34,6 +43,9 @@ export function createLocalGenerator(deps, job) {
     }
 
     if (kind === 'a1111') {
+      if (typeof onProgress === 'function') {
+        onProgress({ stage: 'Generating...', progress: undefined })
+      }
       const isImg2Img = Boolean(source && source.bytes)
       const endpoint = `${base}${isImg2Img ? '/sdapi/v1/img2img' : '/sdapi/v1/txt2img'}`
       const body = {
@@ -80,6 +92,13 @@ export function createLocalGenerator(deps, job) {
     let workflowGraph
     if (cfg.comfyWorkflowJson) {
       const template = validateComfyWorkflow(cfg.comfyWorkflowJson)
+      const faceData = job.faceReference && job.faceReference.bytes
+        ? Buffer.from(job.faceReference.bytes).toString('base64')
+        : (job.faceReference?.url || '')
+      const refData = job.referenceImage && job.referenceImage.bytes
+        ? Buffer.from(job.referenceImage.bytes).toString('base64')
+        : (job.referenceImage?.url || '')
+
       workflowGraph = interpolateComfyWorkflow(template, {
         prompt: promptArg,
         negativePrompt: negativePrompt || '',
@@ -90,6 +109,10 @@ export function createLocalGenerator(deps, job) {
         cfg: cfg.localCfg ?? 7,
         model: cfg.localModel,
         image: source && source.bytes ? Buffer.from(source.bytes).toString('base64') : '',
+        faceImage: faceData,
+        faceWeight: job.faceStrength ?? 0.75,
+        referenceImage: refData,
+        referenceWeight: job.referenceStrength ?? 0.65,
       })
     } else {
       workflowGraph = buildDefaultComfyWorkflow({
@@ -114,61 +137,138 @@ export function createLocalGenerator(deps, job) {
       }
     }
 
-    const submit = await fetchImpl(`${base}/prompt`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ prompt: workflowGraph, client_id: promptId }),
-      signal,
-    })
-    if (!submit.ok) {
-      throw new Error(`Local ComfyUI submit failed (HTTP ${submit.status}): ${String(await submit.text().catch(() => '')).slice(0, 300)}`)
+    let ws
+    let wsClosed = false
+    const closeWs = () => {
+      if (!wsClosed && ws) {
+        wsClosed = true
+        try {
+          ws.close()
+        } catch (_err) {
+          // Socket close failure ignored
+        }
+      }
     }
-    const submitData = await submit.json().catch(() => ({}))
-    const pid = submitData.prompt_id
-    if (!pid) throw new Error('Local ComfyUI did not return a prompt_id')
 
-    const deadline = Date.now() + cfg.timeoutMs
-    let attempt = 0
-    for (;;) {
-      if (signal?.aborted) throw new Error('Local ComfyUI generation cancelled')
-      if (Date.now() > deadline) throw new Error(`Local ComfyUI timed out after ${cfg.timeoutMs} ms`)
-      if (attempt > 0) {
-        const cDelay = calculateBackoff(attempt - 1, cfg.pollIntervalMs || 1000, 5000)
-        await new Promise((resolve) => {
-          const timer = setTimeout(resolve, cDelay)
+    try {
+      const WebSocketClass = resolveWebSocket()
+      if (WebSocketClass) {
+        const wsUrl = `${base.replace(/^http/, 'ws')}/ws?clientId=${encodeURIComponent(promptId)}`
+        try {
+          ws = new WebSocketClass(wsUrl)
           if (signal) {
-            signal.addEventListener('abort', () => { clearTimeout(timer); resolve() }, { once: true })
+            signal.addEventListener('abort', closeWs, { once: true })
           }
-        })
-      }
-      attempt++
-      const hist = await fetchImpl(`${base}/history/${pid}`, { signal })
-      if (!hist.ok) continue
-      const histData = await hist.json().catch(() => ({}))
-      const entry = histData[pid]
-      if (entry) {
-        const comfyErr = extractComfyNodeErrors(entry)
-        if (comfyErr) {
-          throw new Error(`Local ComfyUI execution failed: ${comfyErr}`)
+          ws.onmessage = (event) => {
+            if (wsClosed) return
+            try {
+              if (typeof event.data === 'string') {
+                const msg = JSON.parse(event.data)
+                if (msg.type === 'progress') {
+                  const { value, max } = msg.data || {}
+                  const progress = (max > 0) ? Math.min(100, Math.max(0, Math.round((value / max) * 100))) : undefined
+                  if (typeof onProgress === 'function') {
+                    onProgress({ stage: 'Rendering...', step: `${value}/${max}`, progress })
+                  }
+                } else if (msg.type === 'executing') {
+                  const node = msg.data?.node
+                  if (typeof onProgress === 'function') {
+                    onProgress({ stage: node ? `Executing node ${node}` : 'Finishing...' })
+                  }
+                } else if (msg.type === 'status') {
+                  const q = msg.data?.status?.exec_info?.queue_remaining
+                  if (q !== undefined && q > 0 && typeof onProgress === 'function') {
+                    onProgress({ stage: `In queue (${q} remaining)` })
+                  }
+                }
+              } else if (event.data) {
+                const rawBuf = Buffer.isBuffer(event.data) ? event.data : Buffer.from(event.data)
+                let imgBuf = rawBuf
+                if (rawBuf.length > 8 && (rawBuf[0] === 0 || rawBuf[0] === 1 || rawBuf[0] === 2)) {
+                  imgBuf = rawBuf.subarray(8)
+                }
+                if (imgBuf.length > 4) {
+                  const isPng = imgBuf[0] === 0x89 && imgBuf[1] === 0x50
+                  const mime = isPng ? 'image/png' : 'image/jpeg'
+                  const draftUrl = `data:${mime};base64,${imgBuf.toString('base64')}`
+                  if (typeof onProgress === 'function') {
+                    onProgress({ draftUrl })
+                  }
+                }
+              }
+            } catch (_err) {
+              // Frame parse failure ignored
+            }
+          }
+          ws.onerror = () => {}
+          ws.onclose = () => {}
+        } catch (_err) {
+          // Websocket handshake failure ignored
         }
       }
-      if (entry && entry.outputs) {
-        const outputs = entry.outputs
-        const img = Object.values(outputs).flatMap((o) => o.images || []).find((i) => i && i.filename)
-        if (img) {
-          const dl = await fetchImpl(`${base}/view?filename=${encodeURIComponent(img.filename)}&subfolder=${encodeURIComponent(img.subfolder || '')}&type=${encodeURIComponent(img.type || 'output')}`, { signal })
-          if (!dl.ok) throw new Error(`Local ComfyUI download failed (HTTP ${dl.status})`)
-          return {
-            bytes: Buffer.from(await dl.arrayBuffer()),
-            mediaType: normalizeMediaType('image/png', format),
-            width,
-            height,
-            seed: seedArg ?? 0,
-            sourceUrl: '',
+
+      if (typeof onProgress === 'function') {
+        onProgress({ stage: 'Submitting prompt...', progress: undefined })
+      }
+
+      const submit = await fetchImpl(`${base}/prompt`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ prompt: workflowGraph, client_id: promptId }),
+        signal,
+      })
+      if (!submit.ok) {
+        throw new Error(`Local ComfyUI submit failed (HTTP ${submit.status}): ${String(await submit.text().catch(() => '')).slice(0, 300)}`)
+      }
+      const submitData = await submit.json().catch(() => ({}))
+      const pid = submitData.prompt_id
+      if (!pid) throw new Error('Local ComfyUI did not return a prompt_id')
+
+      const deadline = Date.now() + cfg.timeoutMs
+      let attempt = 0
+      for (;;) {
+        if (signal?.aborted) throw new Error('Local ComfyUI generation cancelled')
+        if (Date.now() > deadline) throw new Error(`Local ComfyUI timed out after ${cfg.timeoutMs} ms`)
+        if (attempt > 0) {
+          const cDelay = calculateBackoff(attempt - 1, cfg.pollIntervalMs || 1000, 5000)
+          await new Promise((resolve) => {
+            const timer = setTimeout(resolve, cDelay)
+            if (signal) {
+              signal.addEventListener('abort', () => { clearTimeout(timer); resolve() }, { once: true })
+            }
+          })
+        }
+        attempt++
+        const hist = await fetchImpl(`${base}/history/${pid}`, { signal })
+        if (!hist.ok) continue
+        const histData = await hist.json().catch(() => ({}))
+        const entry = histData[pid]
+        if (entry) {
+          const comfyErr = extractComfyNodeErrors(entry)
+          if (comfyErr) {
+            throw new Error(`Local ComfyUI execution failed: ${comfyErr}`)
+          }
+        }
+        if (entry && entry.outputs) {
+          const outputs = entry.outputs
+          const img = Object.values(outputs).flatMap((o) => o.images || []).find((i) => i && i.filename)
+          if (img) {
+            const dl = await fetchImpl(`${base}/view?filename=${encodeURIComponent(img.filename)}&subfolder=${encodeURIComponent(img.subfolder || '')}&type=${encodeURIComponent(img.type || 'output')}`, { signal })
+            if (!dl.ok) throw new Error(`Local ComfyUI download failed (HTTP ${dl.status})`)
+            return {
+              bytes: Buffer.from(await dl.arrayBuffer()),
+              mediaType: normalizeMediaType('image/png', format),
+              width,
+              height,
+              seed: seedArg ?? 0,
+              sourceUrl: '',
+            }
           }
         }
       }
+    } finally {
+      closeWs()
     }
   }
   return local
-}
+}

package/lib/providers/backends/replicate.js

@@ -31,6 +31,11 @@ export function createReplicateGenerator(deps, job) {
           image: `data:${source.mediaType || 'image/png'};base64,${Buffer.from(source.bytes).toString('base64')}`,
           ...(mask && mask.bytes ? { mask: `data:${mask.mediaType || 'image/png'};base64,${Buffer.from(mask.bytes).toString('base64')}` } : {}),
           ...(strength !== undefined ? { prompt_strength: strength } : {}),
+        } : (job.faceReference || job.referenceImage) ? {
+          face_image: (job.faceReference || job.referenceImage).bytes
+            ? `data:${(job.faceReference || job.referenceImage).mediaType || 'image/png'};base64,${Buffer.from((job.faceReference || job.referenceImage).bytes).toString('base64')}`
+            : (job.faceReference || job.referenceImage).url,
+          id_weight: job.faceStrength ?? 0.75,
         } : {}),
       },
     }

package/lib/providers/backends/seedream.js

@@ -14,6 +14,9 @@ export function createSeedreamGenerator(deps, job) {
   const { prompt, size, format, seed, signal, negativePrompt, guidanceScale, source, mask, strength, quality, style, aspectPixels, aspectRatio } = job
 
   async function seedream(seedArg = seed, promptArg = prompt) {
+    if (job.faceReference) {
+      throw new Error('Seedream does not support facial identity references (FaceID) — use ComfyUI (IP-Adapter/InstantID) or FAL')
+    }
     const key = await resolveKey(cfg.seedreamKeyEnv)
     const base = (cfg.seedreamBaseURL || 'https://api.bytedanceapi.com/v1').replace(/\/+$/, '')
     const timeoutSignal = typeof AbortSignal !== 'undefined' && AbortSignal.timeout

package/lib/providers/backends/subscription.js

@@ -18,6 +18,9 @@ export function createSubscriptionGenerator(deps, job) {
       if (source) {
         return { ok: false, provider, reason: `${provider}: does not support image editing — use fal, custom, or local` }
       }
+      if (job.faceReference) {
+        return { ok: false, provider, reason: `${provider}: does not support facial identity references (FaceID) — use ComfyUI (IP-Adapter) or FAL` }
+      }
       const images = deps.subscriptionImages
       if (!images || typeof images.generate !== 'function') {
         return {