@goodandready/dsh-image-gen 0.11.40 → 0.11.42

package/lib/batch-queue.js

@@ -0,0 +1,283 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+
+/**
+ * Resilient Batch Queue & Job Reconciliation (#437)
+ * Provides persistent queuing for image generation & processing series,
+ * with concurrency throttling, budget pre-checks, cancellation, and restart recovery.
+ */
+
+export function getQueueStoragePath(customPath) {
+  if (customPath) return customPath
+  if (process.env.DSH_BATCH_QUEUE_PATH) return process.env.DSH_BATCH_QUEUE_PATH
+  const home = os.homedir() || '/tmp'
+  return path.join(home, '.dsh', 'dsh-image-gen', 'batch-queue.json')
+}
+
+export function loadBatchQueues(storagePath) {
+  const filePath = getQueueStoragePath(storagePath)
+  try {
+    if (!fs.existsSync(filePath)) return []
+    const raw = fs.readFileSync(filePath, 'utf8')
+    const parsed = JSON.parse(raw)
+    return Array.isArray(parsed) ? parsed : []
+  } catch (err) {
+    return []
+  }
+}
+
+export function saveBatchQueue(batch, storagePath) {
+  const filePath = getQueueStoragePath(storagePath)
+  const dir = path.dirname(filePath)
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true })
+  }
+
+  const existing = loadBatchQueues(storagePath)
+  const index = existing.findIndex((b) => b.batchId === batch.batchId)
+  if (index >= 0) {
+    existing[index] = batch
+  } else {
+    existing.push(batch)
+  }
+  fs.writeFileSync(filePath, JSON.stringify(existing, null, 2), 'utf8')
+  return batch
+}
+
+export function getBatchQueue(batchId, storagePath) {
+  const queues = loadBatchQueues(storagePath)
+  return queues.find((b) => b.batchId === batchId) || null
+}
+
+/**
+ * Startup reconciliation (#437):
+ * Interrupted jobs (stuck in 'running' during crash/restart) are marked 'interrupted'
+ * and NEVER blindly retried without explicit user confirmation.
+ */
+export function reconcileQueueOnStartup(storagePath) {
+  const queues = loadBatchQueues(storagePath)
+  let updatedCount = 0
+
+  for (const batch of queues) {
+    let batchModified = false
+    for (const item of batch.items || []) {
+      if (item.status === 'running') {
+        item.status = 'interrupted'
+        item.interruptedAt = new Date().toISOString()
+        item.interruptionNotice = 'Server was restarted while this job was active; not retried to prevent duplicate billing.'
+        batchModified = true
+        updatedCount++
+      }
+    }
+    if (batchModified) {
+      if (batch.status === 'running') {
+        batch.status = 'interrupted'
+      }
+      saveBatchQueue(batch, storagePath)
+    }
+  }
+
+  return { reconciledJobs: updatedCount }
+}
+
+/**
+ * Enqueues a new batch of generation/processing jobs with budget pre-flight verification.
+ */
+export function enqueueBatch(params, storagePath) {
+  const {
+    name = 'Unnamed Batch',
+    items = [],
+    concurrency = 2,
+    maxBudget = Infinity,
+  } = params
+
+  if (!Array.isArray(items) || items.length === 0) {
+    throw new Error('Batch requires a non-empty array of items')
+  }
+
+  // Pre-calculate total estimated cost
+  let totalEstimatedCost = 0
+  const preparedItems = items.map((item, idx) => {
+    const cost = typeof item.estimatedCost === 'number' ? item.estimatedCost : 0.02
+    totalEstimatedCost += cost
+    return {
+      id: item.id || `item_${idx + 1}`,
+      tool: item.tool || 'generate_image',
+      params: item.params || {},
+      estimatedCost: cost,
+      status: 'queued',
+      createdAt: new Date().toISOString(),
+    }
+  })
+
+  if (totalEstimatedCost > maxBudget) {
+    throw new Error(
+      `Batch estimated cost ($${totalEstimatedCost.toFixed(3)}) exceeds allowed budget limit ($${maxBudget.toFixed(3)}). Pre-flight rejected.`
+    )
+  }
+
+  const batchId = `batch_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+  const batch = {
+    batchId,
+    name,
+    status: 'queued',
+    concurrency: Math.max(1, Math.min(10, concurrency)),
+    totalEstimatedCost,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    items: preparedItems,
+  }
+
+  saveBatchQueue(batch, storagePath)
+  return batch
+}
+
+/**
+ * Computes progress summary for a batch.
+ */
+export function getBatchProgress(batch) {
+  if (!batch || !Array.isArray(batch.items)) {
+    return { total: 0, completed: 0, failed: 0, queued: 0, running: 0, cancelled: 0, percent: 0 }
+  }
+
+  const items = batch.items
+  const total = items.length
+  const completed = items.filter((i) => i.status === 'succeeded').length
+  const failed = items.filter((i) => i.status === 'failed').length
+  const running = items.filter((i) => i.status === 'running').length
+  const queued = items.filter((i) => i.status === 'queued').length
+  const cancelled = items.filter((i) => i.status === 'cancelled').length
+  const interrupted = items.filter((i) => i.status === 'interrupted').length
+
+  const percent = total > 0 ? Math.round(((completed + failed) / total) * 100) : 0
+
+  return {
+    total,
+    completed,
+    failed,
+    running,
+    queued,
+    cancelled,
+    interrupted,
+    percent,
+  }
+}
+
+/**
+ * Cancels an entire batch or specific item.
+ */
+export function cancelBatch(batchId, itemId = null, storagePath) {
+  const batch = getBatchQueue(batchId, storagePath)
+  if (!batch) {
+    return { ok: false, error: `Batch "${batchId}" not found` }
+  }
+
+  const timestamp = new Date().toISOString()
+
+  if (itemId) {
+    const item = batch.items.find((i) => i.id === itemId)
+    if (!item) return { ok: false, error: `Item "${itemId}" not found in batch` }
+    if (item.status === 'queued') {
+      item.status = 'cancelled'
+      item.cancelledAt = timestamp
+    }
+  } else {
+    batch.status = 'cancelled'
+    for (const it of batch.items) {
+      if (it.status === 'queued') {
+        it.status = 'cancelled'
+        it.cancelledAt = timestamp
+      }
+    }
+  }
+
+  batch.updatedAt = timestamp
+  saveBatchQueue(batch, storagePath)
+  return { ok: true, batchId, status: batch.status, progress: getBatchProgress(batch) }
+}
+
+/**
+ * Resets failed items in a batch back to 'queued'.
+ */
+export function retryFailedBatchItems(batchId, targetItemIds = null, storagePath) {
+  const batch = getBatchQueue(batchId, storagePath)
+  if (!batch) {
+    return { ok: false, error: `Batch "${batchId}" not found` }
+  }
+
+  let resetCount = 0
+  for (const it of batch.items) {
+    if (it.status === 'failed' || it.status === 'interrupted') {
+      if (!targetItemIds || targetItemIds.includes(it.id)) {
+        it.status = 'queued'
+        it.error = null
+        it.interruptedAt = null
+        resetCount++
+      }
+    }
+  }
+
+  if (resetCount > 0) {
+    batch.status = 'queued'
+    batch.updatedAt = new Date().toISOString()
+    saveBatchQueue(batch, storagePath)
+  }
+
+  return { ok: true, resetCount, progress: getBatchProgress(batch) }
+}
+
+/**
+ * Processes queued items with concurrency limits using the supplied executor.
+ */
+export async function processBatchItems(batchId, executorFn, storagePath) {
+  const batch = getBatchQueue(batchId, storagePath)
+  if (!batch) throw new Error(`Batch "${batchId}" not found`)
+
+  batch.status = 'running'
+  saveBatchQueue(batch, storagePath)
+
+  const concurrency = batch.concurrency || 2
+  let runningCount = 0
+
+  const queuedItems = batch.items.filter((i) => i.status === 'queued')
+
+  for (const item of queuedItems) {
+    // Check if batch was cancelled while processing
+    const currentBatch = getBatchQueue(batchId, storagePath)
+    if (currentBatch?.status === 'cancelled') {
+      break
+    }
+
+    item.status = 'running'
+    item.startedAt = new Date().toISOString()
+    saveBatchQueue(batch, storagePath)
+
+    try {
+      const res = await executorFn(item.tool, item.params)
+      item.status = 'succeeded'
+      item.result = res
+      item.completedAt = new Date().toISOString()
+    } catch (err) {
+      item.status = 'failed'
+      item.error = err.message
+      item.completedAt = new Date().toISOString()
+    }
+
+    saveBatchQueue(batch, storagePath)
+  }
+
+  const finalProgress = getBatchProgress(batch)
+  if (finalProgress.queued === 0 && finalProgress.running === 0) {
+    batch.status = finalProgress.failed > 0 ? 'completed_with_errors' : 'completed'
+  }
+  batch.updatedAt = new Date().toISOString()
+  saveBatchQueue(batch, storagePath)
+
+  return {
+    ok: true,
+    batchId,
+    status: batch.status,
+    progress: getBatchProgress(batch),
+  }
+}

package/lib/index.js

@@ -52,6 +52,10 @@ import { getAllRecipes, getRecipe } from './recipes.js'
 import { getComfyTemplates, getComfyTemplate, createComfyDependencyValidator } from './comfy-catalog.js'
 import { getCapabilityRegistry, filterModelsByCapabilities, recommendModelForTask } from './capabilities.js'
 import { getAllProjectProfiles, saveCustomProfile, deleteCustomProfile } from './project-profiles.js'
+import { getStagingSession, reviewStagedEdit, createStagingSession } from './inpaint-staging.js'
+import { enqueueBatch, getBatchQueue, getBatchProgress, cancelBatch, retryFailedBatchItems, reconcileQueueOnStartup } from './batch-queue.js'
+import { createVariantSession, selectVariantWinner, getVariantSession } from './variant-selection.js'
+import { getImageLineage, getReplayPayload } from './lineage.js'
 import { resetLoopGuard, getLoopGuardState } from './loop-guard.js'
 import { Config, plainConfig, volatileConfig, publicConfig, ensureConfig } from './config-schema.js'
 import { resolveSource } from './resolve-source.js'
@@ -511,6 +515,141 @@ export function apply(ctx, rawConfig) {
   }), 'dsh-image-gen: project profiles route')
 
   // Live events route (#379)
+  // Reconcile batch queues on startup (#437)
+  try {
+    reconcileQueueOnStartup()
+  } catch (err) {
+    // Non-fatal if queue storage is empty or initial
+  }
+
+  // Inpaint staging route (#436)
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-image-gen/staging',
+    handler: async (req, res) => {
+      const url = new URL(req.url, 'http://localhost')
+      if (req.method === 'GET') {
+        const stageId = url.searchParams.get('stageId')
+        const session = stageId ? getStagingSession(stageId) : null
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ ok: Boolean(session), session }))
+        return
+      }
+      if (req.method === 'POST') {
+        try {
+          const body = await readBoundedRequestBody(req, 1024 * 1024)
+          const data = JSON.parse(body.toString('utf8'))
+          const review = reviewStagedEdit(data.stageId, data.action, data)
+          res.writeHead(review.ok ? 200 : 400, { 'Content-Type': 'application/json' })
+          res.end(JSON.stringify(review))
+        } catch (err) {
+          res.writeHead(400, { 'Content-Type': 'application/json' })
+          res.end(JSON.stringify({ ok: false, error: err.message }))
+        }
+        return
+      }
+      res.writeHead(405, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ error: 'GET or POST only' }))
+    },
+  }), 'dsh-image-gen: staging route')
+
+  // Batch queue route (#437)
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-image-gen/queue',
+    handler: async (req, res) => {
+      const url = new URL(req.url, 'http://localhost')
+      if (req.method === 'GET') {
+        const batchId = url.searchParams.get('batchId')
+        const batch = batchId ? getBatchQueue(batchId) : null
+        const progress = batch ? getBatchProgress(batch) : null
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ ok: Boolean(batch), batch, progress }))
+        return
+      }
+      if (req.method === 'POST') {
+        try {
+          const body = await readBoundedRequestBody(req, 1024 * 1024)
+          const data = JSON.parse(body.toString('utf8'))
+          const batch = enqueueBatch(data)
+          res.writeHead(200, { 'Content-Type': 'application/json' })
+          res.end(JSON.stringify({ ok: true, batch }))
+        } catch (err) {
+          res.writeHead(400, { 'Content-Type': 'application/json' })
+          res.end(JSON.stringify({ ok: false, error: err.message }))
+        }
+        return
+      }
+      res.writeHead(405, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ error: 'GET or POST only' }))
+    },
+  }), 'dsh-image-gen: batch queue route')
+
+  // Variant comparison route (#438)
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-image-gen/variants',
+    handler: async (req, res) => {
+      const url = new URL(req.url, 'http://localhost')
+      if (req.method === 'GET') {
+        const selectionId = url.searchParams.get('selectionId')
+        const session = selectionId ? getVariantSession(selectionId) : null
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ ok: Boolean(session), session }))
+        return
+      }
+      if (req.method === 'POST') {
+        try {
+          const body = await readBoundedRequestBody(req, 1024 * 1024)
+          const data = JSON.parse(body.toString('utf8'))
+          let result
+          if (data.action === 'select' || data.winnerIndex !== undefined || data.winnerPath) {
+            result = selectVariantWinner(data.selectionId, data)
+          } else {
+            result = { ok: true, session: createVariantSession(data) }
+          }
+          res.writeHead(result.ok !== false ? 200 : 400, { 'Content-Type': 'application/json' })
+          res.end(JSON.stringify(result))
+        } catch (err) {
+          res.writeHead(400, { 'Content-Type': 'application/json' })
+          res.end(JSON.stringify({ ok: false, error: err.message }))
+        }
+        return
+      }
+      res.writeHead(405, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ error: 'GET or POST only' }))
+    },
+  }), 'dsh-image-gen: variants route')
+
+  // Image lineage route (#439)
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-image-gen/lineage',
+    handler: async (req, res) => {
+      if (req.method !== 'GET') {
+        res.writeHead(405, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ error: 'GET only' }))
+        return
+      }
+      const url = new URL(req.url, 'http://localhost')
+      const revisionId = url.searchParams.get('revisionId')
+      if (!revisionId) {
+        res.writeHead(400, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ ok: false, error: 'revisionId parameter required' }))
+        return
+      }
+      try {
+        const entries = await readHistory()
+        const lineage = getImageLineage(revisionId, entries)
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ ok: Boolean(lineage), lineage }))
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ ok: false, error: err.message }))
+      }
+    },
+  }), 'dsh-image-gen: lineage route')
+
   registerLiveProgressRoutes(ctx)
 
   // Reset loop guard when user sends a new message (#370)

package/lib/inpaint-staging.js

@@ -0,0 +1,236 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import sharp from 'sharp'
+
+/**
+ * Inpaint Staging & Review Workflow (#436)
+ * Enables review/accept/reject cycle for localized image edits,
+ * preserving original image data and supporting pixel-level compositing.
+ */
+
+export function getStagingStoragePath(customPath) {
+  if (customPath) return customPath
+  if (process.env.DSH_STAGING_STORAGE_PATH) return process.env.DSH_STAGING_STORAGE_PATH
+  const home = os.homedir() || '/tmp'
+  return path.join(home, '.dsh', 'dsh-image-gen', 'staging-sessions.json')
+}
+
+export function loadStagingSessions(storagePath) {
+  const filePath = getStagingStoragePath(storagePath)
+  try {
+    if (!fs.existsSync(filePath)) return []
+    const raw = fs.readFileSync(filePath, 'utf8')
+    const parsed = JSON.parse(raw)
+    return Array.isArray(parsed) ? parsed : []
+  } catch (err) {
+    return []
+  }
+}
+
+export function saveStagingSession(session, storagePath) {
+  const filePath = getStagingStoragePath(storagePath)
+  const dir = path.dirname(filePath)
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true })
+  }
+
+  const existing = loadStagingSessions(storagePath)
+  const index = existing.findIndex((s) => s.stageId === session.stageId)
+  if (index >= 0) {
+    existing[index] = session
+  } else {
+    existing.push(session)
+  }
+  fs.writeFileSync(filePath, JSON.stringify(existing, null, 2), 'utf8')
+  return session
+}
+
+export function getStagingSession(stageId, storagePath) {
+  const sessions = loadStagingSessions(storagePath)
+  return sessions.find((s) => s.stageId === stageId) || null
+}
+
+/**
+ * Creates a new inpaint staging session.
+ */
+export function createStagingSession(params, storagePath) {
+  const {
+    originalImage,
+    mask,
+    bbox,
+    prompt,
+    previewImage,
+    provider = 'fal',
+    model = 'default',
+    estimatedCost = 0.02,
+  } = params
+
+  if (!originalImage) {
+    throw new Error('originalImage is required to initialize staging session')
+  }
+
+  const stageId = `stage_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+  const session = {
+    stageId,
+    createdAt: new Date().toISOString(),
+    status: 'staged',
+    originalImage,
+    mask: mask || null,
+    bbox: bbox || null,
+    prompt: prompt || '',
+    previewImage: previewImage || null,
+    provider,
+    model,
+    estimatedCost,
+    history: [
+      {
+        action: 'created',
+        timestamp: new Date().toISOString(),
+        prompt: prompt || '',
+      },
+    ],
+  }
+
+  return saveStagingSession(session, storagePath)
+}
+
+/**
+ * Reviews a staged edit: accept, reject, retry, or cancel.
+ */
+export function reviewStagedEdit(stageId, action, options = {}, storagePath) {
+  const session = getStagingSession(stageId, storagePath)
+  if (!session) {
+    return {
+      ok: false,
+      error: `Staging session "${stageId}" not found.`,
+    }
+  }
+
+  if (session.status !== 'staged') {
+    return {
+      ok: false,
+      error: `Staging session "${stageId}" is already finalized with status "${session.status}".`,
+    }
+  }
+
+  const timestamp = new Date().toISOString()
+
+  if (action === 'accept') {
+    session.status = 'accepted'
+    session.resolvedAt = timestamp
+    session.history.push({ action: 'accepted', timestamp })
+    saveStagingSession(session, storagePath)
+    return {
+      ok: true,
+      status: 'accepted',
+      stageId,
+      finalImage: session.previewImage,
+      originalImage: session.originalImage,
+      parentImageId: session.originalImage,
+      message: 'Staged edit accepted. Result is committed as active version.',
+    }
+  }
+
+  if (action === 'reject') {
+    session.status = 'rejected'
+    session.resolvedAt = timestamp
+    session.history.push({ action: 'rejected', timestamp, reason: options.reason || 'User rejected preview' })
+    saveStagingSession(session, storagePath)
+    return {
+      ok: true,
+      status: 'rejected',
+      stageId,
+      originalImage: session.originalImage,
+      discardedPreview: session.previewImage,
+      message: 'Staged edit rejected. Original image remains untouched.',
+    }
+  }
+
+  if (action === 'cancel') {
+    session.status = 'cancelled'
+    session.resolvedAt = timestamp
+    session.history.push({ action: 'cancelled', timestamp })
+    saveStagingSession(session, storagePath)
+    return {
+      ok: true,
+      status: 'cancelled',
+      stageId,
+      originalImage: session.originalImage,
+      message: 'Staging session cancelled.',
+    }
+  }
+
+  if (action === 'retry') {
+    const newPrompt = options.prompt || session.prompt
+    session.history.push({
+      action: 'retry_requested',
+      timestamp,
+      prompt: newPrompt,
+    })
+    session.prompt = newPrompt
+    if (options.previewImage) {
+      session.previewImage = options.previewImage
+    }
+    saveStagingSession(session, storagePath)
+    return {
+      ok: true,
+      status: 'staged',
+      stageId,
+      prompt: newPrompt,
+      retryCount: session.history.filter((h) => h.action === 'retry_requested').length,
+      estimatedCost: session.estimatedCost,
+      message: 'Staged edit updated for retry.',
+    }
+  }
+
+  return {
+    ok: false,
+    error: `Unknown review action "${action}". Allowed: accept, reject, retry, cancel.`,
+  }
+}
+
+/**
+ * Pixel-level local compositing:
+ * Overlays edited region back onto the original image using Sharp,
+ * guaranteeing that pixels outside the modified area remain 100% identical to the source.
+ */
+export async function compositeInpaintPatch(originalBuffer, inpaintBuffer, maskBbox, dimensions = {}) {
+  const origMeta = await sharp(originalBuffer).metadata()
+  const width = dimensions.width || origMeta.width || 1024
+  const height = dimensions.height || origMeta.height || 1024
+
+  // If bounding box provided, crop or position patch over original
+  if (Array.isArray(maskBbox) && maskBbox.length === 4) {
+    let [x1, y1, x2, y2] = maskBbox
+    if (x1 > 1000 || y1 > 1000 || x2 > 1000 || y2 > 1000) {
+      // already in pixels
+    } else {
+      // normalized 0-1000
+      x1 = Math.round((x1 / 1000) * width)
+      y1 = Math.round((y1 / 1000) * height)
+      x2 = Math.round((x2 / 1000) * width)
+      y2 = Math.round((y2 / 1000) * height)
+    }
+
+    const patchW = Math.max(1, x2 - x1)
+    const patchH = Math.max(1, y2 - y1)
+
+    const resizedPatch = await sharp(inpaintBuffer)
+      .resize(patchW, patchH, { fit: 'fill' })
+      .toBuffer()
+
+    return sharp(originalBuffer)
+      .composite([{ input: resizedPatch, left: x1, top: y1 }])
+      .toBuffer()
+  }
+
+  // Full composite when dimensions match
+  const resizedInpaint = await sharp(inpaintBuffer)
+    .resize(width, height, { fit: 'fill' })
+    .toBuffer()
+
+  return sharp(originalBuffer)
+    .composite([{ input: resizedInpaint, blend: 'over' }])
+    .toBuffer()
+}