@goodandready/dsh-image-gen 0.11.26 → 0.11.28

package/lib/providers/shared-helpers.js

@@ -115,7 +115,7 @@ export async function submitJob(fetchImpl, baseURL, model, key, body, signal) {
   return data
 }
 
-export async function pollStatus(fetchImpl, statusUrl, key, signal, pollIntervalMs = 500, timeoutMs = 180000) {
+export async function pollStatus(fetchImpl, statusUrl, key, signal, pollIntervalMs = 500, timeoutMs = 180000, onProgress) {
   const deadline = Date.now() + timeoutMs
   let attempt = 0
   for (;;) {
@@ -138,6 +138,21 @@ export async function pollStatus(fetchImpl, statusUrl, key, signal, pollInterval
     const res = await fetchImpl(statusUrl, { headers: { Authorization: falAuthHeader(key) }, signal })
     const data = await res.json().catch(() => ({}))
     const status = data.status
+    if (typeof onProgress === 'function') {
+      if (status === 'IN_QUEUE') {
+        const pos = data.queue_position
+        onProgress({
+          stage: pos !== undefined ? `In queue (#${pos})` : 'In queue',
+          progress: undefined, // honest status: do NOT simulate fake percentage
+        })
+      } else if (status === 'IN_PROGRESS') {
+        const rawProg = typeof data.progress === 'number' ? Math.round(data.progress * 100) : undefined
+        onProgress({
+          stage: 'Generating...',
+          progress: rawProg,
+        })
+      }
+    }
     if (status === 'COMPLETED') return data
     if (status === 'ERROR' || data.error || data.detail) {
       throw new Error(`FAL generation failed: ${JSON.stringify(data).slice(0, 600)}`)
@@ -148,6 +163,53 @@ export async function pollStatus(fetchImpl, statusUrl, key, signal, pollInterval
   }
 }
 
+/**
+ * Normalizes mask bytes for OpenAI/Custom inpainting where transparent alpha (0) indicates edit region.
+ * If the incoming mask has an alpha channel with transparent areas, it is preserved.
+ * If the incoming mask is opaque black & white (e.g. from Canvas), white pixels are converted to transparent (alpha 0)
+ * and black pixels to opaque (alpha 255).
+ *
+ * @param {Buffer|Uint8Array} maskBytes
+ * @returns {Promise<Buffer>}
+ */
+export async function normalizeMaskAlpha(maskBytes) {
+  if (!maskBytes || maskBytes.length === 0) return maskBytes
+  try {
+    const img = sharp(maskBytes)
+    const { data, info } = await img.raw().ensureAlpha().toBuffer({ resolveWithObject: true })
+    const { width, height, channels } = info
+
+    let hasTransparency = false
+    for (let i = 3; i < data.length; i += channels) {
+      if (data[i] < 250) {
+        hasTransparency = true
+        break
+      }
+    }
+
+    if (hasTransparency) {
+      return await sharp(data, { raw: { width, height, channels } }).png().toBuffer()
+    }
+
+    const out = Buffer.from(data)
+    for (let i = 0; i < out.length; i += channels) {
+      const r = out[i]
+      const g = out[i + 1]
+      const b = out[i + 2]
+      const lum = 0.299 * r + 0.587 * g + 0.114 * b
+      if (lum > 128) {
+        out[i + 3] = 0
+      } else {
+        out[i + 3] = 255
+      }
+    }
+
+    return await sharp(out, { raw: { width, height, channels } }).png().toBuffer()
+  } catch (_) {
+    return maskBytes
+  }
+}
+
 export function buildEditForm({ source, mask, prompt, size, strength, model }) {
   const form = new FormData()
   if (model) form.append('model', model)

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

@@ -19,6 +19,12 @@ import { registerThemePairTools } from './tools/theme-pair.js'
 import { registerCharacterSheetTools } from './tools/character-sheet.js'
 import { registerVisionOcrTools } from './tools/vision-ocr.js'
 import { registerDiagramTools } from './tools/diagram.js'
+import {
+  createLiveProgressSession,
+  publishLiveProgress,
+  completeLiveProgress,
+  abortLiveProgress,
+} from './live-progress.js'
 
 /**
  * Registers every image-gen tool on the host tools service according to toolsetProfile (#337, #384).
@@ -43,7 +49,21 @@ 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.')
             }
-            return originalExecute(args, exec)
+            const safeArgs = args || {}
+            const safeExec = exec || {}
+            const callId = safeExec.callId || safeExec.rootCallId
+            if (callId) {
+              createLiveProgressSession(callId, { signal: safeExec.signal })
+              safeExec.onProgress = (update) => publishLiveProgress(callId, update)
+            }
+            try {
+              const res = await originalExecute(safeArgs, safeExec)
+              if (callId) completeLiveProgress(callId)
+              return res
+            } catch (err) {
+              if (callId) abortLiveProgress(callId, err.message)
+              throw err
+            }
           },
         }
         const res = originalToolsRegister(wrappedDef)

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/editing.js

@@ -98,6 +98,21 @@ export function registerEditingTools(ctx, deps, options = {}) {
             const source = await resolveConversationImage(ctx, exec, args.image)
           const maskRef = args.mask_image || args.mask
           const mask = maskRef ? await resolveSource(ctx, exec, maskRef) : undefined
+          if (mask && mask.bytes && source && source.bytes) {
+            try {
+              const sharpMod = await import('sharp')
+              const sharp = sharpMod.default || sharpMod
+              const srcMeta = await sharp(source.bytes).metadata()
+              const maskMeta = await sharp(mask.bytes).metadata()
+              if (srcMeta.width && srcMeta.height && (maskMeta.width !== srcMeta.width || maskMeta.height !== srcMeta.height)) {
+                const resized = await sharp(mask.bytes).resize(srcMeta.width, srcMeta.height, { fit: 'fill' }).png().toBuffer()
+                mask.bytes = resized
+                mask.mediaType = 'image/png'
+              }
+            } catch (_err) {
+              // Mask dimension normalization failure ignored
+            }
+          }
           const vision = await analyzeImageWithVision(ctx, exec, source)
 
           let effectivePrompt = args.prompt
@@ -127,6 +142,8 @@ export function registerEditingTools(ctx, deps, options = {}) {
             strength,
             provider,
             signal: exec?.signal,
+            onProgress: exec?.onProgress,
+            callId: exec?.callId,
           }
 
           const gen = await editImageDirect(deps, job)

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

@@ -1,3 +1,4 @@
+import { buildPresentationMeta } from '../attachment-helper.js'
 import { registerGenerationPackTool } from './generation-pack.js'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import path from 'node:path'
@@ -282,12 +283,16 @@ export function registerGenerationTools(ctx, deps, options = {}) {
           const summary = lines.join('\n')
           if (live().deliverAs !== 'image') {
             const urls = list.map((img) => img.url).filter(Boolean)
-            return [{ type: 'text', text: urls.length ? `${summary}\n${urls.join('\n')}` : summary }]
+            const mdLinks = list.map((img) => `![Generated Image](${img.url})`).join('\n')
+            return [{ type: 'text', text: urls.length ? `${summary}\n${mdLinks}` : summary }]
           }
           const blocks = [{ type: 'text', text: summary }]
           for (const img of list) if (img.attachment) blocks.push({ type: 'image', attachment: img.attachment })
           return blocks
         },
+        presentationMeta(args, value) {
+          return buildPresentationMeta(value)
+        },
       },
       isConcurrencySafe: () => false,
       timeoutMs: (config?.timeoutMs || 180000) + 30000,
@@ -295,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,
@@ -321,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
@@ -334,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 },
+          {
+            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,
@@ -440,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)