@goodandready/dsh-image-gen 0.11.21 → 0.11.23

package/lib/tools/processing-basic.js

@@ -15,7 +15,7 @@ import {
   saveAttachmentSafe,
 } from '../providers.js'
 import { buildDualOutputMarkdown } from '../resolve-image.js'
-import { assertBudgetAvailable } from '../cost-meter.js'
+import { assertBudgetAvailable, recordSpend } from '../cost-meter.js'
 import { trackAndAssertLoopGuard } from '../loop-guard.js'
 import { sanitizeErrorAndLogs } from '../security.js'
 
@@ -55,6 +55,7 @@ export function registerProcessingTools(ctx, deps) {
             const source = await resolveSource(ctx, exec, args.image)
             if (!source || !source.bytes) throw new Error('Source image not found: ' + args.image)
           const cfg = live()
+          assertBudgetAvailable(0.02, cfg.dailyBudgetUsd)
           const res = await removeBackgroundFal(
             { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg },
             { imageBytes: source.bytes, mediaType: source.mediaType, model: args.model, signal: exec.signal }
@@ -67,6 +68,7 @@ export function registerProcessingTools(ctx, deps) {
           await mkdir(outDir, { recursive: true })
           const filePath = path.join(outDir, name)
           await writeFile(filePath, res.bytes)
+          recordSpend(0.02, { ctx, meta: { tool: 'remove_background', model: args.model || 'fal-ai/birefnet' } })
           const summary = buildDualOutputMarkdown({
             action: 'background removed',
             filePath,
@@ -124,6 +126,7 @@ export function registerProcessingTools(ctx, deps) {
             const source = await resolveSource(ctx, exec, args.image)
             if (!source || !source.bytes) throw new Error('Source image not found: ' + args.image)
           const cfg = live()
+          assertBudgetAvailable(0.025, cfg.dailyBudgetUsd)
           const res = await upscaleImageFal(
             { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg },
             { imageBytes: source.bytes, mediaType: source.mediaType, scale: args.scale, prompt: args.prompt, creativity: args.creativity, signal: exec.signal }
@@ -136,6 +139,7 @@ export function registerProcessingTools(ctx, deps) {
           await mkdir(outDir, { recursive: true })
           const filePath = path.join(outDir, name)
           await writeFile(filePath, res.bytes)
+          recordSpend(0.025, { ctx, meta: { tool: 'upscale_image', scale: args.scale } })
           const summary = buildDualOutputMarkdown({
             action: `upscaled (${args.scale || 2}x)`,
             filePath,
@@ -269,6 +273,7 @@ export function registerProcessingTools(ctx, deps) {
           await mkdir(outDir, { recursive: true })
           const filePath = path.join(outDir, name)
           await writeFile(filePath, res.bytes)
+          recordSpend(0.05, { ctx, meta: { tool: 'blend_images' } })
           const summary = buildDualOutputMarkdown({
             action: 'blended composition',
             filePath,

package/lib/tools/style-matrix.js

@@ -14,6 +14,7 @@ import {
   saveAttachmentSafe,
 } from '../providers.js'
 import { resolveFallbackChain, executeWithFallback } from '../fallback-router.js'
+import { assertBudgetAvailable, calculateGenerationCost, recordSpend } from '../cost-meter.js'
 import {
   normalizeMatrixStyles,
   buildMatrixCellPrompt,
@@ -129,6 +130,15 @@ export function registerStyleMatrixTools(ctx, deps) {
           let subscriptionImages
           try { subscriptionImages = ctx.get && ctx.get('subscriptionImages') } catch (_err) { subscriptionImages = undefined }
 
+          const cellCount = activeStyles.length
+          const estimatedCost = calculateGenerationCost({
+            provider,
+            model: cfg.model || cfg.customModel || 'default',
+            size: cfg.defaultSize || '1024x1024',
+            count: cellCount,
+          })
+          assertBudgetAvailable(estimatedCost, cfg.dailyBudgetUsd)
+
           const chain = resolveFallbackChain(provider, cfg.fallbackProviders, PROVIDER_KEYS)
           const quadrantIds = ['A', 'B', 'C', 'D']
           const matrixId = `matrix-${Date.now().toString(36)}`
@@ -168,6 +178,12 @@ export function registerStyleMatrixTools(ctx, deps) {
               name: filename,
             })
 
+            const cellCost = Number(gen.cost) || +(estimatedCost / cellCount).toFixed(4)
+            recordSpend(cellCost, {
+              ctx,
+              meta: { provider, model: cfg.model || cfg.customModel, prompt: cellPrompt, seed: cellSeed },
+            })
+
             const filePath = path.join(outDir, filename)
             await writeFile(filePath, gen.bytes)
 

package/lib/tools/theme-pair.js

@@ -1,18 +1,19 @@
-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,
   saveAttachmentSafe,
 } from '../providers.js'
 import { resolveFallbackChain, executeWithFallback } from '../fallback-router.js'
+import { assertBudgetAvailable, calculateGenerationCost, recordSpend } from '../cost-meter.js'
 import { renderToolOutput } from '../attachment-helper.js'
 import {
   THEME_STYLES,
@@ -23,7 +24,7 @@ import {
 export function registerThemePairTools(ctx, deps) {
   const {
     live,
-    slugify,
+    slugify = (s) => String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '-'),
     resolveApiKey,
   } = deps
 
@@ -32,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',
@@ -62,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: {
@@ -99,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.')
           }
@@ -120,8 +125,19 @@ export function registerThemePairTools(ctx, deps) {
             darkContrastBoost,
           })
 
-          const primaryProvider = cfg.provider || 'fal'
-          const chain = resolveFallbackChain(primaryProvider, cfg.fallbackChain)
+          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',
+            size: cfg.defaultSize || '1024x1024',
+            count: 2,
+          })
+          assertBudgetAvailable(estimatedCost, cfg.dailyBudgetUsd)
+
+          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
@@ -132,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,
@@ -141,26 +160,34 @@ 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],
           })
-          const lightUrl = lightAttachment.attachmentId ? `/dsh-image-gen/image?id=${encodeURIComponent(lightAttachment.attachmentId)}` : ''
+          const halfCost = +(estimatedCost / 2).toFixed(4)
+          recordSpend(Number(lightGen.cost) || halfCost, {
+            ctx,
+            meta: { provider: primaryProvider, model: cfg.model || cfg.customModel, prompt: lightPrompt },
+          })
 
           // 2. Generate Dark theme variant (using matched seed)
           const darkJob = {
@@ -171,26 +198,39 @@ 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],
           })
-          const darkUrl = darkAttachment.attachmentId ? `/dsh-image-gen/image?id=${encodeURIComponent(darkAttachment.attachmentId)}` : ''
+          recordSpend(Number(darkGen.cost) || halfCost, {
+            ctx,
+            meta: { provider: primaryProvider, model: cfg.model || cfg.customModel, prompt: darkPrompt },
+          })
 
           // Sidecars
           await writeFile(
@@ -202,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),
           )
@@ -248,4 +288,4 @@ export function registerThemePairTools(ctx, deps) {
       }),
     )
   }, 'dsh-image-gen: tool generate_theme_pair')
-}
+}

package/lib/tools/ui-asset.js

@@ -15,6 +15,7 @@ import {
   saveAttachmentSafe,
 } from '../providers.js'
 import { resolveFallbackChain, executeWithFallback } from '../fallback-router.js'
+import { assertBudgetAvailable, calculateGenerationCost, recordSpend } from '../cost-meter.js'
 import { buildDualOutputMarkdown } from '../resolve-image.js'
 import {
   UI_ASSET_TYPES,
@@ -161,6 +162,14 @@ export function registerUiAssetTools(ctx, deps) {
             },
           )
 
+          const estimatedCost = calculateGenerationCost({
+            provider,
+            model: cfg.model || cfg.customModel || 'default',
+            size: cfg.defaultSize || '1024x1024',
+            count: 1,
+          })
+          assertBudgetAvailable(estimatedCost, cfg.dailyBudgetUsd)
+
           const chain = resolveFallbackChain(provider, cfg.fallbackProviders, PROVIDER_KEYS)
           const seedVal = args.seed ?? Math.floor(Math.random() * 100000)
 
@@ -201,6 +210,12 @@ export function registerUiAssetTools(ctx, deps) {
             name: filename,
           })
 
+          const effectiveCost = Number(gen.cost) || estimatedCost
+          recordSpend(effectiveCost, {
+            ctx,
+            meta: { provider, model: cfg.model || cfg.customModel, prompt: synthesizedPrompt, seed: seedVal },
+          })
+
           const sessionCwd = exec.agent?.session?.header?.cwd
           const targetDir = cfg.outputDir || 'generated/images'
           const outDir = path.resolve(sessionCwd || process.cwd(), targetDir)

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)
         },
       })
     )