@goodandready/dsh-image-gen 0.11.29 → 0.11.31

package/lib/client.js

@@ -2698,7 +2698,7 @@ window.__ModuleLoader__.load({
 
       'f.geminiModel': 'Gemini Model ID',
       'f.geminiModelHint': 'Google Gemini image generation model identifier.',
-      'p.geminiModel': 'gemini-2.0-flash-exp-image-generation',
+      'p.geminiModel': 'gemini-3.1-flash-image',
       'f.geminiKeyEnv': 'Gemini Key Reference',
       'f.geminiKeyEnvHint': 'Credential reference holding Google Gemini API key.',
       'p.geminiKeyEnv': 'GEMINI_API_KEY',
@@ -2977,7 +2977,7 @@ window.__ModuleLoader__.load({
 
       'f.geminiModel': 'Gemini 模型 ID',
       'f.geminiModelHint': 'Google Gemini 图像生成模型标识符。',
-      'p.geminiModel': 'gemini-2.0-flash-exp-image-generation',
+      'p.geminiModel': 'gemini-3.1-flash-image',
       'f.geminiKeyEnv': 'Gemini 凭证名称',
       'f.geminiKeyEnvHint': '存储 Google Gemini 密钥的凭证名称。',
       'p.geminiKeyEnv': 'GEMINI_API_KEY',

package/lib/config-schema.js

@@ -177,7 +177,7 @@ export const Config = z.object({
   geminiModel: z
     .string()
     .description('Google Gemini image generation model identifier.')
-    .default('gemini-2.0-flash-exp-image-generation')
+    .default('gemini-3.1-flash-image')
     .volatile(),
   geminiKeyEnv: z
     .string()

package/lib/cost-meter.js

@@ -1,9 +1,10 @@
 // lib/cost-meter.js
-// Integration with dsh-cost-meter, rate card, and daily budget enforcer (#167)
+// Integration with dsh-cost-meter, rate card, and daily budget enforcer (#167, #353, #355)
 
 import { homedir } from 'node:os'
 import { join } from 'node:path'
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { readFileSync, writeFileSync, mkdirSync, renameSync, unlinkSync } from 'node:fs'
+import { randomBytes } from 'node:crypto'
 import { enforceSecurePermissions } from './security.js'
 
 /**
@@ -53,6 +54,27 @@ export const RATE_CARD = {
   },
 }
 
+/** Active in-flight budget reservations for serialized concurrency (#355) */
+const activeReservations = new Map()
+
+/**
+ * Returns total currently active in-flight spend reservations in USD.
+ */
+export function getTotalActiveReservations() {
+  let total = 0
+  for (const amount of activeReservations.values()) {
+    total += Number(amount) || 0
+  }
+  return +total.toFixed(4)
+}
+
+/**
+ * Clears all active in-flight reservations (for testing / session resets).
+ */
+export function clearSpendReservations() {
+  activeReservations.clear()
+}
+
 /**
  * Calculates estimated USD cost for a generation request.
  */
@@ -94,6 +116,7 @@ export function loadDailySpend() {
 
 /**
  * Records an image generation expense.
+ * Uses atomic sibling write + rename to guarantee crash-safe persistence (#355).
  */
 export function recordSpend(usdAmount, { ctx, meta = {} } = {}) {
   const amount = Number(usdAmount) || 0
@@ -106,8 +129,11 @@ export function recordSpend(usdAmount, { ctx, meta = {} } = {}) {
   current.lastUpdated = new Date().toISOString()
 
   try {
-    mkdirSync(join(filePath, '..'), { recursive: true })
-    writeFileSync(filePath, JSON.stringify(current, null, 2), 'utf8')
+    const dir = join(filePath, '..')
+    mkdirSync(dir, { recursive: true })
+    const tmpFile = `${filePath}.${randomBytes(6).toString('hex')}.tmp`
+    writeFileSync(tmpFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 })
+    renameSync(tmpFile, filePath)
     enforceSecurePermissions(filePath)
   } catch (err) {
     // Non-fatal write failure
@@ -130,7 +156,7 @@ export function recordSpend(usdAmount, { ctx, meta = {} } = {}) {
 }
 
 /**
- * Asserts that the generation does not exceed daily budget.
+ * Asserts that the generation does not exceed daily budget, accounting for active in-flight reservations (#353, #355).
  * @throws {Error} If daily budget is exceeded.
  */
 export function assertBudgetAvailable(estimatedCost, dailyBudgetUsd) {
@@ -139,11 +165,52 @@ export function assertBudgetAvailable(estimatedCost, dailyBudgetUsd) {
 
   const cost = Number(estimatedCost) || 0
   const current = loadDailySpend()
-  const projected = +(current.totalSpendUsd + cost).toFixed(4)
+  const reserved = getTotalActiveReservations()
+  const projected = +(current.totalSpendUsd + reserved + cost).toFixed(4)
   if (projected > budget) {
     throw new Error(
-      `Daily image generation budget exceeded: current spend $${current.totalSpendUsd.toFixed(2)} + estimated $${cost.toFixed(2)} exceeds limit $${budget.toFixed(2)} (Settings → Image generation → dailyBudgetUsd)`
+      `Daily image generation budget exceeded: current spend $${current.totalSpendUsd.toFixed(2)} + reserved $${reserved.toFixed(2)} + estimated $${cost.toFixed(2)} exceeds limit $${budget.toFixed(2)} (Settings → Image generation → dailyBudgetUsd)`
     )
   }
   return true
 }
+
+/**
+ * Reserves estimated budget for an in-flight generation attempt (#353, #355).
+ * Returns a settlement handle with .commit(actualCost, opts) and .release().
+ *
+ * @param {number} estimatedCost
+ * @param {number} dailyBudgetUsd
+ * @returns {{ id: string, cost: number, commit: Function, release: Function }}
+ */
+export function reserveSpend(estimatedCost, dailyBudgetUsd) {
+  const budget = Number(dailyBudgetUsd) || 0
+  const cost = Number(estimatedCost) || 0
+
+  if (budget > 0 && cost > 0) {
+    assertBudgetAvailable(cost, budget)
+  }
+
+  const id = `res_${Date.now()}_${randomBytes(4).toString('hex')}`
+  if (budget > 0 && cost > 0) {
+    activeReservations.set(id, cost)
+  }
+
+  let settled = false
+  return {
+    id,
+    cost,
+    commit(actualCost, opts) {
+      if (settled) return
+      settled = true
+      activeReservations.delete(id)
+      const effective = actualCost !== undefined ? Number(actualCost) : cost
+      return recordSpend(effective, opts)
+    },
+    release() {
+      if (settled) return
+      settled = true
+      activeReservations.delete(id)
+    },
+  }
+}

package/lib/frontend-assets.js

@@ -70,7 +70,7 @@ export function getContrastRatio(hex1, hex2) {
  * @returns {Promise<string[]>} Hex colors
  */
 export async function extractSampleColorsFromBuffer(buffer) {
-  if (!buffer || buffer.length < 8) {
+  if (!buffer || buffer.length === 0) {
     return ['#0f172a', '#3b82f6', '#10b981', '#f59e0b', '#ef4444', '#f8fafc']
   }
 
@@ -96,76 +96,79 @@ export async function extractSampleColorsFromBuffer(buffer) {
   }
 
   // Decode raster container to raw RGBA pixels via Sharp
+  let data, info
   try {
-    const { data, info } = await sharp(buffer)
+    const res = await sharp(buffer)
       .raw()
       .ensureAlpha()
       .toBuffer({ resolveWithObject: true })
+    data = res.data
+    info = res.info
+  } catch (err) {
+    throw new Error(`Failed to decode image buffer for color extraction: ${err.message}`)
+  }
 
-    const totalPixels = info.width * info.height
-    const step = Math.max(1, Math.floor(totalPixels / 2048))
-    const colorBuckets = new Map()
-
-    for (let i = 0; i < totalPixels; i += step) {
-      const off = i * 4
-      const r = data[off]
-      const g = data[off + 1]
-      const b = data[off + 2]
-      const a = data[off + 3]
-
-      // Ignore fully or mostly transparent pixels
-      if (a < 128) continue
-
-      // Quantize to 16-level RGB bins to cluster nearby nuances
-      const qr = Math.round(r / 16) * 16
-      const qg = Math.round(g / 16) * 16
-      const qb = Math.round(b / 16) * 16
-      const key = `${qr},${qg},${qb}`
-
-      let bucket = colorBuckets.get(key)
-      if (!bucket) {
-        bucket = { count: 0, rSum: 0, gSum: 0, bSum: 0 }
-        colorBuckets.set(key, bucket)
-      }
-      bucket.count++
-      bucket.rSum += r
-      bucket.gSum += g
-      bucket.bSum += b
+  const totalPixels = info.width * info.height
+  const step = Math.max(1, Math.floor(totalPixels / 2048))
+  const colorBuckets = new Map()
+
+  for (let i = 0; i < totalPixels; i += step) {
+    const off = i * 4
+    const r = data[off]
+    const g = data[off + 1]
+    const b = data[off + 2]
+    const a = data[off + 3]
+
+    // Ignore fully or mostly transparent pixels
+    if (a < 128) continue
+
+    // Quantize to 16-level RGB bins to cluster nearby nuances
+    const qr = Math.round(r / 16) * 16
+    const qg = Math.round(g / 16) * 16
+    const qb = Math.round(b / 16) * 16
+    const key = `${qr},${qg},${qb}`
+
+    let bucket = colorBuckets.get(key)
+    if (!bucket) {
+      bucket = { count: 0, rSum: 0, gSum: 0, bSum: 0 }
+      colorBuckets.set(key, bucket)
     }
+    bucket.count++
+    bucket.rSum += r
+    bucket.gSum += g
+    bucket.bSum += b
+  }
 
-    if (colorBuckets.size > 0) {
-      const sorted = Array.from(colorBuckets.values()).sort((a, b) => b.count - a.count)
-      const dominant = sorted.slice(0, 6).map((b) => {
-        return rgbToHex(b.rSum / b.count, b.gSum / b.count, b.bSum / b.count)
-      })
+  if (colorBuckets.size > 0) {
+    const sorted = Array.from(colorBuckets.values()).sort((a, b) => b.count - a.count)
+    const dominant = sorted.slice(0, 6).map((b) => {
+      return rgbToHex(b.rSum / b.count, b.gSum / b.count, b.bSum / b.count)
+    })
 
-      const result = [...dominant]
-      if (result.length < 5) {
-        const primaryRgb = hexToRgb(result[0])
-        const isNearBlack = primaryRgb.r === 0 && primaryRgb.g === 0 && primaryRgb.b === 0
-        if (isNearBlack) {
-          const darkShades = ['#1a1a1a', '#333333', '#4d4d4d', '#666666', '#808080']
-          for (const s of darkShades) {
-            if (result.length >= 6) break
-            if (!result.includes(s)) result.push(s)
-          }
-        } else {
-          const factors = [0.2, 0.4, 0.6, 0.8, 1.2, 1.4]
-          for (const factor of factors) {
-            if (result.length >= 6) break
-            const shade = rgbToHex(
-              Math.min(255, Math.round(primaryRgb.r * factor)),
-              Math.min(255, Math.round(primaryRgb.g * factor)),
-              Math.min(255, Math.round(primaryRgb.b * factor)),
-            )
-            if (!result.includes(shade)) result.push(shade)
-          }
+    const result = [...dominant]
+    if (result.length < 5) {
+      const primaryRgb = hexToRgb(result[0])
+      const isNearBlack = primaryRgb.r === 0 && primaryRgb.g === 0 && primaryRgb.b === 0
+      if (isNearBlack) {
+        const darkShades = ['#1a1a1a', '#333333', '#4d4d4d', '#666666', '#808080']
+        for (const s of darkShades) {
+          if (result.length >= 6) break
+          if (!result.includes(s)) result.push(s)
+        }
+      } else {
+        const factors = [0.2, 0.4, 0.6, 0.8, 1.2, 1.4]
+        for (const factor of factors) {
+          if (result.length >= 6) break
+          const shade = rgbToHex(
+            Math.min(255, Math.round(primaryRgb.r * factor)),
+            Math.min(255, Math.round(primaryRgb.g * factor)),
+            Math.min(255, Math.round(primaryRgb.b * factor)),
+          )
+          if (!result.includes(shade)) result.push(shade)
         }
       }
-      return result.slice(0, 6)
     }
-  } catch (_err) {
-    // If sharp cannot decode or buffer is non-image, fallback
+    return result.slice(0, 6)
   }
 
   return ['#0f172a', '#3b82f6', '#10b981', '#f59e0b', '#ef4444', '#f8fafc']
@@ -334,6 +337,28 @@ export function checkWcagContrast(colors, textHex = '#ffffff') {
   }
 }
 
+/**
+ * Decode common HTML numeric and named entities in SVG attribute values (#374)
+ * @param {string} str
+ * @returns {string}
+ */
+export function decodeHtmlEntities(str) {
+  if (!str || typeof str !== 'string') return ''
+  return str
+    .replace(/&#x([0-9a-fA-F]+);?/gi, (_, hex) => {
+      try { return String.fromCharCode(parseInt(hex, 16)) } catch (_e) { return '' }
+    })
+    .replace(/&#([0-9]+);?/g, (_, dec) => {
+      try { return String.fromCharCode(parseInt(dec, 10)) } catch (_e) { return '' }
+    })
+    .replace(/&colon;/gi, ':')
+    .replace(/&tab;/gi, '\t')
+    .replace(/&newline;/gi, '\n')
+    .replace(/&quot;/gi, '"')
+    .replace(/&apos;/gi, "'")
+    .replace(/&amp;/gi, '&')
+}
+
 /**
  * Issue #176: optimize_vector_svg
  * Cleans, sanitizes, and minifies SVG content, normalizes viewBox, and exports React TSX component.
@@ -360,14 +385,51 @@ export function optimizeSvgContent(svgString, options = {}) {
   cleaned = cleaned.replace(/<script[^>]*\/?>/gi, '')
   cleaned = cleaned.replace(/<foreignObject[\s\S]*?<\/foreignObject>/gi, '')
   cleaned = cleaned.replace(/<foreignObject[^>]*\/?>/gi, '')
-  cleaned = cleaned.replace(/<(?:iframe|embed|object|applet)[\s\S]*?<\/(?:iframe|embed|object|applet)>/gi, '')
-  cleaned = cleaned.replace(/<(?:iframe|embed|object|applet)[^>]*\/?>/gi, '')
-
-  // Strip event handler attributes (onload, onerror, onclick, etc.)
-  cleaned = cleaned.replace(/\s+on[a-z]+\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, '')
+  cleaned = cleaned.replace(/<(?:iframe|embed|object|applet|handler|listener)[\s\S]*?<\/(?:iframe|embed|object|applet|handler|listener)>/gi, '')
+  cleaned = cleaned.replace(/<(?:iframe|embed|object|applet|handler|listener)[^>]*\/?>/gi, '')
+
+  // Security (#374): Strip dangerous SMIL animation elements (<animate>, <set>, etc.) targeting href/xlink:href/on* or containing script schemes
+  cleaned = cleaned.replace(/<(animate|set|animateTransform|animateMotion|discard)\b[^>]*>[\s\S]*?<\/\1>/gi, (block) => {
+    const norm = decodeHtmlEntities(block).replace(/[\s\x00-\x20]+/g, ' ').toLowerCase()
+    if (
+      /attributename\s*=\s*['"]?(?:href|xlink:href|src|action|formaction|on[a-z0-9_-]+)/.test(norm) ||
+      /(?:javascript|vbscript|data\s*:\s*text\/html)/.test(norm)
+    ) {
+      return ''
+    }
+    return block
+  })
+  cleaned = cleaned.replace(/<(?:animate|set|animateTransform|animateMotion|discard)\b[^>]*\/?>/gi, (tag) => {
+    const norm = decodeHtmlEntities(tag).replace(/[\s\x00-\x20]+/g, ' ').toLowerCase()
+    if (
+      /attributename\s*=\s*['"]?(?:href|xlink:href|src|action|formaction|on[a-z0-9_-]+)/.test(norm) ||
+      /(?:javascript|vbscript|data\s*:\s*text\/html)/.test(norm)
+    ) {
+      return ''
+    }
+    return tag
+  })
 
-  // Strip dangerous URI schemes (javascript:, data:text/html, vbscript:) in href/xlink:href/src/action
-  cleaned = cleaned.replace(/\s+(?:href|xlink:href|src|action)\s*=\s*(?:"\s*(?:javascript|data:text\/html|vbscript):[^"]*"|'\s*(?:javascript|data:text\/html|vbscript):[^']*')/gi, '')
+  // Strip event handler attributes (onload, onerror, onclick, etc., quoted or unquoted)
+  cleaned = cleaned.replace(/\s+on[a-z0-9_-]+\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, '')
+
+  // Security (#374): Strip dangerous URI schemes (javascript:, vbscript:, data:text/html, etc.) in href/xlink:href/src/action/formaction
+  // Handles HTML entity encoding (&#x73;), control chars, and unquoted attributes
+  cleaned = cleaned.replace(/\s+(?:href|xlink:href|src|action|formaction)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi, (match, q1, q2, unquoted) => {
+    const val = q1 !== undefined ? q1 : (q2 !== undefined ? q2 : unquoted)
+    const decoded = decodeHtmlEntities(val)
+    const normalized = decoded.replace(/[\x00-\x20\s]+/g, '').toLowerCase()
+    if (
+      normalized.startsWith('javascript:') ||
+      normalized.startsWith('vbscript:') ||
+      normalized.startsWith('data:text/html') ||
+      normalized.startsWith('data:text/javascript') ||
+      normalized.startsWith('data:image/svg+xml')
+    ) {
+      return ''
+    }
+    return match
+  })
 
   cleaned = cleaned.replace(/\s{2,}/g, ' ')
   cleaned = cleaned.replace(/>\s+</g, '><')

package/lib/generation-helpers.js

@@ -152,6 +152,7 @@ export async function saveGeneratedImageArtifact({
   slugify,
   estimatedCost,
   totalCount,
+  recordSpend: shouldRecordSpend = true,
 }) {
   const targetFormat = format || (args.output_format || cfg.defaultFormat)
   const formatted = await ensureImageFormat(gen.bytes, targetFormat, { fallbackMime: gen.mediaType })
@@ -244,6 +245,7 @@ export async function saveGeneratedImageArtifact({
     model: cfg.model,
     size,
     format,
+    aspectRatio: args.aspect_ratio || cfg.defaultAspectRatio,
     seed: gen.seed,
     cacheHash,
     thumbnailUrl: localUrl,
@@ -261,11 +263,13 @@ export async function saveGeneratedImageArtifact({
     await appendHistoryEntry(entry, { pruneDays: cfg.pruneDays, historyLimit })
   }
 
-  // #167: Record spend in cost meter
-  recordSpend(gen.cost || (estimatedCost / totalCount), {
-    ctx,
-    meta: { provider, model: cfg.model || cfg.customModel, prompt: promptArg, seed: gen.seed },
-  })
+  // #167: Record spend in cost meter (unless caller already committed attempt spend)
+  if (shouldRecordSpend !== false) {
+    recordSpend(gen.cost || (estimatedCost / totalCount), {
+      ctx,
+      meta: { provider, model: cfg.model || cfg.customModel, prompt: promptArg, seed: gen.seed },
+    })
+  }
 
   return {
     path: filePath,

package/lib/history.js

@@ -37,13 +37,38 @@ export function findCachedGeneration(entries, hash) {
   return entries.find((e) => e.cacheHash === hash)
 }
 
-export async function findCachedByPrompt(entries, prompt) {
-  return entries.find((e) => e.prompt === prompt)
+export async function findCachedByPrompt(entries, prompt, criteria = {}) {
+  if (!prompt || !Array.isArray(entries)) return undefined
+  return entries.find((e) => {
+    if (e.prompt !== prompt) return false
+    if (criteria.format) {
+      const entryFmt = (e.format || (e.mediaType || '').replace('image/', '')).toLowerCase().replace('jpeg', 'jpg')
+      const targetFmt = String(criteria.format).toLowerCase().replace('jpeg', 'jpg')
+      if (entryFmt && targetFmt && entryFmt !== targetFmt) return false
+    }
+    if (criteria.aspectRatio && e.aspectRatio && e.aspectRatio !== criteria.aspectRatio) return false
+    if (criteria.width && e.width && criteria.width !== e.width) return false
+    if (criteria.height && e.height && criteria.height !== e.height) return false
+    if (criteria.size && e.size && criteria.size !== criteria.size) return false
+    return true
+  })
 }
 
-export async function findCached(entries, seed, prompt) {
-  if (seed === undefined) return undefined
-  return entries.find((e) => e.seed === seed && e.prompt === prompt)
+export async function findCached(entries, seed, prompt, criteria = {}) {
+  if (seed === undefined || !Array.isArray(entries)) return undefined
+  return entries.find((e) => {
+    if (e.seed !== seed || e.prompt !== prompt) return false
+    if (criteria.format) {
+      const entryFmt = (e.format || (e.mediaType || '').replace('image/', '')).toLowerCase().replace('jpeg', 'jpg')
+      const targetFmt = String(criteria.format).toLowerCase().replace('jpeg', 'jpg')
+      if (entryFmt && targetFmt && entryFmt !== targetFmt) return false
+    }
+    if (criteria.aspectRatio && e.aspectRatio && e.aspectRatio !== criteria.aspectRatio) return false
+    if (criteria.width && e.width && criteria.width !== e.width) return false
+    if (criteria.height && e.height && criteria.height !== e.height) return false
+    if (criteria.size && e.size && criteria.size !== criteria.size) return false
+    return true
+  })
 }
 
 /** Return cached entry if file exists on disk, otherwise undefined. */
@@ -61,6 +86,7 @@ export async function cachedResult(entry) {
     cost: 0,
     format: (entry.mediaType || 'image/png').replace('image/', ''),
     cached: true,
+    fromCache: true,
     attachment: entry.attachmentId ? {
       attachmentId: entry.attachmentId,
       mediaType: entry.mediaType || 'image/png',

package/lib/live-progress.js

@@ -14,8 +14,10 @@ const activeSessions = new Map()
 export function createLiveProgressSession(callId, options = {}) {
   if (!callId) return null
   const existing = activeSessions.get(callId)
-  if (existing) {
-    existing.listeners.clear()
+  const listeners = existing?.listeners ? existing.listeners : new Set()
+
+  if (typeof options.onProgress === 'function') {
+    listeners.add(options.onProgress)
   }
 
   const session = {
@@ -27,7 +29,7 @@ export function createLiveProgressSession(callId, options = {}) {
     done: false,
     error: undefined,
     timestamp: Date.now(),
-    listeners: new Set(),
+    listeners,
   }
 
   if (options.signal) {

package/lib/loop-guard.js

@@ -41,15 +41,27 @@ export function trackAndAssertLoopGuard(sessionId, {
   const current = sessionStates.get(sid) || { count: 0, lastPrompt: '', lastTimestamp: 0, lastTurnId: null }
   const maxLimit = Math.max(1, Number(limit) || DEFAULT_MAX_CONSECUTIVE_GENERATIONS)
 
-  // Derive turn identifier from turnId or exec context
+  // Derive turn identifier from turnId or exec context (#370)
   const session = exec?.agent?.session
-  const derivedTurnId = turnId ??
-    exec?.turnId ??
-    exec?.agent?.turnId ??
-    exec?.message?.id ??
-    session?.lastMessageId ??
-    session?.turnId ??
-    (Array.isArray(session?.messages) ? session.messages.length : null)
+  let derivedTurnId = turnId ?? exec?.turnId ?? exec?.agent?.turnId
+
+  if (derivedTurnId === null || derivedTurnId === undefined) {
+    const rawMessages = typeof session?.deriveMessages === 'function'
+      ? session.deriveMessages()
+      : (Array.isArray(session?.messages) ? session.messages : null)
+
+    if (Array.isArray(rawMessages)) {
+      const userMessages = rawMessages.filter(m => m && (m.role === 'user' || m.type === 'user'))
+      if (userMessages.length > 0) {
+        const lastUser = userMessages[userMessages.length - 1]
+        derivedTurnId = lastUser.id ?? lastUser.turnId ?? `user_turn_${userMessages.length}`
+      }
+    }
+  }
+
+  if (derivedTurnId === null || derivedTurnId === undefined) {
+    derivedTurnId = session?.lastUserMessageId ?? session?.lastMessageId ?? session?.turnId ?? null
+  }
 
   // If turn identifier changed, reset count for the new user turn
   if (derivedTurnId !== null && derivedTurnId !== undefined) {

package/lib/providers/backends/fal.js

@@ -35,6 +35,11 @@ export function createFalGenerator(deps, job) {
         body.strength = strength
       }
     } else if (job.faceReference && (job.faceReference.bytes || job.faceReference.url)) {
+      // #375: Enforce model capability check before dispatching face identity anchors
+      const isFaceCapable = /instant-id|face-to-many|pulid|ip-adapter|face/i.test(targetModel)
+      if (!isFaceCapable) {
+        throw new Error(`Model "${targetModel}" on FAL does not support face identity anchors. Use a face-capable model (e.g. fal-ai/flux-lora/face-to-many, fal-ai/instant-id) or ComfyUI with FaceID workflow.`)
+      }
       const refDataUri = job.faceReference.bytes
         ? `data:${job.faceReference.mediaType || 'image/png'};base64,${Buffer.from(job.faceReference.bytes).toString('base64')}`
         : job.faceReference.url
@@ -45,6 +50,11 @@ export function createFalGenerator(deps, job) {
         body.reference_weight = job.faceStrength
       }
     } else if (job.referenceImage && (job.referenceImage.bytes || job.referenceImage.url)) {
+      // #375: Enforce model capability check before dispatching style reference anchors
+      const isRefCapable = /instant-id|face-to-many|pulid|ip-adapter|reference|redux/i.test(targetModel)
+      if (!isRefCapable) {
+        throw new Error(`Model "${targetModel}" on FAL does not support reference image anchors. Use a reference-capable model (e.g. fal-ai/flux/dev/redux, fal-ai/ip-adapter) or ComfyUI.`)
+      }
       const refDataUri = job.referenceImage.bytes
         ? `data:${job.referenceImage.mediaType || 'image/png'};base64,${Buffer.from(job.referenceImage.bytes).toString('base64')}`
         : job.referenceImage.url

package/lib/providers/backends/gemini.js

@@ -15,10 +15,10 @@ export function createGeminiGenerator(deps, job) {
 
   async function gemini(seedArg = seed, promptArg = prompt) {
     const key = await resolveKey(cfg.geminiKeyEnv)
-    let model = cfg.geminiModel || 'gemini-2.0-flash-exp-image-generation'
-    // #364: Transparently migrate deprecated Imagen 3/4 IDs to Gemini multimodal model
-    if (model.startsWith('imagen-') || model === 'imagen-3.0-generate-002') {
-      model = 'gemini-2.0-flash-exp-image-generation'
+    let model = cfg.geminiModel || 'gemini-3.1-flash-image'
+    // #364: Transparently migrate deprecated Imagen 3/4 IDs and preview 2.0 to current Gemini multimodal model
+    if (model.startsWith('imagen-') || model.startsWith('gemini-2.0-flash-exp')) {
+      model = 'gemini-3.1-flash-image'
     }
 
     const timeoutSignal = typeof AbortSignal !== 'undefined' && AbortSignal.timeout
@@ -53,14 +53,22 @@ export function createGeminiGenerator(deps, job) {
     }
     parts.push({ text: promptArg })
 
-    // Build unified imageConfig without quality/style overwrite collisions (#364)
+    // #364: Google Gemini ImageConfig only accepts aspectRatio and imageSize.
+    // Unofficial/deprecated fields like imageQuality or imageStyle must not be passed.
     const imageConfig = {}
-    if (aspectRatio) imageConfig.aspectRatio = aspectRatio
-    if (quality && quality !== 'auto') imageConfig.imageQuality = quality
-    if (style && style !== 'none') imageConfig.imageStyle = style
+    if (aspectRatio) {
+      const ratioMap = {
+        square: '1:1',
+        portrait_4_3: '3:4',
+        landscape_4_3: '4:3',
+        portrait_16_9: '9:16',
+        landscape_16_9: '16:9',
+      }
+      imageConfig.aspectRatio = ratioMap[aspectRatio] || aspectRatio
+    }
 
     const generationConfig = {
-      responseModalities: ['IMAGE'],
+      responseModalities: ['TEXT', 'IMAGE'],
       ...(Object.keys(imageConfig).length > 0 ? { imageConfig } : {}),
     }
 

package/lib/providers/backends/local.js

@@ -43,6 +43,13 @@ export function createLocalGenerator(deps, job) {
     }
 
     if (kind === 'a1111') {
+      // #375: Local A1111 txt2img/img2img lacks identity adapters
+      if (job.faceReference) {
+        throw new Error('Local A1111 does not support facial identity references (FaceID) — use ComfyUI (IP-Adapter/InstantID) or FAL')
+      }
+      if (job.referenceImage) {
+        throw new Error('Local A1111 does not support visual style reference anchors — use ComfyUI (IP-Adapter) or FAL')
+      }
       if (typeof onProgress === 'function') {
         onProgress({ stage: 'Generating...', progress: undefined })
       }
@@ -88,6 +95,17 @@ export function createLocalGenerator(deps, job) {
     }
 
     // ComfyUI: submit via /prompt, poll /history/{prompt_id} until completed.
+    if (job.faceReference || job.referenceImage) {
+      const wf = cfg.comfyWorkflowJson || ''
+      const hasFace = wf.includes('face_image') || wf.includes('ApplyIPAdapter') || wf.includes('InstantID') || wf.includes('FaceID')
+      const hasRef = wf.includes('reference_image') || wf.includes('ApplyIPAdapter') || wf.includes('StyleModelApply')
+      if (job.faceReference && !hasFace) {
+        throw new Error('ComfyUI requires a custom workflow with FaceID or IP-Adapter nodes to use facial identity anchors.')
+      }
+      if (job.referenceImage && !hasRef) {
+        throw new Error('ComfyUI requires a custom workflow with reference or IP-Adapter nodes to use style reference anchors.')
+      }
+    }
     const promptId = `dsh-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
     let workflowGraph
     if (cfg.comfyWorkflowJson) {

package/lib/providers/shared-helpers.js

@@ -90,9 +90,6 @@ export async function ensureImageFormat(bytes, targetFormat, { fallbackMime } =
     const verified = detectImageMediaType(transcoded) || targetMime
     return { bytes: transcoded, mediaType: verified }
   } catch (err) {
-    if (buf.length < 64) {
-      return { bytes: buf, mediaType: fallbackMime || targetMime || actualMime || 'image/png' }
-    }
     throw new Error(`Failed to encode image to ${canonical}: ${err.message}`)
   }
 }