@goodandready/dsh-image-gen 0.10.23 → 0.10.24

package/lib/providers.js

@@ -1,239 +1,54 @@
 /**
  * Returns candidate API key names considering known aliases (e.g. FAL_API_KEY <-> FAL_KEY).
  */
-export function resolveApiKeyCandidates(ref) {
-  if (!ref) return []
-  const candidates = [ref]
-  if (ref === 'FAL_API_KEY') candidates.push('FAL_KEY')
-  else if (ref === 'FAL_KEY') candidates.push('FAL_API_KEY')
-  return candidates
-}
-
-
-export const PROVIDER_MAX_COUNTS = {
-  fal: 4,
-  replicate: 4,
-  custom: 10,
-  seedream: 10,
-  gemini: 4,
-  codex: 1,
-  grok: 1,
-  local: 4,
-}
-
-export function clampProviderCount(provider, count) {
-  const max = PROVIDER_MAX_COUNTS[provider] || 4
-  return normalizeCount(count, max)
-}
-
-export function buildEndpointUrl(baseURL, pathSuffix) {
-  const base = String(baseURL || '').trim().replace(/\/+$/, '')
-  const suffix = String(pathSuffix || '').trim().replace(/^\/+/, '')
-  return `${base}/${suffix}`
-}
-
-export function createAbortError(message = 'Image generation cancelled') {
-  const err = new Error(message)
-  err.name = 'AbortError'
-  return err
-}
-
-
-/** Fast Laplacian-like sharpness and entropy estimator across image scanlines. */
-export function estimateSharpnessAndVariance(bytes) {
-  const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes || [])
-  if (!buf || buf.length < 64) {
-    return { score: 0, passed: false, isBlank: true, reason: 'Empty or corrupt image buffer' }
-  }
-  let sum = 0
-  let diffSum = 0
-  const sampleStep = Math.max(1, Math.floor(buf.length / 4096))
-  let count = 0
-  for (let i = 8; i < buf.length - sampleStep; i += sampleStep) {
-    const v = buf[i]
-    const nextV = buf[i + sampleStep]
-    sum += v
-    diffSum += Math.abs(v - nextV)
-    count++
-  }
-  const avgDiff = count > 0 ? diffSum / count : 0
-  if (avgDiff < 2) {
-    return { score: 0.1, passed: false, isBlank: true, reason: 'Image appears blank or solid monochrome' }
-  }
-  const score = Math.min(0.98, Math.max(0.3, +(0.5 + (avgDiff / 255) * 0.5).toFixed(2)))
-  return { score, passed: score >= 0.5, isBlank: false, avgDiff: +avgDiff.toFixed(2) }
-}
-
-/** Adaptive color palette quantizer for SVG vectorization. */
-export function quantizePalette(colorMode = 'color', paletteSize = 16) {
-  if (colorMode === 'binary') return ['#000000', '#ffffff']
-  if (colorMode === 'grayscale') return ['#000000', '#444444', '#888888', '#cccccc', '#ffffff']
-  // Standard vibrant UI vector palette
-  return [
-    '#000000', '#ffffff', '#e11d48', '#2563eb',
-    '#16a34a', '#ca8a04', '#9333ea', '#0891b2',
-    '#475569', '#64748b', '#94a3b8', '#cbd5e1'
-  ].slice(0, Math.max(2, paletteSize))
-}
-
-
-/** Format parameters in standard Automatic1111 / ComfyUI text format for drag-and-drop support. */
-export function formatA1111Parameters(metadata = {}) {
-  if (typeof metadata === 'string') return metadata
-  const prompt = metadata.prompt || ''
-  const neg = metadata.negative_prompt || metadata.negativePrompt || ''
-  const seed = metadata.seed ?? ''
-  const size = metadata.size || (metadata.width && metadata.height ? `${metadata.width}x${metadata.height}` : '1024x1024')
-  const model = metadata.model || metadata.provider || ''
-  const steps = metadata.steps || 20
-  const cfg = metadata.cfg_scale || metadata.guidance_scale || 7
-
-  let out = prompt
-  if (neg) out += `\nNegative prompt: ${neg}`
-  out += `\nSteps: ${steps}, Sampler: Euler, CFG scale: ${cfg}, Seed: ${seed}, Size: ${size}, Model: ${model}`
-  return out
-}
-
-
-import { createHash } from 'node:crypto'
-
-/** Deterministic sha256 hash for image generation caching. */
-export function computeGenerationHash({ provider, model, prompt, seed, size, style }) {
-  const norm = [
-    String(provider || '').trim().toLowerCase(),
-    String(model || '').trim().toLowerCase(),
-    String(prompt || '').trim(),
-    String(seed ?? ''),
-    String(size || '').trim().toLowerCase(),
-    String(style || '').trim().toLowerCase(),
-  ].join('|')
-  return createHash('sha256').update(norm).digest('hex')
-}
-
-// Image generation provider implementations.
-//
-// A provider receives a generation job and returns finished image bytes. Everything
-// that follows (attachments, workspace files, links, card rendering) is shared
-// across all providers and lives in index.js.
-//
-// Network is injected via fetchImpl and keys via resolveKey, enabling fully isolated unit tests.
-
-export const PROVIDER_KEYS = ['fal', 'custom', 'codex', 'grok', 'local', 'seedream', 'gemini', 'replicate']
-
-/** Clamp count from tool arguments to range 1..4. */
-/** Provider fallback ordering: primary provider first, followed by PROVIDER_KEYS. */
-export function fallbackOrder(primary) {
-  return [primary, ...PROVIDER_KEYS.filter((k) => k !== primary)]
-}
-
-/**
- * Iterates through candidate generators, returning the first successful result.
- * Throws an aggregate error if all candidates fail.
- * @param generators - array of (key, seed) => Promise<generated> functions.
- * @param order - candidate key evaluation order.
- */
-
-/** Calculate exponential backoff delay with jitter. */
-export function calculateBackoff(attempt, baseInterval = 500, maxInterval = 5000, jitterFactor = 0.2) {
-  const exp = Math.min(maxInterval, baseInterval * Math.pow(1.3, attempt))
-  const jitter = exp * jitterFactor * (Math.random() * 2 - 1)
-  return Math.max(100, Math.floor(exp + jitter))
-}
-
-/** Check if an error is a fatal client error that should NOT be cascaded to other providers. */
-export function isFatalClientError(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('bad request (http 400') ||
-    msg.includes('invalid_prompt') ||
-    msg.includes('prompt is required') ||
-    msg.includes('unsupported image format') ||
-    msg.includes('402 payment required') ||
-    msg.includes('insufficient_quota') ||
-    msg.includes('insufficient credits') ||
-    msg.includes('exceeded your current quota') ||
-    msg.includes('balance is insufficient')
-  )
-}
 
-/**
- * Safely extract a human-readable message from any error, object, or response.
- * Completely eliminates "[object Object]" and prevents duplicate provider prefixes (e.g. "codex: codex: ...").
- */
-export function formatErrorMessage(e, providerKey = '') {
-  if (e === null || e === undefined) {
-    return providerKey ? `${providerKey}: unknown error` : 'unknown error'
-  }
-
-  let msg = ''
-  if (typeof e === 'string') {
-    msg = e
-  } else if (typeof e === 'object') {
-    if (typeof e.message === 'string' && e.message && e.message !== '[object Object]') {
-      msg = e.message
-    } else if (typeof e.detail === 'string' && e.detail) {
-      msg = e.detail
-    } else if (e.error) {
-      if (typeof e.error === 'string') msg = e.error
-      else if (typeof e.error.message === 'string') msg = e.error.message
-      else if (typeof e.error.detail === 'string') msg = e.error.detail
-      else {
-        try { msg = JSON.stringify(e.error) } catch {}
-      }
-    } else if (typeof e.statusText === 'string' && e.statusText) {
-      msg = `HTTP ${e.status || ''} ${e.statusText}`.trim()
-    } else if (typeof e.cause === 'string') {
-      msg = e.cause
-    } else if (e.cause && typeof e.cause.message === 'string') {
-      msg = e.cause.message
-    }
-
-    if (!msg || msg === '[object Object]') {
-      try {
-        const json = JSON.stringify(e)
-        if (json && json !== '{}') {
-          msg = json.slice(0, 500)
-        }
-      } catch {}
-    }
-
-    if (!msg || msg === '[object Object]') {
-      const keys = Object.getOwnPropertyNames(e)
-      if (keys.length) {
-        msg = `error [${keys.join(', ')}]`
-      } else {
-        msg = String(e)
-      }
-    }
-  } else {
-    msg = String(e)
-  }
-
-  msg = String(msg || 'unknown error').trim()
-
-  if (providerKey) {
-    const prefixRegex = new RegExp(`^${providerKey}\\s*:\\s*`, 'i')
-    while (prefixRegex.test(msg)) {
-      msg = msg.replace(prefixRegex, '').trim()
-    }
-  }
-
-  if (!msg || msg === '[object Object]') {
-    msg = 'unknown error object'
-  } else if (msg.includes('[object Object]')) {
-    msg = msg.replace(/\[object Object\]/g, 'unknown error object').trim()
-  }
-
-  if (providerKey) {
-    return `${providerKey}: ${msg}`
-  }
-
-  return msg
-}
+// Utilities and constants extracted to provider-utils.js (#239)
+import {
+  resolveApiKeyCandidates,
+  PROVIDER_MAX_COUNTS,
+  clampProviderCount,
+  buildEndpointUrl,
+  createAbortError,
+  estimateSharpnessAndVariance,
+  quantizePalette,
+  formatA1111Parameters,
+  computeGenerationHash,
+  PROVIDER_KEYS,
+  fallbackOrder,
+  calculateBackoff,
+  isFatalClientError,
+  formatErrorMessage,
+  resolveSubscriptionSize,
+  SUBSCRIPTION_SIZES,
+  IMAGE_SIZES,
+  OUTPUT_FORMATS,
+  SIZE_PIXELS,
+  normalizeCount,
+} from './provider-utils.js'
+
+// Re-export utilities so existing imports from './providers.js' continue to work
+export {
+  resolveApiKeyCandidates,
+  PROVIDER_MAX_COUNTS,
+  clampProviderCount,
+  buildEndpointUrl,
+  createAbortError,
+  estimateSharpnessAndVariance,
+  quantizePalette,
+  formatA1111Parameters,
+  computeGenerationHash,
+  PROVIDER_KEYS,
+  fallbackOrder,
+  calculateBackoff,
+  isFatalClientError,
+  formatErrorMessage,
+  resolveSubscriptionSize,
+  SUBSCRIPTION_SIZES,
+  IMAGE_SIZES,
+  OUTPUT_FORMATS,
+  SIZE_PIXELS,
+  normalizeCount,
+} from './provider-utils.js'
 
 export async function tryGenerate(generators, order, seed, promptArg) {
   const refusals = []
@@ -251,11 +66,6 @@ export async function tryGenerate(generators, order, seed, promptArg) {
   throw new Error(`Image generation failed on all providers. ${refusals.join('; ')}`)
 }
 
-export function normalizeCount(count, max = 4) {
-  const n = Math.floor(Number(count))
-  if (!Number.isFinite(n)) return 1
-  return Math.max(1, Math.min(max, n))
-}
 
 // Subscription services use their own aspect ratio taxonomy.
 // Normalize named sizes to standard square, landscape, and portrait equivalents.
@@ -264,63 +74,6 @@ export function normalizeCount(count, max = 4) {
  * Supports named sizes (landscape_16_9, etc.), aspect ratios (16:9, 3:2, 9:16),
  * and pixel dimensions [width, height], preserving requested proportions.
  */
-export function resolveSubscriptionSize(size, aspectPixels, aspectRatio) {
-  if (size && SUBSCRIPTION_SIZES[size]) {
-    return SUBSCRIPTION_SIZES[size]
-  }
-  const ratio = String(aspectRatio || '').trim()
-  if (ratio === '16:9' || ratio === '3:2' || ratio === '4:3') {
-    return '1536x1024'
-  }
-  if (ratio === '9:16' || ratio === '2:3' || ratio === '3:4') {
-    return '1024x1536'
-  }
-  if (ratio === '1:1') {
-    return '1024x1024'
-  }
-  if (Array.isArray(aspectPixels) && aspectPixels.length === 2) {
-    const [w, h] = aspectPixels
-    if (w > h) return '1536x1024'
-    if (h > w) return '1024x1536'
-    return '1024x1024'
-  }
-  return '1024x1024'
-}
-
-export const SUBSCRIPTION_SIZES = {
-  square_hd: '1024x1024',
-  square: '1024x1024',
-  portrait_4_3: '1024x1536',
-  portrait_16_9: '1024x1536',
-  landscape_4_3: '1536x1024',
-  landscape_16_9: '1536x1024',
-}
-
-/** Image sizes accepted by fal-ai/flux-2/klein (and most FAL flux models). */
-export const IMAGE_SIZES = [
-  'square_hd',
-  'square',
-  'portrait_4_3',
-  'portrait_16_9',
-  'landscape_4_3',
-  'landscape_16_9',
-]
-
-/** Output formats accepted by the model. */
-export const OUTPUT_FORMATS = ['png', 'jpeg', 'webp']
-
-// Named sizes are a unified abstraction across all providers.
-// FAL accepts named identifiers; OpenAI-compatible gateways require WxH resolution.
-export const SIZE_PIXELS = {
-  square_hd: '1024x1024',
-  square: '512x512',
-  portrait_4_3: '768x1024',
-  portrait_16_9: '576x1024',
-  landscape_4_3: '1024x768',
-  landscape_16_9: '1024x576',
-}
-
-/** Normalize a raw key into a FAL `Authorization: Key <key>` value. */
 export function falAuthHeader(key) {
   const trimmed = String(key ?? '').trim()
   if (!trimmed) return ''
@@ -1143,6 +896,7 @@ export async function blendImagesFal({ fetchImpl, resolveKey, cfg }, { images, w
 }
 
 /** Direct image editing (inpainting / img2img) via selected provider. */
+/** @internal — direct provider call path for integration tests */
 export async function editImageDirect(deps, job) {
   const providers = makeProviders(deps, job)
   const providerKey = job.provider || deps.cfg.defaultProvider || 'fal'
@@ -1152,6 +906,7 @@ export async function editImageDirect(deps, job) {
 }
 
 /** Direct image variation via selected provider. */
+/** @internal — direct provider call path for integration tests */
 export async function varyImageDirect(deps, job) {
   const providers = makeProviders(deps, {
     ...job,

package/lib/register-tools.js

@@ -2,7 +2,8 @@
 // Each tool lives in lib/tools/* and is registered inside a labeled ctx.effect.
 
 import { registerGenerationTools } from './tools/generation.js'
-import { registerProcessingTools } from './tools/processing.js'
+import { registerProcessingTools } from './tools/processing-basic.js'
+import { registerProcessingAdvancedTools } from './tools/processing-advanced.js'
 import { registerEditingTools } from './tools/editing.js'
 import { registerInspectTools } from './tools/inspect.js'
 import { registerFrontendTools } from './tools/frontend.js'
@@ -16,6 +17,7 @@ import { registerFrontendTools } from './tools/frontend.js'
 export function registerAllTools(ctx, deps) {
   registerGenerationTools(ctx, deps)
   registerProcessingTools(ctx, deps)
+  registerProcessingAdvancedTools(ctx, deps)
   registerEditingTools(ctx, deps)
   registerInspectTools(ctx, deps)
   registerFrontendTools(ctx, deps)

package/lib/tools/{processing.js → processing-advanced.js}

@@ -1,3 +1,5 @@
+// processing-basic — core image-gen tools (remove_background, upscale_image, vectorize_image, blend_images). Split from processing.js (#239).
+
 // processing — image-gen tools (remove_background, upscale_image, vectorize_image, blend_images). Extracted from apply() (#216).
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
@@ -44,7 +46,8 @@ import {
 } from '../frontend-assets.js'
 
 
-export function registerProcessingTools(ctx, deps) {
+
+export function registerProcessingAdvancedTools(ctx, deps) {
   const {
     config,
     live,
@@ -53,274 +56,6 @@ export function registerProcessingTools(ctx, deps) {
     slugify,
     resolveApiKey,
   } = deps
-  ctx.effect(() => {
-    ctx.tools.register(
-      defineTool({
-        name: 'remove_background',
-        description: 'Remove the background of an image (path or attachment id) and return a transparent PNG.',
-        parameters: {
-          image: { type: 'string', required: true, description: 'Path or attachment id of the source image.' },
-          model: { type: 'string', description: 'FAL model for background removal (default: fal-ai/birefnet).' },
-          output_name: { type: 'string', description: 'Custom output file name without extension.' },
-        },
-        output: {
-          schema: {
-            type: 'object',
-            additionalProperties: true,
-            properties: {
-              path: { type: 'string' },
-              url: { type: 'string' },
-              width: { type: 'number' },
-              height: { type: 'number' },
-              format: { type: 'string' },
-            },
-          },
-        },
-        async execute(args, exec) {
-          try {
-            const source = await resolveSource(ctx, exec, args.image)
-            if (!source || !source.bytes) throw new Error('Source image not found: ' + args.image)
-          const cfg = live()
-          const res = await removeBackgroundFal(
-            { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg },
-            { 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 outDir = path.resolve(sessionCwd || process.cwd(), cfg.outputDir || 'generated/images')
-          await mkdir(outDir, { recursive: true })
-          const filePath = path.join(outDir, name)
-          await writeFile(filePath, res.bytes)
-          const summary = buildDualOutputMarkdown({
-            action: 'background removed',
-            filePath,
-            width: res.width || attachment.width,
-            height: res.height || attachment.height,
-            mediaType: 'image/png',
-            provider: 'fal',
-            model: args.model || 'fal-ai/birefnet',
-            attachmentId: attachment.attachmentId,
-          })
-          return toLosslessJson({
-            summary,
-            path: filePath,
-            url: localUrl,
-            width: res.width || attachment.width,
-            height: res.height || attachment.height,
-            format: 'png',
-            attachment,
-          })
-          } catch (err) {
-            throw new Error(sanitizeErrorAndLogs(err.message || err))
-          }
-        },
-      }),
-    )
-  }, 'dsh-image-gen: tool remove_background')
-  ctx.effect(() => {
-    ctx.tools.register(
-      defineTool({
-        name: 'upscale_image',
-        description: 'Upscale an image 2x or 4x with enhanced clarity and detail.',
-        parameters: {
-          image: { type: 'string', required: true, description: 'Path or attachment id of the source image.' },
-          scale: { type: 'number', description: 'Upscale factor: 2 or 4 (default: 2).' },
-          prompt: { type: 'string', description: 'Optional guiding prompt for detail reconstruction.' },
-          creativity: { type: 'number', description: 'Creativity / hallucination level from 0 to 1.' },
-          output_name: { type: 'string', description: 'Custom output file name.' },
-        },
-        output: {
-          schema: {
-            type: 'object',
-            additionalProperties: true,
-            properties: {
-              path: { type: 'string' },
-              url: { type: 'string' },
-              scale: { type: 'number' },
-              width: { type: 'number' },
-              height: { type: 'number' },
-            },
-          },
-        },
-        async execute(args, exec) {
-          try {
-            const source = await resolveSource(ctx, exec, args.image)
-            if (!source || !source.bytes) throw new Error('Source image not found: ' + args.image)
-          const cfg = live()
-          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 }
-          )
-          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 outDir = path.resolve(sessionCwd || process.cwd(), cfg.outputDir || 'generated/images')
-          await mkdir(outDir, { recursive: true })
-          const filePath = path.join(outDir, name)
-          await writeFile(filePath, res.bytes)
-          const summary = buildDualOutputMarkdown({
-            action: `upscaled (${args.scale || 2}x)`,
-            filePath,
-            width: res.width || attachment.width,
-            height: res.height || attachment.height,
-            mediaType: 'image/png',
-            provider: 'fal',
-            model: 'fal-ai/clarity-upscaler',
-            attachmentId: attachment.attachmentId,
-          })
-          return toLosslessJson({
-            summary,
-            path: filePath,
-            url: localUrl,
-            scale: args.scale || 2,
-            width: res.width || attachment.width,
-            height: res.height || attachment.height,
-            attachment,
-          })
-          } catch (err) {
-            throw new Error(sanitizeErrorAndLogs(err.message || err))
-          }
-        },
-      }),
-    )
-  }, 'dsh-image-gen: tool upscale_image')
-  ctx.effect(() => {
-    ctx.tools.register(
-      defineTool({
-        name: 'vectorize_image',
-        description: 'Convert a raster image or icon to SVG vector format.',
-        parameters: {
-          image: { type: 'string', required: true, description: 'Path or attachment id of the source image.' },
-          color_mode: { type: 'string', description: '"color" or "binary" (default: "color").' },
-          output_name: { type: 'string', description: 'Custom output file name.' },
-        },
-        output: {
-          schema: {
-            type: 'object',
-            additionalProperties: true,
-            properties: {
-              path: { type: 'string' },
-              svg: { type: 'string' },
-              format: { type: 'string' },
-            },
-          },
-        },
-        async execute(args, exec) {
-          try {
-            const source = await resolveSource(ctx, exec, args.image)
-            if (!source || !source.bytes) throw new Error('Source image not found: ' + args.image)
-            const cfg = live()
-            const res = 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 outDir = path.resolve(sessionCwd || process.cwd(), cfg.outputDir || 'generated/images')
-            await mkdir(outDir, { recursive: true })
-            const filePath = path.join(outDir, name)
-            await writeFile(filePath, res.bytes)
-
-            let attachment = null
-            let localUrl = ''
-            if (ctx.attachments?.saveImage) {
-              attachment = await ctx.attachments.saveImage({
-                data: new Uint8Array(res.bytes),
-                mediaType: 'image/svg+xml',
-                name,
-              })
-              localUrl = '/dsh-image-gen/image?id=' + encodeURIComponent(attachment.attachmentId)
-            }
-
-            const summary = `### Vectorized SVG Export\n- **File**: ${filePath}\n- **Format**: SVG (XML vector)\n- **Color mode**: ${args.color_mode || 'color'}\n- **Palette size**: ${res.palette ? res.palette.length : 16} colors\n`
-            return toLosslessJson({
-              summary,
-              path: filePath,
-              url: localUrl,
-              svg: res.svg,
-              format: 'svg',
-              attachment,
-            })
-          } catch (err) {
-            throw new Error(sanitizeErrorAndLogs(err.message || err))
-          }
-        },
-      }),
-    )
-  }, 'dsh-image-gen: tool vectorize_image')
-  ctx.effect(() => {
-    ctx.tools.register(
-      defineTool({
-        name: 'blend_images',
-        description: 'Blend multiple images (paths or attachment ids) into a coherent new composition.',
-        parameters: {
-          images: { type: 'array', items: { type: 'string' }, required: true, description: 'List of image paths or attachment ids to blend.' },
-          weights: { type: 'array', items: { type: 'number' }, description: 'Weights for each image (optional).' },
-          prompt: { type: 'string', description: 'Guiding prompt for the blend.' },
-          output_name: { type: 'string', description: 'Custom output file name.' },
-        },
-        output: {
-          schema: {
-            type: 'object',
-            additionalProperties: true,
-            properties: {
-              path: { type: 'string' },
-              url: { type: 'string' },
-              width: { type: 'number' },
-              height: { type: 'number' },
-            },
-          },
-        },
-        async execute(args, exec) {
-          try {
-            const cfg = live()
-            trackAndAssertLoopGuard(exec?.agent?.session?.id || 'default', { limit: cfg.loopGuardLimit })
-            assertBudgetAvailable(0.05, cfg.dailyBudgetUsd)
-            const refs = Array.isArray(args.images) ? args.images : [args.images].filter(Boolean)
-          const sources = []
-          for (const r of refs) {
-            const s = await resolveSource(ctx, exec, r)
-            if (s && s.bytes) sources.push(s)
-          }
-          if (sources.length === 0) throw new Error('No valid images found to blend')
-          const res = await blendImagesFal(
-            { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg },
-            { 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 outDir = path.resolve(sessionCwd || process.cwd(), cfg.outputDir || 'generated/images')
-          await mkdir(outDir, { recursive: true })
-          const filePath = path.join(outDir, name)
-          await writeFile(filePath, res.bytes)
-          const summary = buildDualOutputMarkdown({
-            action: 'blended composition',
-            filePath,
-            width: res.width || attachment.width,
-            height: res.height || attachment.height,
-            mediaType: 'image/png',
-            provider: 'fal',
-            model: 'fal-ai/image-blend',
-            attachmentId: attachment.attachmentId,
-          })
-          return toLosslessJson({
-            summary,
-            path: filePath,
-            url: localUrl,
-            width: res.width || attachment.width,
-            height: res.height || attachment.height,
-            attachment,
-          })
-          } catch (err) {
-            throw new Error(sanitizeErrorAndLogs(err.message || err))
-          }
-        },
-      }),
-    )
-  }, 'dsh-image-gen: tool blend_images')
 
   ctx.effect(() => {
     ctx.tools.register(