@goodandready/dsh-image-gen 0.10.31 → 0.10.32

package/lib/fallback-router.js

@@ -0,0 +1,163 @@
+// fallback-router.js — Smart Provider Fallback Chain for image generation (#282).
+// Automatically cascades across configured providers on 429, 5xx, timeouts,
+// quota depletion, and network issues without failing the user's turn.
+
+import { formatErrorMessage } from './provider-utils.js'
+
+/**
+ * Checks if an error is strictly a prompt-level safety or client syntax violation
+ * that cannot be fixed by switching to a different provider.
+ *
+ * @param {Error|any} error
+ * @returns {boolean} true if fatal prompt/content violation, false if provider-level retryable
+ */
+export function isFatalPromptError(error) {
+  const msg = (error?.message || String(error || '')).toLowerCase()
+  return (
+    msg.includes('content policy') ||
+    msg.includes('safety system') ||
+    msg.includes('nsfw') ||
+    msg.includes('moderation') ||
+    msg.includes('prompt is required') ||
+    msg.includes('empty prompt') ||
+    msg.includes('invalid_prompt') ||
+    msg.includes('unsupported image format')
+  )
+}
+
+/**
+ * Checks whether an error is retryable by switching to another provider.
+ * Covers 429 (rate limit), 5xx (server error), timeout, payment/quota depletion, and network dropouts.
+ *
+ * @param {Error|any} error
+ * @returns {boolean}
+ */
+export function isRetryableProviderError(error) {
+  if (isFatalPromptError(error)) return false
+  const msg = (error?.message || String(error || '')).toLowerCase()
+  return (
+    msg.includes('429') ||
+    msg.includes('rate limit') ||
+    msg.includes('too many requests') ||
+    msg.includes('500') ||
+    msg.includes('502') ||
+    msg.includes('503') ||
+    msg.includes('504') ||
+    msg.includes('bad gateway') ||
+    msg.includes('service unavailable') ||
+    msg.includes('gateway timeout') ||
+    msg.includes('timeout') ||
+    msg.includes('timed out') ||
+    msg.includes('aborted') ||
+    msg.includes('402') ||
+    msg.includes('payment required') ||
+    msg.includes('insufficient_quota') ||
+    msg.includes('insufficient credits') ||
+    msg.includes('exceeded your current quota') ||
+    msg.includes('balance is insufficient') ||
+    msg.includes('quota') ||
+    msg.includes('credit') ||
+    msg.includes('unauthorized') ||
+    msg.includes('401') ||
+    msg.includes('invalid api key') ||
+    msg.includes('econnrefused') ||
+    msg.includes('enotfound') ||
+    msg.includes('fetch failed') ||
+    msg.includes('network')
+  )
+}
+
+/**
+ * Resolves the candidate evaluation order:
+ * Primary provider first, followed by explicit fallbackProviders, then remaining known providers.
+ *
+ * @param {string} primary
+ * @param {string[]} [configuredFallbacks=[]]
+ * @param {string[]} [allProviders=[]]
+ * @returns {string[]}
+ */
+export function resolveFallbackChain(primary, configuredFallbacks = [], allProviders = []) {
+  const chain = [primary]
+  if (Array.isArray(configuredFallbacks)) {
+    for (const p of configuredFallbacks) {
+      if (typeof p === 'string' && p.trim() && !chain.includes(p.trim())) {
+        chain.push(p.trim())
+      }
+    }
+  }
+  if (Array.isArray(allProviders)) {
+    for (const p of allProviders) {
+      if (typeof p === 'string' && p.trim() && !chain.includes(p.trim())) {
+        chain.push(p.trim())
+      }
+    }
+  }
+  return chain
+}
+
+/**
+ * Executes image generation across a cascade of providers with full attempt diagnostics.
+ *
+ * @param {Record<string, (seed: number, prompt: string) => Promise<any>>} generators
+ * @param {string[]} chain Ordered list of providers to try
+ * @param {number} seed
+ * @param {string} prompt
+ * @param {object} [options]
+ * @returns {Promise<any>} Produced image with attached _fallback metadata
+ */
+export async function executeWithFallback(generators, chain, seed, prompt, options = {}) {
+  const attempts = []
+  const primaryProvider = chain[0] || 'unknown'
+  const logger = options.logger || null
+
+  for (let i = 0; i < chain.length; i++) {
+    const providerKey = chain[i]
+    const generator = generators[providerKey]
+    if (typeof generator !== 'function') {
+      continue
+    }
+
+    const startTime = Date.now()
+    try {
+      const produced = await generator(seed, prompt)
+      if (produced) {
+        const isFallback = providerKey !== primaryProvider
+        produced._fallback = {
+          triggered: isFallback,
+          primaryProvider,
+          providerUsed: providerKey,
+          attempts: [
+            ...attempts,
+            { provider: providerKey, durationMs: Date.now() - startTime, success: true },
+          ],
+        }
+        if (isFallback && logger && typeof logger.info === 'function') {
+          logger.info(`[dsh-image-gen] Fallback triggered: ${primaryProvider} -> ${providerKey}`)
+        }
+        return produced
+      }
+    } catch (err) {
+      const durationMs = Date.now() - startTime
+      const formatted = formatErrorMessage(err, providerKey)
+      attempts.push({
+        provider: providerKey,
+        error: formatted,
+        durationMs,
+        success: false,
+      })
+
+      if (isFatalPromptError(err)) {
+        throw new Error(`Content or policy error on ${providerKey} (not cascading): ${formatted}`)
+      }
+
+      if (logger && typeof logger.warn === 'function') {
+        logger.warn(`[dsh-image-gen] Provider ${providerKey} failed: ${formatted}. Trying next candidate...`)
+      }
+    }
+  }
+
+  const failureSummary = attempts
+    .map((a) => `${a.provider} (${a.durationMs}ms): ${a.error}`)
+    .join('; ')
+  throw new Error(`Image generation cascade failed on all ${attempts.length} attempted providers: ${failureSummary}`)
+}

package/lib/index.js

@@ -264,6 +264,10 @@ export const Config = z.object({
     .boolean()
     .description('Content-addressed disk caching for identical generations (<50ms retrieval, zero API cost). On by default.')
     .default(true),
+  fallbackProviders: z
+    .array(z.string())
+    .description('Ordered list of fallback providers to cascade to if the primary encounters 429, 5xx, or quota limits.')
+    .default([]),
 })
 
 /** Keep a file stem safe for the filesystem. */

package/lib/register-tools.js

@@ -11,6 +11,9 @@ import { registerSketchTools } from './tools/sketch.js'
 import { registerSpritesheetTools } from './tools/spritesheet.js'
 import { registerPatternTools } from './tools/pattern.js'
 import { registerResponsiveTools } from './tools/responsive.js'
+import { registerAnchorTools } from './tools/anchor.js'
+import { registerUiAssetTools } from './tools/ui-asset.js'
+import { registerStyleMatrixTools } from './tools/style-matrix.js'
 
 /**
  * Registers every image-gen tool on the host tools service.
@@ -29,4 +32,7 @@ export function registerAllTools(ctx, deps) {
   registerSpritesheetTools(ctx, deps)
   registerPatternTools(ctx, deps)
   registerResponsiveTools(ctx, deps)
+  registerAnchorTools(ctx, deps)
+  registerUiAssetTools(ctx, deps)
+  registerStyleMatrixTools(ctx, deps)
 }

package/lib/style-matrix-helpers.js

@@ -0,0 +1,85 @@
+// style-matrix-helpers.js — Helpers for generate_style_matrix tool (#286).
+
+export const DEFAULT_MATRIX_STYLES = [
+  'editorial_photo',
+  'flat_vector',
+  'clay_3d',
+  'cyberpunk',
+]
+
+export const MATRIX_PRESET_PROMPTS = {
+  editorial_photo: 'editorial magazine photograph, 35mm film, soft diffused cinematic lighting, award-winning shot, ultra-detailed',
+  flat_vector: 'minimal flat vector art, clean sharp lines, bold solid colors, geometric modern graphic illustration',
+  clay_3d: 'charming 3D claymation plasticine sculpt, handcrafted clay texture, stop-motion animation aesthetic, miniature depth of field',
+  cyberpunk: 'gritty cyberpunk scene, neon reflections, rain-slicked chrome, dark synthwave palette, high-tech dystopian atmosphere',
+  cinematic: 'cinematic still frame, 70mm Panavision anamorphic lens, dramatic moody lighting, atmospheric haze',
+  anime: 'vibrant modern anime keyframe, Makoto Shinkai aesthetic, luminous skies, crisp cel shading',
+  isometric_3d: 'isometric 3D diorama render, Blender 3D, orthographic perspective, cute stylized textures',
+  analog_film: 'vintage 1970s Kodachrome analog film print, authentic grain, faded warm tones, nostalgic vignette',
+}
+
+/**
+ * Normalizes input styles into exactly 4 distinct style strings.
+ *
+ * @param {string[]|undefined} inputStyles
+ * @returns {string[]}
+ */
+export function normalizeMatrixStyles(inputStyles) {
+  const result = []
+  if (Array.isArray(inputStyles)) {
+    for (const s of inputStyles) {
+      if (typeof s === 'string' && s.trim()) {
+        const clean = s.trim().toLowerCase()
+        if (!result.includes(clean)) result.push(clean)
+      }
+      if (result.length === 4) break
+    }
+  }
+
+  // Backfill up to 4 using defaults
+  for (const def of DEFAULT_MATRIX_STYLES) {
+    if (result.length >= 4) break
+    if (!result.includes(def)) result.push(def)
+  }
+
+  return result.slice(0, 4)
+}
+
+/**
+ * Builds the full prompt for a matrix quadrant cell.
+ *
+ * @param {string} basePrompt
+ * @param {string} styleName
+ * @returns {string}
+ */
+export function buildMatrixCellPrompt(basePrompt, styleName) {
+  const cleanBase = String(basePrompt || '').trim()
+  const presetDirective = MATRIX_PRESET_PROMPTS[styleName] || (styleName + ' style, aesthetic rendering')
+  return cleanBase + ', ' + presetDirective
+}
+
+/**
+ * Formats a 2x2 markdown presentation grid for chat models.
+ *
+ * @param {object} params
+ * @param {string} params.basePrompt
+ * @param {boolean} params.blindMode
+ * @param {Array<{id: string, style: string, path: string, url: string, seed: number}>} params.cells
+ * @returns {string}
+ */
+export function formatMatrixMarkdown({ basePrompt, blindMode, cells }) {
+  const lines = [
+    '### Style Matrix (2×2 Benchmark): "' + basePrompt + '"',
+    blindMode ? '_Blind Comparison Mode: styles masked until evaluated_' : '',
+    '',
+    '| Cell | Style Preset | Seed | Path |',
+    '| :---: | :--- | :---: | :--- |',
+  ]
+
+  for (const c of cells) {
+    const styleLabel = blindMode ? ('Option ' + c.id) : ('**' + c.style + '**')
+    lines.push('| **' + c.id + '** | ' + styleLabel + ' | `' + c.seed + '` | `' + c.path + '` |')
+  }
+
+  return lines.filter(Boolean).join('\n')
+}

package/lib/tools/anchor.js

@@ -0,0 +1,129 @@
+// anchor.js — set_style_anchor tool (#283).
+// Manages persistent visual style & character reference anchors in session context.
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import {
+  setSessionAnchor,
+  getSessionAnchor,
+  clearSessionAnchor,
+  normalizeAnchorStrength,
+} from '../anchor-helpers.js'
+import { toLosslessJson } from '../providers.js'
+
+export function registerAnchorTools(ctx, deps) {
+  const { live, resolveSource } = deps
+
+  ctx.effect(() => {
+    ctx.tools.register(
+      defineTool({
+        name: 'set_style_anchor',
+        description:
+          'Set or clear a persistent visual anchor (character identity or artstyle) for this session. '
+          + 'Subsequent image generations automatically adhere to this reference to maintain visual continuity.',
+        parameters: {
+          image: {
+            type: 'string',
+            description: 'URL, local file path, or attachment id (sha256:...) to use as the visual anchor. Required unless clear is true.',
+          },
+          label: {
+            type: 'string',
+            description: 'Human-readable descriptor, e.g. "Protagonist Alex" or "Dark Synthwave 3D".',
+          },
+          mode: {
+            type: 'string',
+            enum: ['style', 'character'],
+            description: 'Anchor mode: "character" preserves facial/physical identity; "style" preserves artistic rendering, lighting, and palette. Default: style.',
+          },
+          strength: {
+            type: 'number',
+            description: 'Reference influence strength between 0.1 and 1.0 (default 0.65).',
+          },
+          clear: {
+            type: 'boolean',
+            description: 'When true, clears the active anchor for this session instead of setting a new one.',
+          },
+        },
+        output: {
+          schema: {
+            type: 'object',
+            additionalProperties: true,
+            properties: {
+              ok: { type: 'boolean' },
+              action: { type: 'string' },
+              anchor: {
+                type: 'object',
+                additionalProperties: true,
+                properties: {
+                  image: { type: 'string' },
+                  label: { type: 'string' },
+                  mode: { type: 'string' },
+                  strength: { type: 'number' },
+                  updatedAt: { type: 'string' },
+                },
+              },
+              summary: { type: 'string' },
+            },
+          },
+          render(args, value) {
+            return [{ type: 'text', text: value.summary || 'Style anchor updated.' }]
+          },
+        },
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+          const cfg = live ? live() : {}
+          if (cfg.enabled === false) {
+            throw new Error('Image generation plugin is disabled in settings.')
+          }
+
+          const sessionId = exec?.agent?.session?.id || exec?.agent?.session?.header?.id || 'session'
+
+          if (args.clear) {
+            const existed = clearSessionAnchor(sessionId)
+            const summary = existed
+              ? 'Active visual style anchor was cleared for this session.'
+              : 'No active visual style anchor was set for this session.'
+            return toLosslessJson({
+              ok: true,
+              action: 'cleared',
+              summary,
+            })
+          }
+
+          if (!args.image || typeof args.image !== 'string' || !args.image.trim()) {
+            throw new Error('Parameter "image" (URL, file path, or sha256 attachment ID) is required to set an anchor.')
+          }
+
+          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')
+
+          // Validate source readability if it is a local path or attachment
+          if (resolveSource && (imageRef.startsWith('sha256:') || !imageRef.startsWith('http'))) {
+            try {
+              await resolveSource(ctx, exec, imageRef)
+            } catch (err) {
+              // Best effort check; non-blocking if remote URL or future attachment
+            }
+          }
+
+          const anchor = setSessionAnchor(sessionId, {
+            image: imageRef,
+            label,
+            mode,
+            strength,
+          })
+
+          const summary = `Visual anchor "${label}" (${mode} mode, strength: ${strength}) is now active for this session. Subsequent generations will align with this reference.`
+
+          return toLosslessJson({
+            ok: true,
+            action: 'set',
+            anchor,
+            summary,
+          })
+        },
+      }),
+    )
+  }, 'dsh-image-gen: tool set_style_anchor')
+}

package/lib/tools/generation.js

@@ -52,6 +52,8 @@ import { calculateGenerationCost, recordSpend, assertBudgetAvailable } from '../
 import { trackAndAssertLoopGuard } from '../loop-guard.js'
 import { sanitizeErrorAndLogs } from '../security.js'
 import { getCachedGeneration, setCachedGeneration } from '../generation-cache.js'
+import { resolveFallbackChain, executeWithFallback } from '../fallback-router.js'
+import { getSessionAnchor, applyAnchorPromptHints } from '../anchor-helpers.js'
 import {
   extractDesignTokens,
   generateCssGradient,
@@ -173,6 +175,14 @@ export function registerGenerationTools(ctx, deps) {
           type: 'boolean',
           description: 'Optional flag to bypass content-addressed cache and force a new API generation.',
         },
+        reference_image: {
+          type: 'string',
+          description: 'Optional reference image (URL, path, or sha256:...) for character or style consistency.',
+        },
+        reference_strength: {
+          type: 'number',
+          description: 'Optional strength of reference anchor influence (0.1 to 1.0).',
+        },
       },
       output: {
         schema: {
@@ -266,7 +276,13 @@ export function registerGenerationTools(ctx, deps) {
         const enhanced = await enhancePrompt(ctx, cfg, args.prompt, exec.signal, provider)
         const effectiveStyle = args.style || cfg.stylePreset
         const styleInfo = resolveStylePreset(effectiveStyle, args.negative_prompt, args.guidance_scale)
-        const effectivePrompt = styleInfo.promptSuffix ? `${enhanced.prompt}, ${styleInfo.promptSuffix}` : enhanced.prompt
+        let effectivePrompt = styleInfo.promptSuffix ? `${enhanced.prompt}, ${styleInfo.promptSuffix}` : enhanced.prompt
+        const activeAnchor = getSessionAnchor(sessionId)
+        if (args.reference_image) {
+          effectivePrompt = `${effectivePrompt}, visual reference anchor`
+        } else if (activeAnchor) {
+          effectivePrompt = applyAnchorPromptHints(activeAnchor, effectivePrompt)
+        }
 
         // #165: Negative prompt sanitizer for diffusion models
         let effectiveNegative = styleInfo.negativePrompt
@@ -419,7 +435,7 @@ export function registerGenerationTools(ctx, deps) {
         const seedBase = args.seed ?? Math.floor(Math.random() * 100000)
         // Fallback cascade: evaluate configured provider, falling back to alternates
         // (fal -> custom -> codex -> grok), accumulating failure diagnostics.
-        const order = fallbackOrder(provider)
+        const order = resolveFallbackChain(provider, cfg.fallbackProviders, PROVIDER_KEYS)
         const qgEnabled = args.quality_gate ?? cfg.qualityGate
         const generators = Object.fromEntries(PROVIDER_KEYS.map((k) => [
           k,
@@ -512,7 +528,7 @@ export function registerGenerationTools(ctx, deps) {
           const tasks = batchPrompts.map((item, i) => async () => {
             const text = typeof item === 'string' ? item : (item && item.text) || ''
             const cached = await checkCache(seedBase + i, text)
-            return cached || await tryGenerate(generators, order, seedBase + i, text)
+            return cached || await executeWithFallback(generators, order, seedBase + i, text, { logger: ctx.logger })
           })
           const parallelResults = await asyncPool(tasks, 3)
           images.push(...parallelResults)
@@ -520,7 +536,7 @@ export function registerGenerationTools(ctx, deps) {
           const count = normalizeCount(args.count)
           const tasks = Array.from({ length: count }, (_, i) => async () => {
             const cached = await checkCache(seedBase + i, effectivePrompt)
-            return cached || await tryGenerate(generators, order, seedBase + i)
+            return cached || await executeWithFallback(generators, order, seedBase + i, effectivePrompt, { logger: ctx.logger })
           })
           const parallelResults = await asyncPool(tasks, 3)
           images.push(...parallelResults)
@@ -538,7 +554,7 @@ export function registerGenerationTools(ctx, deps) {
           cost: first.cost,
           attachmentId: first.attachment?.attachmentId || 'N/A',
         })
-        return toLosslessJson({ summary: dualOutputSummary, channel: provider, provider, model: cfg.model || cfg.customModel, ...first, images })
+        return toLosslessJson({ summary: dualOutputSummary, channel: provider, provider, model: cfg.model || cfg.customModel, _fallback: first._fallback, anchor: activeAnchor ? { label: activeAnchor.label, mode: activeAnchor.mode } : undefined, ...first, images })
       },
     }),
   )