@goodandready/dsh-image-gen 0.11.27 → 0.11.28

package/lib/comfy-workflow-helpers.js

@@ -73,6 +73,10 @@ export function interpolateComfyWorkflow(workflowGraph, ctx) {
   const cfgVal = Number.isFinite(ctx.cfg) ? ctx.cfg : 7
   const modelVal = String(ctx.model ?? 'v1-5-pruned-emaonly.safetensors')
   const imageVal = String(ctx.image ?? '')
+  const faceImageVal = String(ctx.faceImage ?? ctx.face_image ?? '')
+  const faceWeightVal = Number.isFinite(ctx.faceWeight ?? ctx.face_weight) ? (ctx.faceWeight ?? ctx.face_weight) : 0.75
+  const refImageVal = String(ctx.referenceImage ?? ctx.reference_image ?? '')
+  const refWeightVal = Number.isFinite(ctx.referenceWeight ?? ctx.reference_weight) ? (ctx.referenceWeight ?? ctx.reference_weight) : 0.65
 
   function transformValue(val) {
     if (typeof val === 'string') {
@@ -83,6 +87,8 @@ export function interpolateComfyWorkflow(workflowGraph, ctx) {
       if (trimmed === '{{height}}') return heightVal
       if (trimmed === '{{steps}}') return stepsVal
       if (trimmed === '{{cfg}}') return cfgVal
+      if (trimmed === '{{face_weight}}' || trimmed === '{{faceWeight}}') return faceWeightVal
+      if (trimmed === '{{reference_weight}}' || trimmed === '{{referenceWeight}}') return refWeightVal
 
       // General string replacements
       return val
@@ -96,6 +102,14 @@ export function interpolateComfyWorkflow(workflowGraph, ctx) {
         .replace(/\{\{cfg\}\}/g, String(cfgVal))
         .replace(/\{\{model\}\}/g, modelVal)
         .replace(/\{\{image\}\}/g, imageVal)
+        .replace(/\{\{face_image\}\}/g, faceImageVal)
+        .replace(/\{\{faceImage\}\}/g, faceImageVal)
+        .replace(/\{\{face_weight\}\}/g, String(faceWeightVal))
+        .replace(/\{\{faceWeight\}\}/g, String(faceWeightVal))
+        .replace(/\{\{reference_image\}\}/g, refImageVal)
+        .replace(/\{\{referenceImage\}\}/g, refImageVal)
+        .replace(/\{\{reference_weight\}\}/g, String(refWeightVal))
+        .replace(/\{\{referenceWeight\}\}/g, String(refWeightVal))
     }
     if (Array.isArray(val)) {
       return val.map(transformValue)

package/lib/generation-helpers.js

@@ -72,8 +72,11 @@ export async function prepareGenerationPrompt({ ctx, cfg, args, exec, sessionId,
   let effectiveNegative = styleInfo.negativePrompt
   const activeAnchor = getSessionAnchor(sessionId)
   let resolvedFaceRef
+  let resolvedRefImage
 
   const faceRefInput = args.face_reference || (activeAnchor && (activeAnchor.mode === 'face' || activeAnchor.mode === 'character') ? activeAnchor.image : undefined)
+  const refImageInput = args.reference_image || (activeAnchor && activeAnchor.mode === 'style' ? activeAnchor.image : undefined)
+
   if (faceRefInput) {
     try {
       resolvedFaceRef = await resolveSource(ctx, exec, faceRefInput)
@@ -90,9 +93,22 @@ export async function prepareGenerationPrompt({ ctx, cfg, args, exec, sessionId,
     if (facePlan.negativePrompt) {
       effectiveNegative = effectiveNegative ? `${effectiveNegative}, ${facePlan.negativePrompt}` : facePlan.negativePrompt
     }
-  } else if (args.reference_image) {
-    effectivePrompt = `${effectivePrompt}, visual reference anchor`
-  } else if (activeAnchor) {
+  }
+
+  if (refImageInput) {
+    try {
+      resolvedRefImage = await resolveSource(ctx, exec, refImageInput)
+    } catch (_err) {
+      resolvedRefImage = { url: refImageInput }
+    }
+    if (!faceRefInput) {
+      if (activeAnchor) {
+        effectivePrompt = applyAnchorPromptHints(activeAnchor, effectivePrompt)
+      } else {
+        effectivePrompt = `${effectivePrompt}, visual reference anchor`
+      }
+    }
+  } else if (!faceRefInput && activeAnchor) {
     effectivePrompt = applyAnchorPromptHints(activeAnchor, effectivePrompt)
   }
 
@@ -113,6 +129,7 @@ export async function prepareGenerationPrompt({ ctx, cfg, args, exec, sessionId,
     styleInfo,
     activeAnchor,
     resolvedFaceRef,
+    resolvedRefImage,
   }
 }
 

package/lib/providers/backends/custom.js

@@ -19,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) {

package/lib/providers/backends/fal.js

@@ -34,6 +34,24 @@ 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') {

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

@@ -92,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 || '',
@@ -102,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({

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 {

package/lib/providers.js

@@ -640,7 +640,7 @@ export function toLosslessJson(val) {
  * Returns { ok: boolean, latencyMs: number, message: string }.
  */
 export async function testProviderConnection(deps, providerId) {
-  const { fetchImpl = fetch, resolveKey, cfg } = deps
+  const { fetchImpl = fetch, resolveKey, cfg } = deps || {}
   const start = Date.now()
   const rawProvider = (typeof providerId === 'string' && providerId.trim())
     || (typeof cfg?.provider === 'string' && cfg.provider.trim())
@@ -648,128 +648,199 @@ export async function testProviderConnection(deps, providerId) {
     || 'fal'
   const p = rawProvider.toLowerCase()
 
+  const safeTimeout = (ms) => {
+    return typeof AbortSignal !== 'undefined' && AbortSignal.timeout ? AbortSignal.timeout(ms) : undefined
+  }
+
   try {
     if (p === 'fal') {
-      const key = await resolveKey(cfg.apiKeyEnv || 'FAL_KEY')
-      if (!key) return { ok: false, latencyMs: 0, message: 'FAL API key not configured' }
-      const res = await fetchImpl('https://queue.fal.run/fal-ai/fast-sdxl/status', {
-        headers: { Authorization: falAuthHeader(key) },
-        signal: typeof AbortSignal !== 'undefined' && AbortSignal.timeout ? AbortSignal.timeout(6000) : undefined,
-      })
+      const key = await resolveKey(cfg?.apiKeyEnv || 'FAL_KEY')
+      if (!key) return { ok: false, state: 'not_configured', latencyMs: 0, message: 'FAL API key not configured' }
+      let res
+      try {
+        res = await fetchImpl('https://queue.fal.run/fal-ai/fast-sdxl/status', {
+          headers: { Authorization: falAuthHeader(key) },
+          signal: safeTimeout(6000),
+        })
+      } catch (netErr) {
+        return { ok: false, state: 'offline', latencyMs: Date.now() - start, message: `Fal queue unreachable: ${netErr.message || 'connection error'}` }
+      }
       const latencyMs = Date.now() - start
       if (res.status === 401 || res.status === 403) {
-        return { ok: false, latencyMs, message: `Fal auth failed (HTTP ${res.status})` }
+        return { ok: false, state: 'unauthorized', latencyMs, message: `Fal auth failed (HTTP ${res.status})` }
+      }
+      if (res.status >= 500) {
+        return { ok: false, state: 'server_error', latencyMs, message: `Fal server error (HTTP ${res.status})` }
       }
-      return { ok: true, latencyMs, message: 'Fal.ai queue reachable' }
+      return { ok: true, state: 'authenticated', latencyMs, message: 'Fal.ai queue reachable' }
     }
 
-    if (p === 'comfyui') {
-      const url = cfg.comfyuiUrl || cfg.localBaseURL || 'http://127.0.0.1:8188'
-      const res = await fetchImpl(`${url.replace(/\/+$/, '')}/system_stats`, {
-        signal: typeof AbortSignal !== 'undefined' && AbortSignal.timeout ? AbortSignal.timeout(5000) : undefined,
-      })
-      const latencyMs = Date.now() - start
-      if (res.ok) {
-        const data = await res.json().catch(() => ({}))
-        const vram = data?.devices?.[0]?.vram_free ? ` (${Math.round(data.devices[0].vram_free / 1048576)} MB free VRAM)` : ''
-        return { ok: true, latencyMs, message: `ComfyUI operational${vram}` }
+    if (p === 'local' || p === 'comfyui' || p === 'a1111') {
+      const backend = (p === 'local' ? (cfg?.localBackend || 'comfyui') : p).toLowerCase()
+      if (backend === 'a1111') {
+        const url = cfg?.a1111Url || cfg?.localBaseURL || 'http://127.0.0.1:7860'
+        let res
+        try {
+          res = await fetchImpl(`${url.replace(/\/+$/, '')}/sdapi/v1/samplers`, {
+            signal: safeTimeout(5000),
+          })
+        } catch (netErr) {
+          return { ok: false, state: 'offline', latencyMs: Date.now() - start, message: `Automatic1111 offline (${netErr.message || 'connection refused'})` }
+        }
+        const latencyMs = Date.now() - start
+        if (res.status === 401 || res.status === 403) {
+          return { ok: false, state: 'unauthorized', latencyMs, message: `A1111 auth error (HTTP ${res.status})` }
+        }
+        if (res.status >= 500) {
+          return { ok: false, state: 'server_error', latencyMs, message: `A1111 server error (HTTP ${res.status})` }
+        }
+        if (res.ok) {
+          return { ok: true, state: 'model_available', latencyMs, message: 'Automatic1111 operational' }
+        }
+        return { ok: false, state: 'server_error', latencyMs, message: `A1111 returned HTTP ${res.status}` }
       }
-      return { ok: false, latencyMs, message: `ComfyUI returned HTTP ${res.status}` }
-    }
 
-    if (p === 'a1111') {
-      const url = cfg.a1111Url || cfg.localBaseURL || 'http://127.0.0.1:7860'
-      const res = await fetchImpl(`${url.replace(/\/+$/, '')}/sdapi/v1/samplers`, {
-        signal: typeof AbortSignal !== 'undefined' && AbortSignal.timeout ? AbortSignal.timeout(5000) : undefined,
-      })
+      // Default local is ComfyUI
+      const url = cfg?.comfyuiUrl || cfg?.localBaseURL || 'http://127.0.0.1:8188'
+      let res
+      try {
+        res = await fetchImpl(`${url.replace(/\/+$/, '')}/system_stats`, {
+          signal: safeTimeout(5000),
+        })
+      } catch (netErr) {
+        return { ok: false, state: 'offline', latencyMs: Date.now() - start, message: `ComfyUI offline (${netErr.message || 'connection refused'})` }
+      }
       const latencyMs = Date.now() - start
+      if (res.status === 401 || res.status === 403) {
+        return { ok: false, state: 'unauthorized', latencyMs, message: `ComfyUI auth error (HTTP ${res.status})` }
+      }
+      if (res.status >= 500) {
+        return { ok: false, state: 'server_error', latencyMs, message: `ComfyUI server error (HTTP ${res.status})` }
+      }
       if (res.ok) {
-        return { ok: true, latencyMs, message: 'Automatic1111 operational' }
+        const data = await res.json().catch(() => ({}))
+        const vram = data?.devices?.[0]?.vram_free ? ` (${Math.round(data.devices[0].vram_free / 1048576)} MB free VRAM)` : ''
+        return { ok: true, state: 'model_available', latencyMs, message: `ComfyUI operational${vram}` }
       }
-      return { ok: false, latencyMs, message: `A1111 returned HTTP ${res.status}` }
+      return { ok: false, state: 'server_error', latencyMs, message: `ComfyUI returned HTTP ${res.status}` }
     }
 
     if (p === 'custom') {
-      const url = cfg.customEndpoint || cfg.customBaseURL || 'https://api.openai.com/v1'
-      const key = await resolveKey(cfg.customApiKeyEnv || cfg.customKeyEnv || 'OPENAI_API_KEY')
+      const url = cfg?.customEndpoint || cfg?.customBaseURL || 'https://api.openai.com/v1'
+      const key = await resolveKey(cfg?.customApiKeyEnv || cfg?.customKeyEnv || 'OPENAI_API_KEY')
       const headers = key ? { Authorization: `Bearer ${key}` } : {}
-      const res = await fetchImpl(`${url.replace(/\/+$/, '')}/models`, {
-        headers,
-        signal: typeof AbortSignal !== 'undefined' && AbortSignal.timeout ? AbortSignal.timeout(6000) : undefined,
-      })
+      let res
+      try {
+        res = await fetchImpl(`${url.replace(/\/+$/, '')}/models`, {
+          headers,
+          signal: safeTimeout(6000),
+        })
+      } catch (netErr) {
+        return { ok: false, state: 'offline', latencyMs: Date.now() - start, message: `Custom endpoint offline (${netErr.message || 'connection error'})` }
+      }
       const latencyMs = Date.now() - start
       if (res.status === 401 || res.status === 403) {
-        return { ok: false, latencyMs, message: `Custom endpoint auth error (HTTP ${res.status})` }
+        return { ok: false, state: 'unauthorized', latencyMs, message: `Custom endpoint auth error (HTTP ${res.status})` }
+      }
+      if (res.status >= 500) {
+        return { ok: false, state: 'server_error', latencyMs, message: `Custom endpoint server error (HTTP ${res.status})` }
       }
       if (res.ok || res.status === 404 || res.status === 405) {
-        return { ok: true, latencyMs, message: `Custom gateway reachable (HTTP ${res.status})` }
+        return { ok: true, state: res.ok ? 'authenticated' : 'reachable', latencyMs, message: `Custom gateway reachable (HTTP ${res.status})` }
       }
-      return { ok: false, latencyMs, message: `Custom endpoint returned HTTP ${res.status}` }
+      return { ok: false, state: 'server_error', latencyMs, message: `Custom endpoint returned HTTP ${res.status}` }
     }
 
     if (p === 'subscription' || p === 'chatgpt' || p === 'grok' || p === 'codex') {
-      const hasSub = Boolean(deps.ctx?.subscriptions)
+      const subService = deps?.subscriptionImages
+        || (deps?.ctx?.get && deps.ctx.get('subscriptionImages'))
+        || deps?.ctx?.subscriptionImages
+      const hasSub = Boolean(subService && typeof subService.generate === 'function')
       const latencyMs = Date.now() - start
       if (hasSub) {
-        return { ok: true, latencyMs, message: 'Subscription bridge available' }
+        return { ok: true, state: 'authenticated', latencyMs, message: 'Subscription bridge available' }
       }
-      return { ok: false, latencyMs, message: 'dsh-subscriptions plugin not installed' }
+      return { ok: false, state: 'not_configured', latencyMs, message: 'subscriptionImages service not available (requires dsh-subscriptions plugin)' }
     }
 
     if (p === 'replicate') {
-      const key = await resolveKey(cfg.replicateKeyEnv || 'REPLICATE_API_TOKEN')
-      if (!key) return { ok: false, latencyMs: 0, message: 'Replicate API token not configured' }
-      const res = await fetchImpl('https://api.replicate.com/v1/models', {
-        headers: { Authorization: `Bearer ${key}` },
-        signal: typeof AbortSignal !== 'undefined' && AbortSignal.timeout ? AbortSignal.timeout(6000) : undefined,
-      })
+      const key = await resolveKey(cfg?.replicateKeyEnv || 'REPLICATE_API_TOKEN')
+      if (!key) return { ok: false, state: 'not_configured', latencyMs: 0, message: 'Replicate API token not configured' }
+      let res
+      try {
+        res = await fetchImpl('https://api.replicate.com/v1/models', {
+          headers: { Authorization: `Bearer ${key}` },
+          signal: safeTimeout(6000),
+        })
+      } catch (netErr) {
+        return { ok: false, state: 'offline', latencyMs: Date.now() - start, message: `Replicate unreachable (${netErr.message || 'connection error'})` }
+      }
       const latencyMs = Date.now() - start
       if (res.status === 401 || res.status === 403) {
-        return { ok: false, latencyMs, message: `Replicate auth error (HTTP ${res.status})` }
+        return { ok: false, state: 'unauthorized', latencyMs, message: `Replicate auth error (HTTP ${res.status})` }
+      }
+      if (res.status >= 500) {
+        return { ok: false, state: 'server_error', latencyMs, message: `Replicate server error (HTTP ${res.status})` }
       }
       if (res.ok) {
-        return { ok: true, latencyMs, message: 'Replicate API reachable' }
+        return { ok: true, state: 'authenticated', latencyMs, message: 'Replicate API reachable' }
       }
-      return { ok: false, latencyMs, message: `Replicate returned HTTP ${res.status}` }
+      return { ok: false, state: 'server_error', latencyMs, message: `Replicate returned HTTP ${res.status}` }
     }
 
     if (p === 'gemini') {
-      const key = await resolveKey(cfg.geminiKeyEnv || 'GEMINI_API_KEY')
-      if (!key) return { ok: false, latencyMs: 0, message: 'Google Gemini API key not configured' }
-      const model = cfg.geminiModel || 'gemini-2.0-flash-exp-image-generation'
-      const res = await fetchImpl(`https://generativelanguage.googleapis.com/v1beta/models/${model}?key=${encodeURIComponent(key)}`, {
-        signal: typeof AbortSignal !== 'undefined' && AbortSignal.timeout ? AbortSignal.timeout(6000) : undefined,
-      })
+      const key = await resolveKey(cfg?.geminiKeyEnv || 'GEMINI_API_KEY')
+      if (!key) return { ok: false, state: 'not_configured', latencyMs: 0, message: 'Google Gemini API key not configured' }
+      const model = cfg?.geminiModel || 'gemini-2.0-flash-exp-image-generation'
+      let res
+      try {
+        res = await fetchImpl(`https://generativelanguage.googleapis.com/v1beta/models/${model}?key=${encodeURIComponent(key)}`, {
+          signal: safeTimeout(6000),
+        })
+      } catch (netErr) {
+        return { ok: false, state: 'offline', latencyMs: Date.now() - start, message: `Google Gemini API unreachable (${netErr.message || 'connection error'})` }
+      }
       const latencyMs = Date.now() - start
       if (res.status === 400 || res.status === 401 || res.status === 403) {
-        return { ok: false, latencyMs, message: `Gemini API auth error (HTTP ${res.status})` }
+        return { ok: false, state: 'unauthorized', latencyMs, message: `Gemini API auth error (HTTP ${res.status})` }
+      }
+      if (res.status >= 500) {
+        return { ok: false, state: 'server_error', latencyMs, message: `Gemini API server error (HTTP ${res.status})` }
       }
       if (res.ok) {
-        return { ok: true, latencyMs, message: 'Gemini Vision API operational' }
+        return { ok: true, state: 'model_available', latencyMs, message: 'Gemini Vision API operational' }
       }
-      return { ok: false, latencyMs, message: `Gemini returned HTTP ${res.status}` }
+      return { ok: false, state: 'server_error', latencyMs, message: `Gemini returned HTTP ${res.status}` }
     }
 
     if (p === 'seedream') {
-      const url = cfg.seedreamBaseURL || 'https://api.bytedanceapi.com/v1'
-      const key = await resolveKey(cfg.seedreamKeyEnv || 'SEEDREAM_API_KEY')
+      const url = cfg?.seedreamBaseURL || 'https://api.bytedanceapi.com/v1'
+      const key = await resolveKey(cfg?.seedreamKeyEnv || 'SEEDREAM_API_KEY')
       const headers = key ? { Authorization: `Bearer ${key}` } : {}
-      const res = await fetchImpl(`${url.replace(/\/+$/, '')}/models`, {
-        headers,
-        signal: typeof AbortSignal !== 'undefined' && AbortSignal.timeout ? AbortSignal.timeout(6000) : undefined,
-      }).catch(() => null)
+      let res
+      try {
+        res = await fetchImpl(`${url.replace(/\/+$/, '')}/models`, {
+          headers,
+          signal: safeTimeout(6000),
+        })
+      } catch (netErr) {
+        return { ok: false, state: 'offline', latencyMs: Date.now() - start, message: `Seedream endpoint offline (${netErr.message || 'connection error'})` }
+      }
       const latencyMs = Date.now() - start
-      if (res && (res.ok || res.status === 404 || res.status === 405)) {
-        return { ok: true, latencyMs, message: 'Seedream endpoint reachable' }
+      if (res.status === 401 || res.status === 403) {
+        return { ok: false, state: 'unauthorized', latencyMs, message: `Seedream auth error (HTTP ${res.status})` }
       }
-      if (res && (res.status === 401 || res.status === 403)) {
-        return { ok: false, latencyMs, message: `Seedream auth error (HTTP ${res.status})` }
+      if (res.status >= 500) {
+        return { ok: false, state: 'server_error', latencyMs, message: `Seedream server error (HTTP ${res.status})` }
+      }
+      if (res.ok || res.status === 404 || res.status === 405) {
+        return { ok: true, state: res.ok ? 'authenticated' : 'reachable', latencyMs, message: 'Seedream endpoint reachable' }
       }
-      return { ok: true, latencyMs, message: 'Seedream provider endpoint configured' }
+      return { ok: false, state: 'server_error', latencyMs, message: `Seedream returned HTTP ${res.status}` }
     }
 
-    return { ok: true, latencyMs: Date.now() - start, message: `Provider "${p}" configured` }
+    return { ok: false, state: 'unsupported', latencyMs: Date.now() - start, message: `Unknown or unsupported provider: "${p}"` }
   } catch (err) {
-    return { ok: false, latencyMs: Date.now() - start, message: err.message || 'Connection timeout' }
+    return { ok: false, state: 'offline', latencyMs: Date.now() - start, message: err.message || 'Connection timeout' }
   }
 }

package/lib/register-tools.js

@@ -49,13 +49,15 @@ export function registerAllTools(ctx, deps) {
             if (currentCfg && currentCfg.enabled === false) {
               throw new Error('Image generation is disabled in settings (dsh-image-gen.enabled is false); enable it in Settings → Image generation.')
             }
-            const callId = exec?.callId || exec?.rootCallId
+            const safeArgs = args || {}
+            const safeExec = exec || {}
+            const callId = safeExec.callId || safeExec.rootCallId
             if (callId) {
-              createLiveProgressSession(callId, { signal: exec.signal })
-              exec.onProgress = (update) => publishLiveProgress(callId, update)
+              createLiveProgressSession(callId, { signal: safeExec.signal })
+              safeExec.onProgress = (update) => publishLiveProgress(callId, update)
             }
             try {
-              const res = await originalExecute(args, exec)
+              const res = await originalExecute(safeArgs, safeExec)
               if (callId) completeLiveProgress(callId)
               return res
             } catch (err) {

package/lib/tools/anchor.js

@@ -34,6 +34,11 @@ export function registerAnchorTools(ctx, deps) {
             enum: ['style', 'character', 'face'],
             description: 'Anchor mode: "face" preserves facial portrait identity via FaceID/IP-Adapter; "character" preserves overall character traits; "style" preserves aesthetic palette. Default: style.',
           },
+          anchor_type: {
+            type: 'string',
+            enum: ['style', 'character', 'face'],
+            description: 'Alias for mode ("style", "character", "face").',
+          },
           strength: {
             type: 'number',
             description: 'Reference influence strength between 0.1 and 1.0 (default 0.65).',
@@ -95,9 +100,11 @@ export function registerAnchorTools(ctx, deps) {
           }
 
           const imageRef = args.image.trim()
-          const mode = args.mode === 'character' ? 'character' : 'style'
-          const strength = normalizeAnchorStrength(args.strength)
-          const label = args.label ? String(args.label).trim() : (mode === 'character' ? 'Character Anchor' : 'Style Anchor')
+          const rawMode = String(args.mode || args.anchor_type || '').toLowerCase().trim()
+          const mode = (rawMode === 'character' || rawMode === 'face') ? rawMode : 'style'
+          const strength = normalizeAnchorStrength(args.strength, mode === 'face' || mode === 'character' ? 0.75 : 0.65)
+          const defaultLabel = mode === 'face' ? 'Face Identity Anchor' : (mode === 'character' ? 'Character Anchor' : 'Style Anchor')
+          const label = args.label ? String(args.label).trim() : defaultLabel
 
           // Validate source readability if it is a local path or attachment
           if (resolveSource && (imageRef.startsWith('sha256:') || !imageRef.startsWith('http'))) {

package/lib/tools/character-sheet.js

@@ -107,6 +107,10 @@ export function registerCharacterSheetTools(ctx, deps) {
             throw new Error('Image generation is disabled in settings.')
           }
 
+          if (!args?.prompt || typeof args.prompt !== 'string' || !args.prompt.trim()) {
+            throw new Error('Character description prompt is required for character sheet generation.')
+          }
+
           const provider = PROVIDER_KEYS.includes(args.provider || cfg.provider)
             ? (args.provider || cfg.provider)
             : (PROVIDER_KEYS.includes(cfg.provider) ? cfg.provider : 'fal')

package/lib/tools/diagram.js

@@ -103,6 +103,10 @@ export function registerDiagramTools(ctx, deps) {
             throw new Error('Image generation is disabled in settings.')
           }
 
+          if (!args?.diagram || typeof args.diagram !== 'string' || !args.diagram.trim()) {
+            throw new Error('Diagram content (Mermaid code, ASCII, or description) is required for beautify_diagram.')
+          }
+
           const provider = PROVIDER_KEYS.includes(args.provider || cfg.provider)
             ? (args.provider || cfg.provider)
             : (PROVIDER_KEYS.includes(cfg.provider) ? cfg.provider : 'fal')

package/lib/tools/generation-pack.js

@@ -30,7 +30,10 @@ export function registerGenerationPackTool(ctx, deps) {
         },
         async execute(args, exec) {
           const ratios = Array.isArray(args.aspect_ratios) && args.aspect_ratios.length ? args.aspect_ratios : ['1:1', '16:9', '9:16']
-                    const generateTool = ctx.tools.get('generate_image')
+          const generateTool = ctx?.tools?.get ? ctx.tools.get('generate_image') : (ctx?.tools?.list?.find ? ctx.tools.list.find((t) => t.name === 'generate_image') : null)
+          if (!generateTool || typeof generateTool.execute !== 'function') {
+            throw new Error('Required tool "generate_image" is not available on host.')
+          }
           const results = []
           const warnings = []
           const seedBase = Math.floor(Math.random() * 100000)

package/lib/tools/generation.js

@@ -300,7 +300,7 @@ export function registerGenerationTools(ctx, deps, options = {}) {
         const cfg = live()
 
         // #168: Fail-fast loop guard protecting against runaway agent loops
-        const sessionId = exec.agent?.session?.id || exec.agent?.session?.header?.id || 'session'
+        const sessionId = exec?.agent?.session?.id || exec?.agent?.session?.header?.id || 'session'
         if (cfg.loopGuardLimit > 0) {
           trackAndAssertLoopGuard(sessionId, {
             limit: cfg.loopGuardLimit,
@@ -326,6 +326,7 @@ export function registerGenerationTools(ctx, deps, options = {}) {
           effectiveGuidance,
           activeAnchor,
           resolvedFaceRef,
+          resolvedRefImage,
         } = await prepareGenerationPrompt({ ctx, cfg, args, exec, sessionId, provider, resolveSource })
 
         // #167: Assert daily budget availability before calling API
@@ -339,7 +340,28 @@ export function registerGenerationTools(ctx, deps, options = {}) {
         assertBudgetAvailable(estimatedCost, cfg.dailyBudgetUsd)
         const providers = makeProviders(
           { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg, subscriptionImages },
-          { prompt: effectivePrompt, size, format, seed: args.seed, signal: exec.signal, negativePrompt: effectiveNegative, guidanceScale: effectiveGuidance, source, mask, strength: args.strength, quality: args.quality, style: args.style, aspectPixels, aspectRatio: args.aspect_ratio, faceReference: resolvedFaceRef, onProgress: exec?.onProgress, callId: exec?.callId },
+          {
+            prompt: effectivePrompt,
+            size,
+            format,
+            seed: args.seed,
+            signal: exec?.signal,
+            negativePrompt: effectiveNegative,
+            guidanceScale: effectiveGuidance,
+            source,
+            mask,
+            strength: args.strength,
+            quality: args.quality,
+            style: args.style,
+            aspectPixels,
+            aspectRatio: args.aspect_ratio,
+            faceReference: resolvedFaceRef,
+            faceStrength: args.face_strength || activeAnchor?.strength,
+            referenceImage: resolvedRefImage,
+            referenceStrength: args.reference_strength || activeAnchor?.strength,
+            onProgress: exec?.onProgress,
+            callId: exec?.callId,
+          },
         )
         // Subscription providers return {ok:false, reason} instead of throwing:
         // rejection reaches the model as text. Without this guard,
@@ -445,7 +467,7 @@ export function registerGenerationTools(ctx, deps, options = {}) {
               const stem = `${slugify(args.output_name || promptVal)}-${Date.now().toString(36)}-${seedVal}`
               const name = `${stem}.${extension}`
               const { attachment, localUrl } = await saveAttachmentSafe(ctx, { bytes: diskHit.bytes, mediaType: diskHit.mediaType, name })
-              const sessionCwd = exec.agent?.session?.header?.cwd
+              const sessionCwd = exec?.agent?.session?.header?.cwd
               const targetDir = (args.output_dir && String(args.output_dir).trim()) || cfg.outputDir || 'generated/images'
               const outDir = path.resolve(sessionCwd || process.cwd(), targetDir)
               await mkdir(outDir, { recursive: true })

package/lib/tools/processing-basic.js

@@ -58,12 +58,12 @@ export function registerProcessingTools(ctx, deps) {
           assertBudgetAvailable(0.02, cfg.dailyBudgetUsd)
           const res = await removeBackgroundFal(
             { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg },
-            { imageBytes: source.bytes, mediaType: source.mediaType, model: args.model, signal: exec.signal }
+            { imageBytes: source.bytes, mediaType: source.mediaType, model: args.model, signal: exec?.signal }
           )
           const stem = `${slugify(args.output_name || 'nobg')}-${Date.now().toString(36)}`
           const name = `${stem}.png`
           const { attachment, localUrl } = await saveAttachmentSafe(ctx, { bytes: res.bytes, mediaType: 'image/png', name })
-          const sessionCwd = exec.agent?.session?.header?.cwd
+          const sessionCwd = exec?.agent?.session?.header?.cwd
           const outDir = path.resolve(sessionCwd || process.cwd(), cfg.outputDir || 'generated/images')
           await mkdir(outDir, { recursive: true })
           const filePath = path.join(outDir, name)
@@ -129,12 +129,12 @@ export function registerProcessingTools(ctx, deps) {
           assertBudgetAvailable(0.025, cfg.dailyBudgetUsd)
           const res = await upscaleImageFal(
             { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg },
-            { imageBytes: source.bytes, mediaType: source.mediaType, scale: args.scale, prompt: args.prompt, creativity: args.creativity, signal: exec.signal }
+            { imageBytes: source.bytes, mediaType: source.mediaType, scale: args.scale, prompt: args.prompt, creativity: args.creativity, signal: exec?.signal }
           )
           const stem = `${slugify(args.output_name || 'upscaled')}-${Date.now().toString(36)}`
           const name = `${stem}.png`
           const { attachment, localUrl } = await saveAttachmentSafe(ctx, { bytes: res.bytes, mediaType: 'image/png', name })
-          const sessionCwd = exec.agent?.session?.header?.cwd
+          const sessionCwd = exec?.agent?.session?.header?.cwd
           const outDir = path.resolve(sessionCwd || process.cwd(), cfg.outputDir || 'generated/images')
           await mkdir(outDir, { recursive: true })
           const filePath = path.join(outDir, name)
@@ -196,7 +196,7 @@ export function registerProcessingTools(ctx, deps) {
             const res = await traceToSvg(source.bytes, { colorMode: args.color_mode })
             const stem = `${slugify(args.output_name || 'vector')}-${Date.now().toString(36)}`
             const name = `${stem}.svg`
-            const sessionCwd = exec.agent?.session?.header?.cwd
+            const sessionCwd = exec?.agent?.session?.header?.cwd
             const outDir = path.resolve(sessionCwd || process.cwd(), cfg.outputDir || 'generated/images')
             await mkdir(outDir, { recursive: true })
             const filePath = path.join(outDir, name)
@@ -268,12 +268,12 @@ export function registerProcessingTools(ctx, deps) {
           }
           const res = await blendImagesFal(
             { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg },
-            { images: sources, weights: args.weights, prompt: args.prompt, signal: exec.signal }
+            { images: sources, weights: args.weights, prompt: args.prompt, signal: exec?.signal }
           )
           const stem = `${slugify(args.output_name || 'blended')}-${Date.now().toString(36)}`
           const name = `${stem}.png`
           const { attachment, localUrl } = await saveAttachmentSafe(ctx, { bytes: res.bytes, mediaType: 'image/png', name })
-          const sessionCwd = exec.agent?.session?.header?.cwd
+          const sessionCwd = exec?.agent?.session?.header?.cwd
           const outDir = path.resolve(sessionCwd || process.cwd(), cfg.outputDir || 'generated/images')
           await mkdir(outDir, { recursive: true })
           const filePath = path.join(outDir, name)

package/lib/tools/style-matrix.js

@@ -151,7 +151,7 @@ export function registerStyleMatrixTools(ctx, deps) {
           const quadrantIds = ['A', 'B', 'C', 'D']
           const matrixId = `matrix-${Date.now().toString(36)}`
 
-          const sessionCwd = exec.agent?.session?.header?.cwd
+          const sessionCwd = exec?.agent?.session?.header?.cwd
           const targetDir = cfg.outputDir || 'generated/images'
           const outDir = path.resolve(sessionCwd || process.cwd(), targetDir)
           await mkdir(outDir, { recursive: true })
@@ -168,7 +168,7 @@ export function registerStyleMatrixTools(ctx, deps) {
                 size: 'custom',
                 format: 'png',
                 seed: cellSeed,
-                signal: exec.signal,
+                signal: exec?.signal,
                 aspectPixels,
                 aspectRatio,
               },

package/lib/tools/theme-pair.js

@@ -158,7 +158,7 @@ export function registerThemePairTools(ctx, deps) {
           const chain = resolveFallbackChain(primaryProvider, cfg.fallbackProviders, PROVIDER_KEYS)
           const baseSeed = typeof args.seed === 'number' ? args.seed : Math.floor(Math.random() * 1000000)
 
-          const sessionCwd = exec.agent?.session?.header?.cwd
+          const sessionCwd = exec?.agent?.session?.header?.cwd
           const targetDir = cfg.outputDir || 'generated/images'
           const outDir = path.resolve(sessionCwd || process.cwd(), targetDir)
           await mkdir(outDir, { recursive: true })
@@ -176,7 +176,7 @@ export function registerThemePairTools(ctx, deps) {
             aspectPixels,
             aspectRatio,
             seed: baseSeed,
-            signal: exec.signal,
+            signal: exec?.signal,
           }
           const lightProviders = makeProviders(
             { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg, subscriptionImages },
@@ -214,7 +214,7 @@ export function registerThemePairTools(ctx, deps) {
             aspectPixels,
             aspectRatio,
             seed: baseSeed,
-            signal: exec.signal,
+            signal: exec?.signal,
           }
           const darkProviders = makeProviders(
             { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg, subscriptionImages },

package/lib/tools/ui-asset.js

@@ -156,7 +156,7 @@ export function registerUiAssetTools(ctx, deps) {
               size: 'custom',
               format: 'png',
               seed: args.seed,
-              signal: exec.signal,
+              signal: exec?.signal,
               aspectPixels,
               aspectRatio,
             },
@@ -187,7 +187,7 @@ export function registerUiAssetTools(ctx, deps) {
             try {
               const bgResult = await removeBackgroundFal(
                 { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg },
-                { imageBytes: finalBytes, mediaType, signal: exec.signal },
+                { imageBytes: finalBytes, mediaType, signal: exec?.signal },
               )
               if (bgResult && bgResult.bytes) {
                 finalBytes = bgResult.bytes
@@ -216,7 +216,7 @@ export function registerUiAssetTools(ctx, deps) {
             meta: { provider, model: cfg.model || cfg.customModel, prompt: synthesizedPrompt, seed: seedVal },
           })
 
-          const sessionCwd = exec.agent?.session?.header?.cwd
+          const sessionCwd = exec?.agent?.session?.header?.cwd
           const targetDir = cfg.outputDir || 'generated/images'
           const outDir = path.resolve(sessionCwd || process.cwd(), targetDir)
           await mkdir(outDir, { recursive: true })

package/lib/tools/vision-ocr.js

@@ -137,6 +137,10 @@ export function registerVisionOcrTools(ctx, deps) {
             throw new Error('Image generation is disabled in settings.')
           }
 
+          if (!args?.image || typeof args.image !== 'string' || !args.image.trim()) {
+            throw new Error('Parameter "image" (URL, file path, or sha256 attachment ID) is required for text replacement.')
+          }
+
           const provider = PROVIDER_KEYS.includes(args.provider || cfg.provider)
             ? (args.provider || cfg.provider)
             : (PROVIDER_KEYS.includes(cfg.provider) ? cfg.provider : 'fal')

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@goodandready/dsh-image-gen",
-  "version": "0.11.27",
-  "description": "Image generation for DeepSeek Harness: a generate_image tool with pluggable providers \u2014 the FAL queue, any OpenAI-compatible images API, or a ChatGPT/Grok subscription with no API key at all. The picture is shown inline in the conversation; the model receives either a link (works with any chat model) or the image itself (needs dsh-vision-bridge or a vision-capable model).",
+  "version": "0.11.28",
+  "description": "Image generation for DeepSeek Harness: a generate_image tool with pluggable providers — the FAL queue, any OpenAI-compatible images API, or a ChatGPT/Grok subscription with no API key at all. The picture is shown inline in the conversation; the model receives either a link (works with any chat model) or the image itself (needs dsh-vision-bridge or a vision-capable model).",
   "keywords": [
     "deepseek-harness",
     "dsh",