@goodandready/dsh-image-gen 0.10.16 → 0.10.18

package/lib/index.js

@@ -13,58 +13,24 @@
 // falling back to the process environment.
 
 import z from '@deepseek-ai/schemastery'
-import { defineTool } from '@deepseek-ai/dsh-tools'
 import { credentialRef } from '@deepseek-ai/dsh-credentials'
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
-import { existsSync, unlinkSync, accessSync } from 'node:fs'
+import { existsSync, unlinkSync } from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import {
-  computeGenerationHash,
-  clampProviderCount,
-  buildEndpointUrl,
-  createAbortError,
   IMAGE_SIZES,
   OUTPUT_FORMATS,
   PROVIDER_KEYS,
   buildSidecar,
-  makeProviders,
-  ASPECT_RATIOS,
-  pixelDiff,
-  normalizeCount,
-  tryGenerate,
-  resolveApiKeyCandidates,
-  fallbackOrder,
   normalizeMediaType,
-  embedPngMetadata,
-  removeBackgroundFal,
-  upscaleImageFal,
-  traceToSvg,
-  estimateCost,
-  estimateSharpnessAndVariance,
-  STYLE_PRESETS,
-  applyStylePreset,
-  resolveStylePreset,
-  blendImagesFal,
+  resolveApiKeyCandidates,
   toLosslessJson,
   saveAttachmentSafe,
 } from './providers.js'
 
-import { resolveConversationImage, analyzeImageWithVision, buildDualOutputMarkdown } from './resolve-image.js'
-import { sanitizeNegativePrompt, supportsNegativePrompt } from './negative-sanitizer.js'
-import { executeWithQualityGate } from './quality-gate.js'
-import { calculateGenerationCost, recordSpend, assertBudgetAvailable } from './cost-meter.js'
-import { trackAndAssertLoopGuard, resetLoopGuard } from './loop-guard.js'
-import { maskApiKey, sanitizeErrorAndLogs } from './security.js'
-import { getCachedGeneration, setCachedGeneration } from './generation-cache.js'
-import {
-  extractDesignTokens,
-  generateCssGradient,
-  checkWcagContrast,
-  optimizeSvgContent,
-  generatePwaIconSuite,
-  extractSampleColorsFromBuffer,
-} from './frontend-assets.js'
+import { buildDualOutputMarkdown, resolveConversationImage, analyzeImageWithVision } from './resolve-image.js'
+import { registerAllTools } from './register-tools.js'
 
 
 export { IMAGE_SIZES, OUTPUT_FORMATS, PROVIDER_KEYS, buildSidecar, normalizeMediaType, resolveConversationImage, analyzeImageWithVision }
@@ -675,1328 +641,14 @@ export function apply(ctx, config) {
     },
   }), 'dsh-image-gen: history route')
 
-  // Регистрация инструментов обёрнута в ctx.effect для соблюдения жизненного цикла Cordis (#136)
-  ctx.effect(() => {
-    ctx.tools.register(
-    defineTool({
-      name: 'generate_image',
-      description:
-        'Generate an image with the configured image provider. '
-        + 'Saves the image to the session workspace and shows it in the conversation. '
-        + 'Depending on how the deployment is configured the result carries either the image itself or a link to it; '
-        + 'when you only get a link, answer from the prompt and the link rather than claiming to see the picture. '
-        + 'Use for any text-to-image request. Pass count (1-4) to generate several variations in one call; cost scales with count (default 1).',
-      parameters: {
-        prompt: {
-          type: 'string',
-          required: true,
-          description: 'Detailed description of the image to generate (subject, style, lighting, composition, colors).',
-        },
-        image_size: {
-          type: 'string',
-          description: `One of: ${IMAGE_SIZES.join(', ')}. Default: ${config.defaultSize}.`,
-        },
-        aspect_ratio: {
-          type: 'string',
-          enum: ['1:1', '16:9', '9:16', '4:3', '3:4', '3:2', '2:3'],
-          description: 'Optional aspect ratio; overrides image_size when both are given. Sent as width/height to providers that accept pixels.',
-        },
-        seed: {
-          type: 'integer',
-          description: 'Optional seed for reproducible output.',
-        },
-        output_format: {
-          type: 'string',
-          enum: OUTPUT_FORMATS,
-          description: `Output format. Default: ${config.defaultFormat}.`,
-        },
-        output_name: {
-          type: 'string',
-          description: 'Optional file name stem for the saved image (defaults to a slug of the prompt).',
-        },
-        output_dir: {
-          type: 'string',
-          description: 'Optional custom directory to write images into (relative to session cwd or absolute). Defaults to outputDir from settings.',
-        },
-        count: {
-          type: 'integer',
-          description: 'Number of variations to generate in one call, 1-4 (default 1). Cost scales with count.',
-        },
-        prompts: {
-          type: 'array',
-          items: {
-            oneOf: [
-              { type: 'string' },
-              { type: 'object', additionalProperties: false, properties: { text: { type: 'string' } } },
-            ],
-          },
-          description: 'Optional list of prompts (strings or {text}); one image is generated per prompt. When set, overrides count and the single prompt.',
-        },
-        negative_prompt: {
-          type: 'string',
-          description: 'Optional text describing what NOT to draw; sent to providers that support it (ignored otherwise).',
-        },
-        guidance_scale: {
-          type: 'number',
-          description: 'Optional prompt adherence (e.g. 1-20); sent to providers that support it (ignored otherwise).',
-        },
-        quality: {
-          type: 'string',
-          enum: ['auto', 'low', 'medium', 'high'],
-          description: 'Optional quality for providers that support it (seedream, gemini). Ignored otherwise.',
-        },
-        style: {
-          type: 'string',
-          description: 'Optional style preset for providers that support it (seedream, gemini). Ignored otherwise.',
-        },
-        source_image: {
-          type: 'string',
-          description: 'Optional path to an image file or an attachment id (sha256:...) to edit instead of drawing from scratch. Only providers that support image editing accept it; others refuse with a clear reason.',
-        },
-        mask: {
-          type: 'string',
-          description: 'Optional path or attachment id of a mask image (same size as source) to restrict the edit to a region. Only used when source_image is set and the provider supports masks.',
-        },
-        strength: {
-          type: 'number',
-          description: 'Optional edit strength (0-1) for providers that accept it; higher keeps more of the original.',
-        },
-        quality_gate: {
-          type: 'boolean',
-          description: 'Optional override to enable/disable automated quality gate and defect re-rolling for this call.',
-        },
-        force: {
-          type: 'boolean',
-          description: 'Optional flag to bypass content-addressed cache and force a new API generation.',
-        },
-      },
-      output: {
-        schema: {
-          type: 'object',
-          additionalProperties: true,
-          properties: {
-            path: { type: 'string' },
-            url: { type: 'string' },
-            width: { type: 'integer' },
-            height: { type: 'integer' },
-            seed: { type: 'integer' },
-            prompt: { type: 'string' },
-            format: { type: 'string' },
-            attachment: {
-              type: 'object',
-              additionalProperties: false,
-              properties: {
-                attachmentId: { type: 'string' },
-                mediaType: { type: 'string' },
-                bytes: { type: 'integer' },
-                width: { type: 'integer' },
-                height: { type: 'integer' },
-                name: { type: 'string' },
-              },
-            },
-            images: {
-              type: 'array',
-              items: {
-                type: 'object',
-                additionalProperties: false,
-                properties: {
-                  path: { type: 'string' },
-                  url: { type: 'string' },
-                  width: { type: 'integer' },
-                  height: { type: 'integer' },
-                  seed: { type: 'integer' },
-                  prompt: { type: 'string' },
-                  format: { type: 'string' },
-                },
-              },
-            },
-          },
-        },
-      render(args, value) {
-          const list = value.images || [value]
-          const lines = list.map((img) => `Generated image (${img.width}×${img.height}, ${img.format}, seed ${img.seed}) via ${value.provider || 'image-gen'}/${value.model || 'default'}: ${img.path}`)
-          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 blocks = [{ type: 'text', text: summary }]
-          for (const img of list) if (img.attachment) blocks.push({ type: 'image', attachment: img.attachment })
-          return blocks
-        },
-      },
-      isConcurrencySafe: () => false,
-      timeoutMs: config.timeoutMs + 30000,
-      async execute(args, exec) {
-        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'
-        if (cfg.loopGuardLimit > 0) {
-          trackAndAssertLoopGuard(sessionId, {
-            limit: cfg.loopGuardLimit,
-            prompt: args.prompt,
-          })
-        }
-        if (cfg.enabled === false) {
-          throw new Error('Image generation is disabled in settings (dsh-image-gen.enabled is false); enable it in Settings → Image generation.')
-        }
-        const provider = PROVIDER_KEYS.includes(cfg.provider) ? cfg.provider : 'fal'
-        const deliverAs = cfg.deliverAs
-        const size = args.aspect_ratio ? 'custom' : (args.image_size ?? cfg.defaultSize)
-        if (!args.aspect_ratio && !IMAGE_SIZES.includes(size)) {
-          throw new Error(`Invalid image_size "${size}". One of: ${IMAGE_SIZES.join(', ')}`)
-        }
-        const aspectPixels = args.aspect_ratio ? ASPECT_RATIOS[args.aspect_ratio] : undefined
-        const format = args.output_format ?? cfg.defaultFormat
-        if (!OUTPUT_FORMATS.includes(format)) {
-          throw new Error(`Invalid output_format "${format}". One of: ${OUTPUT_FORMATS.join(', ')}`)
-        }
-        // Служба подписок необязательна: без неё эти два провайдера просто
-        // отказываются, а остальные работают как работали.
-        let subscriptionImages
-        try { subscriptionImages = ctx.get && ctx.get('subscriptionImages') } catch (noService) { subscriptionImages = undefined }
-
-        const source = args.source_image ? await resolveSource(ctx, exec, args.source_image) : undefined
-        const mask = args.mask ? await resolveSource(ctx, exec, args.mask) : undefined
-        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
-
-        // #165: Negative prompt sanitizer for diffusion models
-        let effectiveNegative = styleInfo.negativePrompt
-        if (supportsNegativePrompt(provider, cfg.model || cfg.customModel)) {
-          effectiveNegative = sanitizeNegativePrompt({
-            positivePrompt: effectivePrompt,
-            userNegative: effectiveNegative,
-            autoInjectDefects: true,
-          })
-        }
-        const effectiveGuidance = styleInfo.guidanceScale
-
-        // #167: Assert daily budget availability before calling API
-        const totalCount = Array.isArray(args.prompts) && args.prompts.length ? args.prompts.length : normalizeCount(args.count)
-        const estimatedCost = calculateGenerationCost({
-          provider,
-          model: cfg.model || cfg.customModel,
-          size,
-          count: totalCount,
-        })
-        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 },
-        )
-        // Подписочные провайдеры (codex/grok) отдают {ok:false, reason} вместо исключения:
-        // отказ должен дойти до модели текстом. Без проверки execute шёл дальше с пустыми
-        // байтами, и пользователь получал битую карточку вместо внятного отказа.
-        const guard = (generated) => { if (generated && generated.ok === false) throw new Error(generated.reason) }
-        const one = async (jobSeed, providerKey, promptArg = effectivePrompt) => {
-          const gen = await providers[providerKey](jobSeed, promptArg)
-          guard(gen)
-          const mediaType = gen.mediaType || 'image/png'
-          let bytes = gen.bytes
-          if (mediaType === 'image/png') {
-            bytes = embedPngMetadata(bytes, {
-              prompt: promptArg,
-              seed: gen.seed,
-              provider,
-              model: cfg.model || cfg.customModel,
-              negative_prompt: effectiveNegative,
-              guidance_scale: effectiveGuidance,
-              width: gen.width,
-              height: gen.height,
-            })
-          }
-          const extension = mediaType === 'image/jpeg' ? 'jpg' : mediaType === 'image/webp' ? 'webp' : 'png'
-          const stem = `${slugify(args.output_name || promptArg)}-${Date.now().toString(36)}-${jobSeed}`
-          const name = `${stem}.${extension}`
-
-          const { attachment, localUrl } = await saveAttachmentSafe(ctx, { bytes, mediaType, name })
-
-          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 })
-          const filePath = path.join(outDir, name)
-          await writeFile(filePath, bytes)
-
-          // Sidecar: рядом с картинкой — метаданные генерации. Каталог становится
-          // самодокументируемым (галерея/повтор/диагностика читают их без БД).
-          await writeFile(
-            path.join(outDir, `${stem}.json`),
-            JSON.stringify(buildSidecar({
-              prompt: promptArg,
-              size,
-              format,
-              seed: gen.seed,
-              provider,
-              deliverAs,
-              width: gen.width || attachment.width,
-              height: gen.height || attachment.height,
-              mediaType,
-              attachmentId: attachment.attachmentId,
-              url: deliverAs === 'image' && gen.sourceUrl ? gen.sourceUrl : localUrl,
-              cost: gen.cost,
-            }), null, 2),
-          )
-
-          const cacheHash = computeGenerationHash({
-            provider,
-            model: cfg.model || cfg.customModel,
-            prompt: promptArg,
-            seed: gen.seed,
-            size: args.image_size || cfg.defaultSize,
-            style: args.style || cfg.stylePreset,
-          })
-
-          // #170: Store in content-addressed disk cache
-          if (cfg.diskCache !== false) {
-            setCachedGeneration(cacheHash, {
-              bytes,
-              mediaType,
-              width: gen.width || attachment.width,
-              height: gen.height || attachment.height,
-              seed: gen.seed,
-              meta: { prompt: promptArg, provider, model: cfg.model || cfg.customModel, cost: gen.cost },
-            })
-          }
-          const entry = {
-            path: filePath,
-            prompt: promptArg,
-            provider,
-            model: cfg.model,
-            size,
-            format,
-            seed: gen.seed,
-            cacheHash,
-            thumbnailUrl: localUrl,
-            width: gen.width || attachment.width,
-            height: gen.height || attachment.height,
-            mediaType,
-            bytes: attachment.bytes,
-            createdAt: new Date().toISOString(),
-            attachmentId: attachment.attachmentId,
-          }
-          let current = await readHistory()
-          current = await pruneHistory(current, cfg.pruneDays)
-          current.unshift(entry)
-          if (current.length > (cfg.historyLimit || 50)) current.length = cfg.historyLimit || 50
-          await writeHistory(current)
-
-          // #167: Record spend in cost meter
-          recordSpend(gen.cost || (estimatedCost / totalCount), {
-            ctx,
-            meta: { provider, model: cfg.model || cfg.customModel, prompt: promptArg, seed: gen.seed },
-          })
-
-          return {
-            path: filePath,
-            url: deliverAs === 'image' && gen.sourceUrl ? gen.sourceUrl : localUrl,
-            width: gen.width || attachment.width,
-            height: gen.height || attachment.height,
-            seed: gen.seed,
-            prompt: promptArg,
-            ...(enhanced.enhanced ? { originalPrompt: args.prompt } : {}),
-            cost: gen.cost,
-            format: mediaType.replace('image/', ''),
-            attachment: {
-              attachmentId: attachment.attachmentId,
-              mediaType: attachment.mediaType,
-              bytes: attachment.bytes,
-              width: attachment.width,
-              height: attachment.height,
-              name: attachment.name,
-            },
-          }
-        }
-
-        const seedBase = args.seed ?? Math.floor(Math.random() * 100000)
-        // Fallback-цепочка: пробуем текущий провайдер, при отказе — следующий
-        // по порядку (fal → custom → codex → grok), собирая причины отказов.
-        const order = fallbackOrder(provider)
-        const qgEnabled = args.quality_gate ?? cfg.qualityGate
-        const generators = Object.fromEntries(PROVIDER_KEYS.map((k) => [
-          k,
-          async (s, p) => {
-            const { generated, qualityReport } = await executeWithQualityGate(
-              (seedVal) => one(seedVal, k, p),
-              {
-                initialSeed: s,
-                enabled: qgEnabled,
-                ctx,
-                prompt: p,
-              }
-            )
-            return { ...generated, qualityReport }
-          }
-        ]))
-        const images = []
-        const historyEntries = (cfg.cacheBySeed || cfg.cacheByPrompt) ? await readHistory() : []
-        const checkCache = async (seedVal, promptVal) => {
-          const h = computeGenerationHash({
-            provider,
-            model: cfg.model || cfg.customModel,
-            prompt: promptVal,
-            seed: seedVal,
-            size: args.image_size || cfg.defaultSize,
-            style: args.style || cfg.stylePreset,
-          })
-
-          // #170: Content-addressed disk cache check (<50ms return)
-          if (cfg.diskCache !== false && !args.force) {
-            const diskHit = getCachedGeneration(h, { force: args.force })
-            if (diskHit) {
-              const extension = diskHit.mediaType === 'image/jpeg' ? 'jpg' : diskHit.mediaType === 'image/webp' ? 'webp' : 'png'
-              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 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 })
-              const filePath = path.join(outDir, name)
-              await writeFile(filePath, diskHit.bytes)
-
-              return {
-                path: filePath,
-                url: localUrl,
-                width: diskHit.width || attachment.width,
-                height: diskHit.height || attachment.height,
-                seed: seedVal,
-                prompt: promptVal,
-                cost: 0,
-                fromCache: true,
-                format: diskHit.mediaType.replace('image/', ''),
-                attachment: {
-                  attachmentId: attachment.attachmentId,
-                  mediaType: attachment.mediaType,
-                  bytes: attachment.bytes,
-                  width: attachment.width,
-                  height: attachment.height,
-                  name: attachment.name,
-                },
-              }
-            }
-          }
-
-          if (!cfg.cacheBySeed && !cfg.cacheByPrompt) return undefined
-          const hPrompt = computeGenerationHash({
-            provider,
-            model: cfg.model,
-            prompt: promptVal,
-            seed: seedVal,
-            size: args.image_size || cfg.defaultSize,
-            style: args.style || cfg.stylePreset,
-          })
-          const found = findCachedGeneration(historyEntries, hPrompt)
-          if (found) return await cachedResult(found)
-          if (cfg.cacheBySeed) {
-            const bySeed = await findCached(historyEntries, seedVal, promptVal)
-            if (bySeed) return await cachedResult(bySeed)
-          }
-          if (cfg.cacheByPrompt) {
-            const byPrompt = await findCachedByPrompt(historyEntries, promptVal)
-            if (byPrompt) return await cachedResult(byPrompt)
-          }
-          return undefined
-        }
-
-        const batchPrompts = Array.isArray(args.prompts) && args.prompts.length ? args.prompts : null
-        if (batchPrompts) {
-          for (let i = 0; i < batchPrompts.length; i += 1) {
-            const item = batchPrompts[i]
-            const text = typeof item === 'string' ? item : (item && item.text) || ''
-            const cached = await checkCache(seedBase + i, text)
-            images.push(cached || await tryGenerate(generators, order, seedBase + i, text))
-          }
-        } else {
-          const count = normalizeCount(args.count)
-          for (let i = 0; i < count; i += 1) {
-            const cached = await checkCache(seedBase + i, effectivePrompt)
-            images.push(cached || await tryGenerate(generators, order, seedBase + i))
-          }
-        }
-        const first = images[0]
-        const dualOutputSummary = buildDualOutputMarkdown({
-          action: 'generated',
-          filePath: first.path,
-          width: first.width,
-          height: first.height,
-          mediaType: first.mediaType || ('image/' + (first.format || 'png')),
-          seed: first.seed,
-          provider,
-          model: cfg.model || cfg.customModel || 'default',
-          cost: first.cost,
-          attachmentId: first.attachment?.attachmentId || 'N/A',
-        })
-        return toLosslessJson({ summary: dualOutputSummary, channel: provider, provider, model: cfg.model || cfg.customModel, ...first, images })
-      },
-    }),
-  )
-
-  // Сравнение двух изображений: доля различающихся пикселей.
-  ctx.tools.register(
-    defineTool({
-      name: 'compare_images',
-      description: 'Compare two images (paths or attachment ids) and report the fraction of differing pixels. Use to check how much an edit changed the original.',
-      parameters: {
-        image_a: { type: 'string', required: true, description: 'Path or attachment id of the first image.' },
-        image_b: { type: 'string', required: true, description: 'Path or attachment id of the second image.' },
-      },
-      output: {
-        schema: {
-          type: 'object',
-          additionalProperties: false,
-          properties: {
-            diffRatio: { type: 'number' },
-            error: { type: 'string' },
-          },
-        },
-      },
-      async execute(args, exec) {
-        const a = await resolveSource(ctx, exec, args.image_a)
-        const b = await resolveSource(ctx, exec, args.image_b)
-        return pixelDiff(a && a.bytes, b && b.bytes)
-      },
-    }),
-  )
-
-  // Удаление фона (Rembg / BiRefNet).
-  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))
-        }
-      },
-    }),
-  )
-
-  // Увеличение разрешения и детализация (Upscaling).
-  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))
-        }
-      },
-    }),
-  )
-
-  // Векторизация в SVG (Vectorize image).
-  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))
-        }
-      },
-    }),
-  )
-
-
-  // Смешивание изображений (Blend images).
-  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))
-        }
-      },
-    }),
-  )
-
-
-  // Пакетная генерация под разные пропорции (generate_image_pack).
-  ctx.tools.register(
-    defineTool({
-      name: 'generate_image_pack',
-      description: 'Generate a multi-aspect ratio pack of the same image (e.g. 1:1, 16:9, 9:16) for different platforms.',
-      parameters: {
-        prompt: { type: 'string', required: true, description: 'Text prompt for image generation.' },
-        aspect_ratios: { type: 'array', items: { type: 'string' }, description: 'Target ratios (default: ["1:1", "16:9", "9:16"]).' },
-        output_name: { type: 'string', description: 'Base file name for the pack.' },
-      },
-      output: {
-        schema: {
-          type: 'object',
-          additionalProperties: true,
-          properties: {
-            images: { type: 'array', items: { type: 'object', additionalProperties: true } },
-            count: { type: 'number' },
-            warnings: { type: 'array', items: { type: 'string' } },
-          },
-        },
-      },
-      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 cfg = live()
-        const generateTool = ctx.tools.get('generate_image')
-        const results = []
-        const warnings = []
-        const seedBase = Math.floor(Math.random() * 100000)
-
-        for (let i = 0; i < ratios.length; i += 1) {
-          const ratio = ratios[i]
-          const sizeName = ratio === '16:9' ? 'landscape_16_9' : ratio === '9:16' ? 'portrait_16_9' : ratio === '4:3' ? 'landscape_4_3' : ratio === '3:4' ? 'portrait_4_3' : 'square_hd'
-          const name = `${slugify(args.output_name || 'pack')}-${ratio.replace(':', 'x')}`
-          try {
-            const genResult = await generateTool.execute({
-              prompt: args.prompt,
-              image_size: sizeName,
-              seed: seedBase,
-              output_name: name,
-            }, exec)
-            results.push({ ratio, ...genResult })
-          } catch (err) {
-            warnings.push(`Ratio ${ratio} failed: ${err?.message || String(err)}`)
-          }
-        }
-
-        if (results.length === 0 && warnings.length > 0) {
-          throw new Error(`All aspect ratio generations failed in pack: ${warnings.join('; ')}`)
-        }
-
-        return toLosslessJson({
-          images: results,
-          count: results.length,
-          ...(warnings.length ? { warnings } : {}),
-        })
-      },
-    }),
-  )
-
-  // Редактирование существующего изображения (Inpainting / Edits) (#142, #144, #145, #150).
-  ctx.tools.register(
-    defineTool({
-      name: 'edit_image',
-      description:
-        'Edit an existing image using inpainting, targeted modification, or object replacement. '
-        + 'Describe the desired changes in prompt. '
-        + 'If image is omitted or "latest", automatically resolves the most recent image from the conversation session (#144). '
-        + 'Leverages @goodandready/dsh-vision-bridge for pre-edit composition analysis (#145). '
-        + 'Optionally accepts mask (path or attachment id) and strength (0.1-1.0). Returns safe dual-output (#150).',
-      parameters: {
-        prompt: {
-          type: 'string',
-          required: true,
-          description: 'Detailed description of the modification or edit to perform on the image.',
-        },
-        image: {
-          type: 'string',
-          description: 'Path or attachment id of the source image. Defaults to "latest" to auto-resolve from session history.',
-        },
-        mask: {
-          type: 'string',
-          description: 'Optional path or attachment id of the inpaint mask image.',
-        },
-        strength: {
-          type: 'number',
-          description: 'Denoising / edit strength between 0.1 and 1.0 (default 0.75 for edits, 0.9 for mask inpainting).',
-        },
-        output_name: {
-          type: 'string',
-          description: 'Optional file name stem for the saved edited image.',
-        },
-        output_dir: {
-          type: 'string',
-          description: 'Optional custom directory to write edited image into.',
-        },
-      },
-      output: {
-        schema: {
-          type: 'object',
-          additionalProperties: true,
-          properties: {
-            summary: { type: 'string' },
-            path: { type: 'string' },
-            url: { type: 'string' },
-            width: { type: 'number' },
-            height: { type: 'number' },
-            seed: { type: 'number' },
-            provider: { type: 'string' },
-            cost: { type: 'number' },
-            format: { type: 'string' },
-            attachment: { type: 'object', additionalProperties: true },
-            visionAnalysis: { type: 'string' },
-          },
-        },
-      },
-      async execute(args, exec) {
-        try {
-          trackAndAssertLoopGuard(exec?.agent?.session?.id || 'default', { limit: cfg.loopGuardLimit })
-          const estimatedCostEdit = calculateGenerationCost({
-            provider: cfg.provider || 'fal',
-            model: cfg.model,
-            size: cfg.defaultSize || 'square_hd',
-            count: 1,
-          })
-          assertBudgetAvailable(estimatedCostEdit, cfg.dailyBudgetUsd)
-          const source = await resolveConversationImage(ctx, exec, args.image)
-        const mask = args.mask ? await resolveSource(ctx, exec, args.mask) : undefined
-        const vision = await analyzeImageWithVision(ctx, exec, source)
-
-        let effectivePrompt = args.prompt
-        if (vision.available && vision.summary) {
-          effectivePrompt = `${args.prompt} (Context: modifying ${vision.summary})`
-        }
-
-        const provider = cfg.provider || 'fal'
-        const deps = {
-          fetchImpl: ctx.http ? (url, opt) => ctx.http(url, opt) : fetch,
-          resolveKey: (ref) => resolveApiKey(ctx, ref),
-          cfg,
-        }
-
-        const seed = Math.floor(Math.random() * 100000)
-        const strength = args.strength ?? (mask ? 0.85 : 0.65)
-        const format = cfg.defaultFormat || 'png'
-        const size = cfg.defaultSize || 'square_hd'
-
-        const job = {
-          prompt: effectivePrompt,
-          size,
-          format,
-          seed,
-          source,
-          mask,
-          strength,
-          provider,
-        }
-
-        const providers = makeProviders(deps, job)
-        const fn = providers[provider] || providers.fal || providers.custom
-        const gen = await fn(seed, effectivePrompt)
-
-        const stem = args.output_name ? slugify(args.output_name) : `${source.name}-edit-${seed}`
-        const name = `${stem}.${format}`
-
-        const result = await saveAndAttachResult(ctx, exec, cfg, {
-          bytes: gen.bytes,
-          mediaType: gen.mediaType || 'image/png',
-          name,
-          stem,
-          prompt: args.prompt,
-          size,
-          format,
-          seed: gen.seed ?? seed,
-          provider,
-          model: cfg.model,
-          cost: gen.cost,
-          sourceUrl: gen.sourceUrl,
-          deliverAs: cfg.deliverAs || 'both',
-          args,
-          action: 'edited',
-        })
-
-        if (vision.summary) {
-          result.visionAnalysis = vision.summary
-        }
-        return toLosslessJson(result)
-        } catch (err) {
-          throw new Error(sanitizeErrorAndLogs(err.message || err))
-        }
-      },
-    }),
-  )
-
-  // Генерация вариаций существующего изображения (#143, #144, #145, #150).
-  ctx.tools.register(
-    defineTool({
-      name: 'vary_image',
-      description:
-        'Generate subtle or creative variations of an existing image while preserving overall composition and structure. '
-        + 'Pass variation_strength between 0.1 (subtle difference) and 0.9 (strong reinterpretation, default 0.35). '
-        + 'If image is omitted or "latest", automatically resolves the most recent image from the conversation session (#144). '
-        + 'Returns safe dual-output for text-only LLMs (#150).',
-      parameters: {
-        image: {
-          type: 'string',
-          description: 'Path or attachment id of the source image. Defaults to "latest" to auto-resolve from session history.',
-        },
-        prompt: {
-          type: 'string',
-          description: 'Optional prompt to steer the variation towards a specific mood, lighting, or style.',
-        },
-        variation_strength: {
-          type: 'number',
-          description: 'Strength of variation between 0.1 and 0.9. Default: 0.35.',
-        },
-        count: {
-          type: 'integer',
-          description: 'Number of variations to produce (1-4, default 1).',
-        },
-        output_name: {
-          type: 'string',
-          description: 'Optional file name stem for the saved variations.',
-        },
-        output_dir: {
-          type: 'string',
-          description: 'Optional custom directory to write variations into.',
-        },
-      },
-      output: {
-        schema: {
-          type: 'object',
-          additionalProperties: true,
-          properties: {
-            summary: { type: 'string' },
-            path: { type: 'string' },
-            url: { type: 'string' },
-            width: { type: 'number' },
-            height: { type: 'number' },
-            seed: { type: 'number' },
-            provider: { type: 'string' },
-            cost: { type: 'number' },
-            format: { type: 'string' },
-            attachment: { type: 'object', additionalProperties: true },
-            variations: { type: 'array', items: { type: 'object', additionalProperties: true } },
-          },
-        },
-      },
-      async execute(args, exec) {
-        try {
-          trackAndAssertLoopGuard(exec?.agent?.session?.id || 'default', { limit: cfg.loopGuardLimit })
-          const count = normalizeCount(args.count || 1)
-          const estimatedCostVary = calculateGenerationCost({
-            provider: cfg.provider || 'fal',
-            model: cfg.model,
-            size: cfg.defaultSize || 'square_hd',
-            count,
-          })
-          assertBudgetAvailable(estimatedCostVary, cfg.dailyBudgetUsd)
-          const source = await resolveConversationImage(ctx, exec, args.image)
-        const vision = await analyzeImageWithVision(ctx, exec, source)
-
-        const provider = cfg.provider || 'fal'
-        const deps = {
-          fetchImpl: ctx.http ? (url, opt) => ctx.http(url, opt) : fetch,
-          resolveKey: (ref) => resolveApiKey(ctx, ref),
-          cfg,
-        }
-        const variationStrength = Math.max(0.05, Math.min(0.95, args.variation_strength ?? 0.35))
-        const baseSeed = Math.floor(Math.random() * 100000)
-        const format = cfg.defaultFormat || 'png'
-        const size = cfg.defaultSize || 'square_hd'
-
-        const promptText = args.prompt || (vision.available ? `variation of ${vision.summary}` : 'high fidelity variation preserving composition')
-
-        const results = []
-        for (let i = 0; i < count; i++) {
-          const currentSeed = baseSeed + i
-          const job = {
-            prompt: promptText,
-            size,
-            format,
-            seed: currentSeed,
-            source,
-            strength: variationStrength,
-            provider,
-          }
-
-          const providers = makeProviders(deps, job)
-          const fn = providers[provider] || providers.fal || providers.custom
-          const gen = await fn(currentSeed, promptText)
-
-          const stem = args.output_name
-            ? `${slugify(args.output_name)}-var-${i + 1}`
-            : `${source.name}-var-${currentSeed}`
-          const name = `${stem}.${format}`
-
-          const item = await saveAndAttachResult(ctx, exec, cfg, {
-            bytes: gen.bytes,
-            mediaType: gen.mediaType || 'image/png',
-            name,
-            stem,
-            prompt: promptText,
-            size,
-            format,
-            seed: gen.seed ?? currentSeed,
-            provider,
-            model: cfg.model,
-            cost: gen.cost,
-            sourceUrl: gen.sourceUrl,
-            deliverAs: cfg.deliverAs || 'both',
-            args,
-            action: `variation (${variationStrength})`,
-          })
-          results.push(item)
-        }
-
-        const first = results[0]
-        return toLosslessJson({
-          ...first,
-          variations: results.map((r) => ({ path: r.path, attachmentId: r.attachment?.attachmentId, seed: r.seed })),
-        })
-        } catch (err) {
-          throw new Error(sanitizeErrorAndLogs(err.message || err))
-        }
-      },
-    }),
-  )
-
-  // Проверка качества изображения (Inspect Image Quality).
-  ctx.tools.register(
-    defineTool({
-      name: 'inspect_image_quality',
-      description: 'Inspect a generated image for quality, artifacts, and presence of expected elements.',
-      parameters: {
-        image: { type: 'string', required: true, description: 'Path or attachment id of the image.' },
-        expected_elements: { type: 'string', description: 'What elements should be present and verified.' },
-      },
-      output: {
-        schema: {
-          type: 'object',
-          additionalProperties: false,
-          properties: {
-            qualityScore: { type: 'number' },
-            passed: { type: 'boolean' },
-            notes: { type: 'string' },
-          },
-        },
-      },
-      async execute(args, exec) {
-        const source = await resolveSource(ctx, exec, args.image)
-        if (!source || !source.bytes) throw new Error('Image not found: ' + args.image)
-        const analysis = estimateSharpnessAndVariance(source.bytes)
-        const elementNote = args.expected_elements ? ` Verified presence of: ${args.expected_elements}.` : ''
-        return {
-          qualityScore: analysis.score,
-          passed: analysis.passed,
-          notes: analysis.isBlank ? `Defect detected: ${analysis.reason}` : `Image clarity and variance verified (score ${analysis.score}).${elementNote}`,
-        }
-      },
-    }),
-    )
-
-  // #172: Генератор дизайн-токенов и CSS/Tailwind палитры по концепту
-  ctx.tools.register(
-    defineTool({
-      name: 'extract_design_tokens',
-      description: 'Extract design tokens (CSS variables, Tailwind colors config, W3C tokens JSON) from an image or palette.',
-      parameters: {
-        image: { type: 'string', description: 'Path or attachment ID of the image to extract colors from.' },
-        colors: { type: 'array', items: { type: 'string' }, description: 'Optional list of hex colors if already known.' },
-        prefix: { type: 'string', description: 'Token naming prefix (default: color).' },
-      },
-      output: {
-        schema: {
-          type: 'object',
-          additionalProperties: true,
-          properties: {
-            tokens: { type: 'object', additionalProperties: true },
-            cssVariables: { type: 'string' },
-            tailwindSnippet: { type: 'string' },
-            w3cTokens: { type: 'object', additionalProperties: true },
-          },
-        },
-      },
-      async execute(args, exec) {
-        let colors = args.colors
-        if (!colors || colors.length === 0) {
-          if (args.image) {
-            const source = await resolveSource(ctx, exec, args.image)
-            if (!source || !source.bytes) {
-              throw new Error('Image not found or unreadable: ' + args.image)
-            }
-            colors = extractSampleColorsFromBuffer(source.bytes)
-          }
-        }
-        return toLosslessJson(extractDesignTokens(colors, { prefix: args.prefix }))
-      },
-    }),
-  )
-
-  // #174: Конвертер фоновых изображений в легковесные CSS Mesh Gradients
-  ctx.tools.register(
-    defineTool({
-      name: 'image_to_css_gradient',
-      description: 'Convert an image background or color palette into a lightweight pure CSS gradient (< 1KB).',
-      parameters: {
-        image: { type: 'string', description: 'Path or attachment ID of the image.' },
-        colors: { type: 'array', items: { type: 'string' }, description: 'Optional explicit hex colors for the gradient.' },
-        type: { type: 'string', enum: ['mesh', 'linear', 'radial'], description: 'Gradient type: mesh, linear, or radial (default: mesh).' },
-      },
-      output: {
-        schema: {
-          type: 'object',
-          additionalProperties: true,
-          properties: {
-            type: { type: 'string' },
-            fallbackColor: { type: 'string' },
-            gradientCss: { type: 'string' },
-            completeStyle: { type: 'string' },
-            byteSize: { type: 'number' },
-          },
-        },
-      },
-      async execute(args, exec) {
-        let colors = args.colors
-        if (!colors || colors.length === 0) {
-          if (args.image) {
-            const source = await resolveSource(ctx, exec, args.image)
-            if (!source || !source.bytes) {
-              throw new Error('Image not found or unreadable: ' + args.image)
-            }
-            colors = extractSampleColorsFromBuffer(source.bytes)
-          }
-        }
-        return toLosslessJson(generateCssGradient(colors, args.type || 'mesh'))
-      },
-    }),
-  )
-
-  // #175: Проверка контрастности фона под текст по WCAG 2.1
-  ctx.tools.register(
-    defineTool({
-      name: 'check_image_contrast',
-      description: 'Check image background contrast ratio against text color according to WCAG 2.1 AA/AAA standards and suggest scrim.',
-      parameters: {
-        image: { type: 'string', description: 'Path or attachment ID of the image.' },
-        colors: { type: 'array', items: { type: 'string' }, description: 'Optional list of background hex colors.' },
-        text_color: { type: 'string', description: 'Text hex color to test against (default: #ffffff).' },
-      },
-      output: {
-        schema: {
-          type: 'object',
-          additionalProperties: true,
-          properties: {
-            textHex: { type: 'string' },
-            minContrastRatio: { type: 'number' },
-            passedAA: { type: 'boolean' },
-            passedAALarge: { type: 'boolean' },
-            passedAAA: { type: 'boolean' },
-            recommendation: { type: 'string' },
-            suggestedScrimCss: { type: 'string' },
-            details: { type: 'array', items: { type: 'object', additionalProperties: true } },
-          },
-        },
-      },
-      async execute(args, exec) {
-        let colors = args.colors
-        if (!colors || colors.length === 0) {
-          if (args.image) {
-            const source = await resolveSource(ctx, exec, args.image)
-            if (!source || !source.bytes) {
-              throw new Error('Image not found or unreadable: ' + args.image)
-            }
-            colors = extractSampleColorsFromBuffer(source.bytes)
-          }
-        }
-        return toLosslessJson(checkWcagContrast(colors, args.text_color || '#ffffff'))
-      },
-    }),
-  )
-
-  // #176: Интеллектуальная постобработка, очистка и оптимизация SVG
-  ctx.tools.register(
-    defineTool({
-      name: 'optimize_vector_svg',
-      description: 'Clean, sanitize, and minify SVG content, normalize viewBox, and export React TSX component.',
-      parameters: {
-        svg_content: { type: 'string', description: 'Raw SVG markup string to optimize.' },
-        image: { type: 'string', description: 'Path or attachment ID of an SVG file if not passing raw string.' },
-        component_name: { type: 'string', description: 'React component name for TSX export (default: VectorIcon).' },
-      },
-      output: {
-        schema: {
-          type: 'object',
-          additionalProperties: true,
-          properties: {
-            svg: { type: 'string' },
-            viewBox: { type: 'string' },
-            originalSize: { type: 'number' },
-            optimizedSize: { type: 'number' },
-            savedBytes: { type: 'number' },
-            reductionPercent: { type: 'number' },
-            reactTsx: { type: 'string' },
-          },
-        },
-      },
-      async execute(args, exec) {
-        let svgStr = args.svg_content
-        if (!svgStr && args.image) {
-          const source = await resolveSource(ctx, exec, args.image)
-          if (source && source.bytes) {
-            svgStr = source.bytes.toString('utf8')
-          }
-        }
-        if (!svgStr) {
-          throw new Error('Either svg_content or image must be provided')
-        }
-        return optimizeSvgContent(svgStr, { componentName: args.component_name })
-      },
-    }),
-  )
-
-  // #190: Генератор полного комплекта фавиконок, иконок приложений и PWA-манифеста
-  ctx.tools.register(
-    defineTool({
-      name: 'generate_pwa_icon_suite',
-      description: 'Generate standard PWA icons specification, HTML meta tags, and web app manifest.json.',
-      parameters: {
-        image: { type: 'string', description: 'Source icon image path or attachment ID.' },
-        name: { type: 'string', description: 'App name (e.g. My Application).' },
-        short_name: { type: 'string', description: 'App short name (e.g. MyApp).' },
-        theme_color: { type: 'string', description: 'Theme color hex (e.g. #0f172a).' },
-        background_color: { type: 'string', description: 'Background color hex (e.g. #ffffff).' },
-        icons_dir: { type: 'string', description: 'Directory for icons relative to webroot (default: icons).' },
-      },
-      output: {
-        schema: {
-          type: 'object',
-          additionalProperties: true,
-          properties: {
-            name: { type: 'string' },
-            shortName: { type: 'string' },
-            themeColor: { type: 'string' },
-            backgroundColor: { type: 'string' },
-            icons: { type: 'array', items: { type: 'object', additionalProperties: true } },
-            manifestJson: { type: 'string' },
-            htmlHeadSnippet: { type: 'string' },
-          },
-        },
-      },
-      async execute(args, exec) {
-        const res = await generatePwaIconSuite({
-          name: args.name || 'App',
-          shortName: args.short_name || args.name || 'App',
-          themeColor: args.theme_color || '#0f172a',
-          backgroundColor: args.background_color || '#ffffff',
-          iconsDir: args.icons_dir || 'icons',
-          sourcePath: args.image || null,
-        })
-        return toLosslessJson(res)
-      },
-    }),
-  )
-
+  // Tool registrations live in register-tools.js; each tool is a labeled ctx.effect (#216).
+  registerAllTools(ctx, {
+    config,
+    live,
+    saveAndAttachResult,
+    resolveSource,
+    slugify,
+    resolveApiKey,
   })
 
 }