@goodandready/dsh-image-gen 0.11.22 → 0.11.23

package/lib/config-schema.js

@@ -186,9 +186,9 @@ export const Config = z.object({
     .default('GEMINI_API_KEY')
     .volatile(),
   localKind: z
-    .union([z.const('automatic1111'), z.const('a1111'), z.const('comfyui')])
-    .description('Local generation backend kind: "automatic1111" / "a1111" (WebUI) or "comfyui".')
-    .default('automatic1111')
+    .union([z.const('a1111'), z.const('comfyui'), z.const('automatic1111')])
+    .description('Local generation backend kind: "a1111" (WebUI) or "comfyui".')
+    .default('a1111')
     .volatile(),
   localBaseURL: z
     .string()
@@ -351,6 +351,9 @@ export function sanitizeRaw(raw) {
     }
     cleaned[k] = v
   }
+  if (cleaned.localKind === 'automatic1111') {
+    cleaned.localKind = 'a1111'
+  }
   return cleaned
 }
 

package/lib/providers/backends/custom.js

@@ -23,16 +23,27 @@ export function createCustomGenerator(deps, job) {
 
     // Empty key reference indicates unauthenticated gateway.
     const key = cfg.customKeyEnv ? await resolveKey(cfg.customKeyEnv) : ''
-    const headers = { 'Content-Type': 'application/json' }
+    const isEdit = Boolean(source && source.bytes)
+    const headers = {}
+    if (!isEdit) {
+      headers['Content-Type'] = 'application/json'
+    }
     if (key) headers.Authorization = `Bearer ${key}`
 
     // Omit response_format; modern models return either base64 or URL.
-    const endpoint = buildEndpointUrl(base, source ? 'images/edits' : 'images/generations')
+    const endpoint = buildEndpointUrl(base, isEdit ? 'images/edits' : 'images/generations')
     const res = await fetchImpl(endpoint, {
       method: 'POST',
       headers,
-      body: source
-        ? buildEditForm({ source, mask, prompt: promptArg, size: cfg.customSize || (aspectPixels ? aspectPixels.join('x') : SIZE_PIXELS[size]) || size, strength })
+      body: isEdit
+        ? buildEditForm({
+            model: cfg.customModel,
+            source,
+            mask,
+            prompt: promptArg,
+            size: cfg.customSize || (aspectPixels ? aspectPixels.join('x') : SIZE_PIXELS[size]) || size,
+            strength,
+          })
         : JSON.stringify({
             model: cfg.customModel,
             prompt: promptArg,

package/lib/providers/backends/local.js

@@ -24,7 +24,14 @@ export function createLocalGenerator(deps, job) {
     const base = String(cfg.localBaseURL || '').replace(/\/+$/, '')
     if (!base) throw new Error('Local image provider: server address is not configured (Settings → Image generation)')
     const [width, height] = pxSize(aspectPixels, size)
-    const kind = (cfg.localKind === 'a1111' || cfg.localKind === 'automatic1111') ? 'a1111' : 'comfyui'
+    const rawKind = cfg.localKind || 'a1111'
+    const kind = (rawKind === 'a1111' || rawKind === 'automatic1111')
+      ? 'a1111'
+      : (rawKind === 'comfyui' ? 'comfyui' : null)
+
+    if (!kind) {
+      throw new Error(`Unknown local generation backend kind "${rawKind}". Expected "a1111" or "comfyui".`)
+    }
 
     if (kind === 'a1111') {
       const isImg2Img = Boolean(source && source.bytes)

package/lib/providers/shared-helpers.js

@@ -86,8 +86,9 @@ export async function pollStatus(fetchImpl, statusUrl, key, signal, pollInterval
   }
 }
 
-export function buildEditForm({ source, mask, prompt, size, strength }) {
+export function buildEditForm({ source, mask, prompt, size, strength, model }) {
   const form = new FormData()
+  if (model) form.append('model', model)
   form.append('image', new Blob([source.bytes], { type: source.mediaType || 'image/png' }), 'source.png')
   if (mask) form.append('mask', new Blob([mask.bytes], { type: mask.mediaType || 'image/png' }), 'mask.png')
   form.append('prompt', prompt)

package/lib/tools/character-sheet.js

@@ -1,5 +1,5 @@
-import { sanitizeErrorAndLogs } from '../security.js'
-// character-sheet.js — generate_character_sheet tool (#181).
+import { buildDualOutputMarkdown } from '../resolve-image.js'
+// character-sheet.js — generate_character_sheet tool (#181, #358).
 // Generates multi-angle character model sheets and turnarounds with visual consistency.
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
@@ -7,10 +7,12 @@ import path from 'node:path'
 import { mkdir, writeFile } from 'node:fs/promises'
 import {
   ASPECT_RATIOS,
+  PROVIDER_KEYS,
   buildSidecar,
   makeProviders,
   toLosslessJson,
   saveAttachmentSafe,
+  
 } from '../providers.js'
 import { resolveFallbackChain, executeWithFallback } from '../fallback-router.js'
 import { assertBudgetAvailable, calculateGenerationCost, recordSpend } from '../cost-meter.js'
@@ -24,7 +26,7 @@ import {
 export function registerCharacterSheetTools(ctx, deps) {
   const {
     live,
-    slugify,
+    slugify = (s) => String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '-'),
     resolveApiKey,
   } = deps
 
@@ -78,6 +80,8 @@ export function registerCharacterSheetTools(ctx, deps) {
               },
               seed: { type: 'integer' },
               provider: { type: 'string' },
+              path: { type: 'string' },
+              url: { type: 'string' },
               attachment: {
                 type: 'object',
                 additionalProperties: true,
@@ -89,13 +93,24 @@ export function registerCharacterSheetTools(ctx, deps) {
                   byteSize: { type: 'integer' },
                 },
               },
+              _fallback: {
+                type: 'object',
+                additionalProperties: true,
+              },
             },
           },
           render: (_args, value) => renderToolOutput(value),
         },
         async execute(args, execCtx) {
-          const cfg = live.value
-          const activeProvider = args.provider || cfg.activeProvider || 'fal'
+          const cfg = typeof live === 'function' ? live() : (live?.value || {})
+          if (cfg.enabled === false) {
+            throw new Error('Image generation is disabled in settings.')
+          }
+
+          const provider = PROVIDER_KEYS.includes(args.provider || cfg.provider)
+            ? (args.provider || cfg.provider)
+            : (PROVIDER_KEYS.includes(cfg.provider) ? cfg.provider : 'fal')
+
           const seed = typeof args.seed === 'number' ? args.seed : Math.floor(Math.random() * 2147483647)
 
           const sheetPlan = buildCharacterSheetPrompt({
@@ -105,73 +120,98 @@ export function registerCharacterSheetTools(ctx, deps) {
             negativePrompt: args.negativePrompt,
           })
 
-          const providers = makeProviders({
-            fetchImpl: fetch,
-            resolveKey: (id) => resolveApiKey(cfg, id),
-            cfg,
-          })
+          const aspectPixels = ASPECT_RATIOS[sheetPlan.aspectRatio] || ASPECT_RATIOS['16:9']
 
-          const fallbackChain = resolveFallbackChain(activeProvider, cfg)
+          let subscriptionImages
+          try { subscriptionImages = ctx.get && ctx.get('subscriptionImages') } catch (_err) { subscriptionImages = undefined }
+
+          const providers = makeProviders(
+            { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg, subscriptionImages },
+            {
+              prompt: sheetPlan.prompt,
+              negativePrompt: sheetPlan.negativePrompt,
+              size: 'custom',
+              format: 'png',
+              seed,
+              signal: execCtx?.signal,
+              aspectPixels,
+              aspectRatio: sheetPlan.aspectRatio,
+              quality: 'high',
+            },
+          )
 
-          const aspectPixels = ASPECT_RATIOS[sheetPlan.aspectRatio] || ASPECT_RATIOS['16:9']
+          const fallbackChain = resolveFallbackChain(provider, cfg.fallbackProviders, PROVIDER_KEYS)
 
           const estimatedCost = calculateGenerationCost({
-            provider: activeProvider,
+            provider,
             model: cfg.model || cfg.customModel || 'default',
             size: cfg.defaultSize || '1024x1024',
             count: 1,
           })
           assertBudgetAvailable(estimatedCost, cfg.dailyBudgetUsd)
 
-          const jobPayload = {
-            prompt: sheetPlan.prompt,
-            negativePrompt: sheetPlan.negativePrompt,
-            aspectRatio: sheetPlan.aspectRatio,
-            aspectPixels,
-            format: 'png',
-            seed,
-            quality: 'high',
-          }
-
-          const { result: genResult, provider: usedProvider } = await executeWithFallback(
-            fallbackChain,
+          const gen = await executeWithFallback(
             providers,
-            jobPayload,
-            { signal: execCtx?.signal }
+            fallbackChain,
+            seed,
+            sheetPlan.prompt,
+            { logger: ctx.logger },
           )
 
+          const usedProvider = gen._fallback?.providerUsed || provider
+          const finalBytes = gen.bytes
           const timestamp = Date.now()
           const safeSlug = slugify(args.prompt.slice(0, 30)) || 'character-sheet'
           const filename = `character-sheet-${sheetPlan.layout}-${safeSlug}-${timestamp}.png`
 
           let attachment = null
-          if (genResult.bytes) {
-            const outDir = path.resolve(process.cwd(), cfg.outputDir || 'output')
+          let localUrl = ''
+          let diskPath = ''
+          if (finalBytes) {
+            const saveRes = await saveAttachmentSafe(ctx, {
+              bytes: finalBytes,
+              mediaType: 'image/png',
+              name: filename,
+            })
+            attachment = saveRes?.attachment || null
+            localUrl = saveRes?.localUrl || ''
+
+            const sessionCwd = execCtx?.agent?.session?.header?.cwd
+            const targetDir = cfg.outputDir || 'generated/images'
+            const outDir = path.resolve(sessionCwd || process.cwd(), targetDir)
             await mkdir(outDir, { recursive: true })
-            const diskPath = path.join(outDir, filename)
-            await writeFile(diskPath, Buffer.from(genResult.bytes))
-
-            attachment = await saveAttachmentSafe(
-              ctx,
-              Buffer.from(genResult.bytes),
-              'image/png',
-              filename,
-              diskPath
-            )
-          } else if (genResult.url) {
+            diskPath = path.join(outDir, filename)
+            await writeFile(diskPath, Buffer.from(finalBytes))
+          } else if (gen.url) {
             attachment = {
-              url: genResult.url,
+              url: gen.url,
               mediaType: 'image/png',
               filename,
             }
+            localUrl = gen.url
           }
 
-          recordSpend(Number(genResult.cost) || estimatedCost, {
+          const effectiveCost = Number(gen.cost) || estimatedCost
+          recordSpend(effectiveCost, {
             ctx,
             meta: { provider: usedProvider, model: cfg.model || cfg.customModel, prompt: sheetPlan.prompt, seed },
           })
 
+          const dualOutput = buildDualOutputMarkdown({
+            action: 'generated',
+            filePath: diskPath || filename,
+            width: aspectPixels[0],
+            height: aspectPixels[1],
+            mediaType: 'image/png',
+            seed,
+            provider: usedProvider,
+            model: cfg.model || cfg.customModel || 'character-sheet',
+            cost: gen.cost,
+            attachmentId: attachment?.attachmentId,
+          })
+
           const response = {
+            summary: dualOutput,
             prompt: sheetPlan.prompt,
             characterDescription: args.prompt,
             layout: sheetPlan.layout,
@@ -181,16 +221,13 @@ export function registerCharacterSheetTools(ctx, deps) {
             seed,
             provider: usedProvider,
             attachment,
+            path: diskPath,
+            url: localUrl,
+            attachmentId: attachment?.attachmentId,
+            _fallback: gen._fallback,
           }
 
-          if (attachment?.attachmentId) {
-            response.attachmentId = attachment.attachmentId
-          }
-          if (attachment?.url) {
-            response.url = attachment.url
-          }
-
-          return response
+          return toLosslessJson(response)
         },
       })
     )

package/lib/tools/diagram.js

@@ -1,5 +1,4 @@
-import { sanitizeErrorAndLogs } from '../security.js'
-// diagram.js — beautify_diagram tool (#185).
+// diagram.js — beautify_diagram tool (#185, #359).
 // Transforms raw Mermaid / Graphviz diagrams into high-end 3D isometric architectural illustrations.
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
@@ -7,9 +6,12 @@ import path from 'node:path'
 import { mkdir, writeFile } from 'node:fs/promises'
 import {
   ASPECT_RATIOS,
+  PROVIDER_KEYS,
   makeProviders,
+  toLosslessJson,
   saveAttachmentSafe,
 } from '../providers.js'
+import { buildDualOutputMarkdown } from '../resolve-image.js'
 import { resolveFallbackChain, executeWithFallback } from '../fallback-router.js'
 import { assertBudgetAvailable, calculateGenerationCost, recordSpend } from '../cost-meter.js'
 import { renderToolOutput } from '../attachment-helper.js'
@@ -21,7 +23,7 @@ import {
 export function registerDiagramTools(ctx, deps) {
   const {
     live,
-    slugify,
+    slugify = (s) => String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '-'),
     resolveApiKey,
   } = deps
 
@@ -75,6 +77,8 @@ export function registerDiagramTools(ctx, deps) {
               prompt: { type: 'string' },
               seed: { type: 'integer' },
               provider: { type: 'string' },
+              path: { type: 'string' },
+              url: { type: 'string' },
               attachment: {
                 type: 'object',
                 additionalProperties: true,
@@ -85,13 +89,24 @@ export function registerDiagramTools(ctx, deps) {
                   filename: { type: 'string' },
                 },
               },
+              _fallback: {
+                type: 'object',
+                additionalProperties: true,
+              },
             },
           },
           render: (_args, value) => renderToolOutput(value),
         },
         async execute(args, execCtx) {
-          const cfg = live?.value || (typeof live === 'function' ? live() : {})
-          const activeProvider = args.provider || cfg.activeProvider || 'fal'
+          const cfg = typeof live === 'function' ? live() : (live?.value || {})
+          if (cfg.enabled === false) {
+            throw new Error('Image generation is disabled in settings.')
+          }
+
+          const provider = PROVIDER_KEYS.includes(args.provider || cfg.provider)
+            ? (args.provider || cfg.provider)
+            : (PROVIDER_KEYS.includes(cfg.provider) ? cfg.provider : 'fal')
+
           const seed = typeof args.seed === 'number' ? args.seed : Math.floor(Math.random() * 2147483647)
 
           const plan = buildDiagramIllustrationPrompt({
@@ -101,70 +116,98 @@ export function registerDiagramTools(ctx, deps) {
             aspectRatio: args.aspect_ratio || '16:9',
           })
 
-          const providers = makeProviders({
-            fetchImpl: fetch,
-            resolveKey: (id) => resolveApiKey(cfg, id),
-            cfg,
-          })
-          const fallbackChain = resolveFallbackChain(activeProvider, cfg)
           const aspectPixels = ASPECT_RATIOS[plan.aspectRatio] || ASPECT_RATIOS['16:9']
 
+          let subscriptionImages
+          try { subscriptionImages = ctx.get && ctx.get('subscriptionImages') } catch (_err) { subscriptionImages = undefined }
+
+          const providers = makeProviders(
+            { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg, subscriptionImages },
+            {
+              prompt: plan.prompt,
+              negativePrompt: plan.negativePrompt,
+              size: 'custom',
+              format: 'png',
+              seed,
+              signal: execCtx?.signal,
+              aspectPixels,
+              aspectRatio: plan.aspectRatio,
+              quality: 'high',
+            },
+          )
+
+          const fallbackChain = resolveFallbackChain(provider, cfg.fallbackProviders, PROVIDER_KEYS)
+
           const estimatedCost = calculateGenerationCost({
-            provider: activeProvider,
+            provider,
             model: cfg.model || cfg.customModel || 'default',
             size: cfg.defaultSize || '1024x1024',
             count: 1,
           })
           assertBudgetAvailable(estimatedCost, cfg.dailyBudgetUsd)
 
-          const jobPayload = {
-            prompt: plan.prompt,
-            negativePrompt: plan.negativePrompt,
-            aspectRatio: plan.aspectRatio,
-            aspectPixels,
-            format: 'png',
-            seed,
-            quality: 'high',
-          }
-
-          const { result: genResult, provider: usedProvider } = await executeWithFallback(
-            fallbackChain,
+          const gen = await executeWithFallback(
             providers,
-            jobPayload,
-            { signal: execCtx?.signal }
+            fallbackChain,
+            seed,
+            plan.prompt,
+            { logger: ctx.logger },
           )
 
-          const outDir = path.resolve(process.cwd(), cfg.outputDir || 'output')
-          await mkdir(outDir, { recursive: true })
+          const usedProvider = gen._fallback?.providerUsed || provider
+          const finalBytes = gen.bytes
           const timestamp = Date.now()
           const safeSlug = slugify(args.title || 'architecture-diagram') || 'diagram'
           const filename = `diagram-3d-${safeSlug}-${timestamp}.png`
 
           let attachment = null
-          if (genResult.bytes) {
-            const diskPath = path.join(outDir, filename)
-            await writeFile(diskPath, Buffer.from(genResult.bytes))
-            attachment = await saveAttachmentSafe(
-              ctx,
-              Buffer.from(genResult.bytes),
-              'image/png',
-              filename,
-              diskPath
-            )
-          } else if (genResult.url) {
+          let localUrl = ''
+          let diskPath = ''
+          if (finalBytes) {
+            const saveRes = await saveAttachmentSafe(ctx, {
+              bytes: finalBytes,
+              mediaType: 'image/png',
+              name: filename,
+            })
+            attachment = saveRes?.attachment || null
+            localUrl = saveRes?.localUrl || ''
+
+            const sessionCwd = execCtx?.agent?.session?.header?.cwd
+            const targetDir = cfg.outputDir || 'generated/images'
+            const outDir = path.resolve(sessionCwd || process.cwd(), targetDir)
+            await mkdir(outDir, { recursive: true })
+            diskPath = path.join(outDir, filename)
+            await writeFile(diskPath, Buffer.from(finalBytes))
+          } else if (gen.url) {
             attachment = {
-              url: genResult.url,
+              url: gen.url,
               mediaType: 'image/png',
               filename,
             }
+            localUrl = gen.url
           }
 
-          recordSpend(Number(genResult.cost) || estimatedCost, {
+          const effectiveCost = Number(gen.cost) || estimatedCost
+          recordSpend(effectiveCost, {
             ctx,
             meta: { provider: usedProvider, model: cfg.model || cfg.customModel, prompt: plan.prompt, seed },
           })
 
-          return {
+          const dualOutput = buildDualOutputMarkdown({
+            action: 'generated',
+            filePath: diskPath || filename,
+            width: aspectPixels[0],
+            height: aspectPixels[1],
+            mediaType: 'image/png',
+            seed,
+            provider: usedProvider,
+            model: cfg.model || cfg.customModel || 'beautify-diagram',
+            cost: gen.cost,
+            attachmentId: attachment?.attachmentId,
+          })
+
+          const response = {
+            summary: dualOutput,
             title: args.title || 'System Architecture',
             style: plan.style,
             aspectRatio: plan.aspectRatio,
@@ -173,9 +216,13 @@ export function registerDiagramTools(ctx, deps) {
             seed,
             provider: usedProvider,
             attachment,
-            url: attachment?.url,
+            path: diskPath,
+            url: localUrl,
             attachmentId: attachment?.attachmentId,
+            _fallback: gen._fallback,
           }
+
+          return toLosslessJson(response)
         },
       })
     )

package/lib/tools/theme-pair.js

@@ -1,12 +1,12 @@
-import { sanitizeErrorAndLogs } from '../security.js'
-// theme-pair.js — generate_theme_pair tool (#189).
-// Synchronized dual generation of light and dark theme visuals with adaptive CSS snippets.
+// theme-pair.js — generate_theme_pair tool (#189, #361).
+// Generates complementary Light & Dark mode asset variants with synchronized compositions.
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import path from 'node:path'
 import { mkdir, writeFile } from 'node:fs/promises'
 import {
   ASPECT_RATIOS,
+  PROVIDER_KEYS,
   buildSidecar,
   makeProviders,
   toLosslessJson,
@@ -24,7 +24,7 @@ import {
 export function registerThemePairTools(ctx, deps) {
   const {
     live,
-    slugify,
+    slugify = (s) => String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '-'),
     resolveApiKey,
   } = deps
 
@@ -33,23 +33,23 @@ export function registerThemePairTools(ctx, deps) {
       defineTool({
         name: 'generate_theme_pair',
         description:
-          'Generate synchronized dual illustrations or UI graphics designed specifically for light and dark application themes. '
-          + 'Produces both light (#FFFFFF clean backdrop) and dark (#0F172A obsidian backdrop with luminous accents) variants with matched composition, plus ready-to-use HTML/CSS responsive markup.',
+          'Generate matching Light and Dark mode UI illustration variants with synchronized seeds, '
+          + 'consistent composition, and inverted contrast palettes. Outputs a responsive <picture> tag with prefers-color-scheme.',
         parameters: {
           prompt: {
             type: 'string',
+            description: 'Core visual concept description (e.g. "cloud database topology architecture").',
             required: true,
-            description: 'Core subject or illustration motif, e.g. "cloud server network topology" or "productivity dashboard banner".',
-          },
-          aspect_ratio: {
-            type: 'string',
-            enum: Object.keys(ASPECT_RATIOS),
-            description: 'Aspect ratio for both variants: "1:1", "16:9", "4:3", etc. (default: "16:9").',
           },
           style: {
             type: 'string',
             enum: THEME_STYLES,
-            description: 'Visual style aesthetic (default: "minimalist").',
+            description: 'Aesthetic visual direction: minimalist, neon_cyberpunk, editorial, gradient_glass, 3d_clay.',
+          },
+          aspect_ratio: {
+            type: 'string',
+            enum: ['16:9', '1:1', '4:3', '21:9'],
+            description: 'Asset aspect ratio (default: 16:9).',
           },
           dark_contrast_boost: {
             type: 'number',
@@ -63,6 +63,10 @@ export function registerThemePairTools(ctx, deps) {
             type: 'integer',
             description: 'Base random seed to synchronize composition between variants.',
           },
+          provider: {
+            type: 'string',
+            description: 'Optional provider override. Defaults to active provider.',
+          },
         },
         output: {
           schema: {
@@ -100,7 +104,7 @@ export function registerThemePairTools(ctx, deps) {
         },
         isConcurrencySafe: () => false,
         async execute(args, exec) {
-          const cfg = live()
+          const cfg = typeof live === 'function' ? live() : (live?.value || {})
           if (cfg.enabled === false) {
             throw new Error('Image generation is disabled in settings.')
           }
@@ -121,7 +125,10 @@ export function registerThemePairTools(ctx, deps) {
             darkContrastBoost,
           })
 
-          const primaryProvider = cfg.provider || 'fal'
+          const primaryProvider = PROVIDER_KEYS.includes(args.provider || cfg.provider)
+            ? (args.provider || cfg.provider)
+            : (PROVIDER_KEYS.includes(cfg.provider) ? cfg.provider : 'fal')
+
           const estimatedCost = calculateGenerationCost({
             provider: primaryProvider,
             model: cfg.model || cfg.customModel || 'default',
@@ -130,7 +137,7 @@ export function registerThemePairTools(ctx, deps) {
           })
           assertBudgetAvailable(estimatedCost, cfg.dailyBudgetUsd)
 
-          const chain = resolveFallbackChain(primaryProvider, cfg.fallbackChain)
+          const chain = resolveFallbackChain(primaryProvider, cfg.fallbackProviders, PROVIDER_KEYS)
           const baseSeed = typeof args.seed === 'number' ? args.seed : Math.floor(Math.random() * 1000000)
 
           const sessionCwd = exec.agent?.session?.header?.cwd
@@ -141,6 +148,9 @@ export function registerThemePairTools(ctx, deps) {
           const slug = args.output_name ? slugify(args.output_name) : slugify(prompt).slice(0, 36)
           const ts = Date.now().toString(36)
 
+          let subscriptionImages
+          try { subscriptionImages = ctx.get && ctx.get('subscriptionImages') } catch (_err) { subscriptionImages = undefined }
+
           // 1. Generate Light theme variant
           const lightJob = {
             prompt: lightPrompt,
@@ -150,22 +160,26 @@ export function registerThemePairTools(ctx, deps) {
             seed: baseSeed,
             signal: exec.signal,
           }
-          const lightGen = await executeWithFallback({
+          const lightProviders = makeProviders(
+            { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg, subscriptionImages },
+            lightJob,
+          )
+          const lightGen = await executeWithFallback(
+            lightProviders,
             chain,
-            liveConfig: cfg,
-            makeProvidersFn: (deps, job) => makeProviders(deps, job),
-            resolveApiKeyFn: resolveApiKey,
-            job: lightJob,
-          })
+            baseSeed,
+            lightPrompt,
+            { logger: ctx.logger },
+          )
 
           const lightFilename = `${slug}-light-${ts}.png`
           const lightPath = path.join(outDir, lightFilename)
-          await writeFile(lightPath, lightGen.bytes)
+          await writeFile(lightPath, Buffer.from(lightGen.bytes))
 
-          const lightAttachment = await saveAttachmentSafe(ctx, {
+          const { attachment: lightAttachment, localUrl: lightUrl } = await saveAttachmentSafe(ctx, {
             bytes: lightGen.bytes,
             mediaType: 'image/png',
-            filename: lightFilename,
+            name: lightFilename,
             width: lightGen.width || aspectPixels[0],
             height: lightGen.height || aspectPixels[1],
           })
@@ -174,7 +188,6 @@ export function registerThemePairTools(ctx, deps) {
             ctx,
             meta: { provider: primaryProvider, model: cfg.model || cfg.customModel, prompt: lightPrompt },
           })
-          const lightUrl = lightAttachment.attachmentId ? `/dsh-image-gen/image?id=${encodeURIComponent(lightAttachment.attachmentId)}` : ''
 
           // 2. Generate Dark theme variant (using matched seed)
           const darkJob = {
@@ -185,22 +198,32 @@ export function registerThemePairTools(ctx, deps) {
             seed: baseSeed,
             signal: exec.signal,
           }
-          const darkGen = await executeWithFallback({
-            chain,
-            liveConfig: cfg,
-            makeProvidersFn: (deps, job) => makeProviders(deps, job),
-            resolveApiKeyFn: resolveApiKey,
-            job: darkJob,
-          })
+          const darkProviders = makeProviders(
+            { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg, subscriptionImages },
+            darkJob,
+          )
+
+          let darkGen
+          try {
+            darkGen = await executeWithFallback(
+              darkProviders,
+              chain,
+              baseSeed,
+              darkPrompt,
+              { logger: ctx.logger },
+            )
+          } catch (darkErr) {
+            throw new Error(`Failed to generate dark theme variant: ${darkErr.message}`)
+          }
 
           const darkFilename = `${slug}-dark-${ts}.png`
           const darkPath = path.join(outDir, darkFilename)
-          await writeFile(darkPath, darkGen.bytes)
+          await writeFile(darkPath, Buffer.from(darkGen.bytes))
 
-          const darkAttachment = await saveAttachmentSafe(ctx, {
+          const { attachment: darkAttachment, localUrl: darkUrl } = await saveAttachmentSafe(ctx, {
             bytes: darkGen.bytes,
             mediaType: 'image/png',
-            filename: darkFilename,
+            name: darkFilename,
             width: darkGen.width || aspectPixels[0],
             height: darkGen.height || aspectPixels[1],
           })
@@ -208,7 +231,6 @@ export function registerThemePairTools(ctx, deps) {
             ctx,
             meta: { provider: primaryProvider, model: cfg.model || cfg.customModel, prompt: darkPrompt },
           })
-          const darkUrl = darkAttachment.attachmentId ? `/dsh-image-gen/image?id=${encodeURIComponent(darkAttachment.attachmentId)}` : ''
 
           // Sidecars
           await writeFile(
@@ -220,8 +242,8 @@ export function registerThemePairTools(ctx, deps) {
               size: `${aspectPixels[0]}x${aspectPixels[1]}`,
               format: 'png',
               seed: baseSeed,
-              light: { path: lightPath, url: lightUrl, attachmentId: lightAttachment.attachmentId },
-              dark: { path: darkPath, url: darkUrl, attachmentId: darkAttachment.attachmentId },
+              light: { path: lightPath, url: lightUrl, attachmentId: lightAttachment?.attachmentId },
+              dark: { path: darkPath, url: darkUrl, attachmentId: darkAttachment?.attachmentId },
               cost: (lightGen.cost || 0) + (darkGen.cost || 0),
             }), null, 2),
           )
@@ -266,4 +288,4 @@ export function registerThemePairTools(ctx, deps) {
       }),
     )
   }, 'dsh-image-gen: tool generate_theme_pair')
-}
+}

package/lib/tools/vision-ocr.js

@@ -1,16 +1,18 @@
-import { sanitizeErrorAndLogs } from '../security.js'
-// vision-ocr.js — replace_image_text tool (#180).
-// Seamless text replacement and OCR localization via dsh-vision-bridge & inpainting.
+// vision-ocr.js — replace_image_text tool (#180, #360).
+// Grounding OCR, background inpainting, and typography re-rendering for visual localization.
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import path from 'node:path'
 import { mkdir, writeFile } from 'node:fs/promises'
 import {
-  ASPECT_RATIOS,
+  PROVIDER_KEYS,
   makeProviders,
+  toLosslessJson,
   saveAttachmentSafe,
 } from '../providers.js'
+import { buildDualOutputMarkdown } from '../resolve-image.js'
 import { resolveFallbackChain, executeWithFallback } from '../fallback-router.js'
+import { assertBudgetAvailable, calculateGenerationCost, recordSpend } from '../cost-meter.js'
 import { renderToolOutput } from '../attachment-helper.js'
 import {
   normalizeBbox,
@@ -22,7 +24,7 @@ export function registerVisionOcrTools(ctx, deps) {
   const {
     live,
     resolveSource,
-    slugify,
+    slugify = (s) => String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '-'),
     resolveApiKey,
   } = deps
 
@@ -31,22 +33,28 @@ export function registerVisionOcrTools(ctx, deps) {
       defineTool({
         name: 'replace_image_text',
         description:
-          'Locate text inscriptions on an image via vision OCR, erase them seamlessly via inpainting, '
-          + 'and render translated or replaced typography precisely at the original coordinates.',
+          'Locate text elements in an image using OCR/vision grounding, inpaint the background to erase them, '
+          + 'and render crisp translated/replacement typography over the cleaned regions for visual localization.',
         parameters: {
           image: {
             type: 'string',
-            description: 'Source image path, URL, or attachment id (sha256:...) containing text to replace.',
+            description: 'Source image path, attachment ID, or URL containing text to replace.',
           },
           replacements: {
             type: 'array',
-            description: 'Array of text replacements: [{ find: "Old Text", replace: "New Text", bbox: [x1,y1,x2,y2] }].',
+            description: 'List of text replacement instructions.',
             items: {
               type: 'object',
               additionalProperties: true,
               properties: {
-                find: { type: 'string', description: 'Original text to locate' },
-                replace: { type: 'string', description: 'New replacement text to render' },
+                find: {
+                  type: 'string',
+                  description: 'Original text string to search for and erase.',
+                },
+                replace: {
+                  type: 'string',
+                  description: 'Replacement text to render in place of the original.',
+                },
                 bbox: {
                   type: 'array',
                   items: { type: 'number' },
@@ -75,6 +83,10 @@ export function registerVisionOcrTools(ctx, deps) {
             type: 'string',
             description: 'Optional provider override for inpainting. Defaults to active provider.',
           },
+          seed: {
+            type: 'integer',
+            description: 'Optional seed for reproducible inpainting.',
+          },
         },
         output: {
           schema: {
@@ -90,6 +102,9 @@ export function registerVisionOcrTools(ctx, deps) {
                 },
               },
               inpaintPrompt: { type: 'string' },
+              targetLanguage: { type: 'string' },
+              path: { type: 'string' },
+              url: { type: 'string' },
               attachment: {
                 type: 'object',
                 additionalProperties: true,
@@ -108,13 +123,23 @@ export function registerVisionOcrTools(ctx, deps) {
                 type: 'object',
                 additionalProperties: true,
               },
+              _fallback: {
+                type: 'object',
+                additionalProperties: true,
+              },
             },
           },
           render: (_args, value) => renderToolOutput(value),
         },
         async execute(args, execCtx) {
-          const cfg = live?.value || (typeof live === 'function' ? live() : {})
-          const activeProvider = args.provider || cfg.activeProvider || 'fal'
+          const cfg = typeof live === 'function' ? live() : (live?.value || {})
+          if (cfg.enabled === false) {
+            throw new Error('Image generation is disabled in settings.')
+          }
+
+          const provider = PROVIDER_KEYS.includes(args.provider || cfg.provider)
+            ? (args.provider || cfg.provider)
+            : (PROVIDER_KEYS.includes(cfg.provider) ? cfg.provider : 'fal')
 
           const source = await resolveSource(ctx, execCtx, args.image)
           if (!source || !source.bytes) {
@@ -148,7 +173,6 @@ export function registerVisionOcrTools(ctx, deps) {
               }
             }
 
-            // Fallback default bounding box if detection didn't locate exact coordinates
             const normalizedBox = normalizeBbox(bbox || [200, 400, 800, 500], imgWidth, imgHeight)
             if (normalizedBox) {
               bboxes.push(normalizedBox)
@@ -160,12 +184,11 @@ export function registerVisionOcrTools(ctx, deps) {
             }
           }
 
-          // If no replacements specified, check default center title box
           if (bboxes.length === 0) {
             const defaultBox = [150, 420, 850, 520]
             bboxes.push(defaultBox)
             overlayItems.push({
-              text: 'Localized Text',
+              text: args.target_language ? `[${args.target_language}] Localized Text` : 'Localized Text',
               bbox: defaultBox,
               color: args.font_color || '#FFFFFF',
             })
@@ -181,12 +204,10 @@ export function registerVisionOcrTools(ctx, deps) {
 
           // 4. Inpaint to erase old text
           const inpaintPrompt = args.inpaint_prompt || 'clean seamless surface, erase text artifacts, coherent background texture'
-          const providers = makeProviders({
-            fetchImpl: fetch,
-            resolveKey: (id) => resolveApiKey(cfg, id),
-            cfg,
-          })
-          const fallbackChain = resolveFallbackChain(activeProvider, cfg)
+          const seed = typeof args.seed === 'number' ? args.seed : Math.floor(Math.random() * 2147483647)
+
+          let subscriptionImages
+          try { subscriptionImages = ctx.get && ctx.get('subscriptionImages') } catch (_err) { subscriptionImages = undefined }
 
           const inpaintJob = {
             prompt: inpaintPrompt,
@@ -200,77 +221,119 @@ export function registerVisionOcrTools(ctx, deps) {
             },
             strength: 0.95,
             format: 'png',
+            seed,
+            signal: execCtx?.signal,
+          }
+
+          const providers = makeProviders(
+            { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg, subscriptionImages },
+            inpaintJob,
+          )
+          const fallbackChain = resolveFallbackChain(provider, cfg.fallbackProviders, PROVIDER_KEYS)
+
+          const estimatedCost = calculateGenerationCost({
+            provider,
+            model: cfg.model || cfg.customModel || 'default',
+            size: `${imgWidth}x${imgHeight}`,
+            count: 1,
+          })
+          assertBudgetAvailable(estimatedCost, cfg.dailyBudgetUsd)
+
+          const gen = await executeWithFallback(
+            providers,
+            fallbackChain,
+            seed,
+            inpaintPrompt,
+            { logger: ctx.logger },
+          )
+
+          const inpaintedBytes = gen.bytes
+          if (!inpaintedBytes) {
+            throw new Error('Inpainting failed to return image bytes for text replacement')
           }
 
-          let inpaintedBytes = null
-          let inpaintedUrl = null
+          // 5. Composite typography overlay on inpainted background
+          let finalBytes = inpaintedBytes
           try {
-            const { result: inpaintResult } = await executeWithFallback(
-              fallbackChain,
-              providers,
-              inpaintJob,
-              { signal: execCtx?.signal }
-            )
-            inpaintedBytes = inpaintResult.bytes
-            inpaintedUrl = inpaintResult.url
-          } catch (_err) {
-            /* non-fatal: inpaint provider unavailable; use source bytes */
-            inpaintedBytes = source.bytes
+            const sharpMod = await import('sharp')
+            const sharp = sharpMod.default || sharpMod
+            finalBytes = await sharp(inpaintedBytes)
+              .composite([{ input: overlayBuffer, top: 0, left: 0 }])
+              .png()
+              .toBuffer()
+          } catch (sharpErr) {
+            if (ctx.logger?.warn) ctx.logger.warn(`Sharp compositing skipped: ${sharpErr.message}`)
           }
 
-          const outDir = path.resolve(process.cwd(), cfg.outputDir || 'output')
+          const usedProvider = gen._fallback?.providerUsed || provider
+          const sessionCwd = execCtx?.agent?.session?.header?.cwd
+          const targetDir = cfg.outputDir || 'generated/images'
+          const outDir = path.resolve(sessionCwd || process.cwd(), targetDir)
           await mkdir(outDir, { recursive: true })
           const timestamp = Date.now()
-          const safeSlug = slugify(args.image.slice(0, 20)) || 'localized-image'
+          const safeSlug = slugify(String(args.image || '').slice(0, 20)) || 'localized-image'
 
-          let attachment = null
-          if (inpaintedBytes) {
-            const filename = `text-replaced-${safeSlug}-${timestamp}.png`
-            const diskPath = path.join(outDir, filename)
-            await writeFile(diskPath, Buffer.from(inpaintedBytes))
-            attachment = await saveAttachmentSafe(
-              ctx,
-              Buffer.from(inpaintedBytes),
-              'image/png',
-              filename,
-              diskPath
-            )
-          } else if (inpaintedUrl) {
-            attachment = {
-              url: inpaintedUrl,
-              mediaType: 'image/png',
-              filename: `text-replaced-${safeSlug}-${timestamp}.png`,
-            }
-          }
+          const filename = `text-replaced-${safeSlug}-${timestamp}.png`
+          const { attachment, localUrl } = await saveAttachmentSafe(ctx, {
+            bytes: finalBytes,
+            mediaType: 'image/png',
+            name: filename,
+          })
+
+          const diskPath = path.join(outDir, filename)
+          await writeFile(diskPath, Buffer.from(finalBytes))
 
           const maskFilename = `mask-text-${safeSlug}-${timestamp}.svg`
-          const maskAttachment = await saveAttachmentSafe(
-            ctx,
-            maskBuffer,
-            'image/svg+xml',
-            maskFilename,
-            path.join(outDir, maskFilename)
-          )
+          const { attachment: maskAttachment } = await saveAttachmentSafe(ctx, {
+            bytes: maskBuffer,
+            mediaType: 'image/svg+xml',
+            name: maskFilename,
+          })
 
           const overlayFilename = `overlay-text-${safeSlug}-${timestamp}.svg`
-          const overlayAttachment = await saveAttachmentSafe(
+          const { attachment: overlayAttachment } = await saveAttachmentSafe(ctx, {
+            bytes: overlayBuffer,
+            mediaType: 'image/svg+xml',
+            name: overlayFilename,
+          })
+
+          const effectiveCost = Number(gen.cost) || estimatedCost
+          recordSpend(effectiveCost, {
             ctx,
-            overlayBuffer,
-            'image/svg+xml',
-            overlayFilename,
-            path.join(outDir, overlayFilename)
-          )
+            meta: { provider: usedProvider, model: cfg.model || cfg.customModel, prompt: inpaintPrompt, seed },
+          })
 
-          return {
+          const dualOutput = buildDualOutputMarkdown({
+            action: 'generated',
+            filePath: diskPath,
+            width: imgWidth,
+            height: imgHeight,
+            mediaType: 'image/png',
+            seed,
+            provider: usedProvider,
+            model: cfg.model || cfg.customModel || 'replace-image-text',
+            cost: gen.cost,
+            attachmentId: attachment?.attachmentId,
+          })
+
+          const response = {
+            summary: dualOutput,
             replacedCount: overlayItems.length,
             bboxes,
             inpaintPrompt,
+            targetLanguage: args.target_language || '',
+            seed,
+            provider: usedProvider,
+            path: diskPath,
+            url: localUrl,
             attachment,
             maskAttachment,
             overlayAttachment,
-            url: attachment?.url,
             attachmentId: attachment?.attachmentId,
+            _fallback: gen._fallback,
           }
+
+          return toLosslessJson(response)
         },
       })
     )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-image-gen",
-  "version": "0.11.22",
+  "version": "0.11.23",
   "description": "Image generation for DeepSeek Harness: a generate_image tool with pluggable providers — the FAL queue, any OpenAI-compatible images API, or a ChatGPT/Grok subscription with no API key at all. The picture is shown inline in the conversation; the model receives either a link (works with any chat model) or the image itself (needs dsh-vision-bridge or a vision-capable model).",
   "keywords": [
     "deepseek-harness",