@goodandready/dsh-image-gen 0.11.40 → 0.11.41

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,8 @@ 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 { resetLoopGuard, getLoopGuardState } from './loop-guard.js'
 import { Config, plainConfig, volatileConfig, publicConfig, ensureConfig } from './config-schema.js'
 import { resolveSource } from './resolve-source.js'
@@ -511,6 +513,76 @@ 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')
+
   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()
+}

package/lib/register-tools.js

@@ -22,6 +22,8 @@ import { registerDiagramTools } from './tools/diagram.js'
 import { registerRecipeTools } from './tools/recipes.js'
 import { registerCapabilityTools } from './tools/capabilities.js'
 import { registerProjectProfileTools } from './tools/project-profiles.js'
+import { registerInpaintStagingTools } from './tools/inpaint-staging.js'
+import { registerBatchQueueTools } from './tools/batch-queue.js'
 import {
   createLiveProgressSession,
   publishLiveProgress,
@@ -157,6 +159,12 @@ export function registerAllTools(ctx, deps) {
     if (Boolean(sets.profiles)) {
       registerProjectProfileTools(targetCtx, deps)
     }
+    if (Boolean(sets.staging)) {
+      registerInpaintStagingTools(targetCtx, deps)
+    }
+    if (Boolean(sets.queue)) {
+      registerBatchQueueTools(targetCtx, deps)
+    }
   }
 
   function dispose() {

package/lib/tools/batch-queue.js

@@ -0,0 +1,134 @@
+import {
+  enqueueBatch,
+  getBatchQueue,
+  getBatchProgress,
+  cancelBatch,
+  retryFailedBatchItems,
+} from '../batch-queue.js'
+
+/**
+ * Registers batch queue management tools (#437).
+ */
+export function registerBatchQueueTools(ctx, deps = {}) {
+  ctx.tools.register({
+    name: 'enqueue_batch_jobs',
+    description: 'Enqueues a series of generation or processing jobs with budget pre-flight check and concurrency control.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        name: {
+          type: 'string',
+          description: 'Descriptive title for the batch.',
+        },
+        items: {
+          type: 'array',
+          items: {
+            type: 'object',
+            additionalProperties: true,
+            properties: {
+              tool: { type: 'string' },
+              params: { type: 'object', additionalProperties: true },
+              estimatedCost: { type: 'number' },
+            },
+          },
+          description: 'Array of jobs to execute.',
+        },
+        concurrency: {
+          type: 'number',
+          description: 'Maximum concurrent active workers (default 2, max 10).',
+        },
+        maxBudgetUSD: {
+          type: 'number',
+          description: 'Maximum total allowed budget in USD for this entire batch.',
+        },
+      },
+      required: ['items'],
+    },
+    output: {
+      render(args, value) {
+        return [
+          {
+            type: 'text',
+            text: `Enqueued Batch: [${value?.batchId}] "${value?.name}"\n` +
+              `Total Jobs: ${value?.items?.length} | Estimated Cost: $${value?.totalEstimatedCost?.toFixed(3)}\n` +
+              `Status: ${value?.status} | Concurrency: ${value?.concurrency}`,
+          },
+        ]
+      },
+    },
+    async execute(args) {
+      const storagePath = deps.queueStoragePath || null
+      return enqueueBatch(
+        {
+          name: args.name,
+          items: args.items,
+          concurrency: args.concurrency || 2,
+          maxBudget: args.maxBudgetUSD || Infinity,
+        },
+        storagePath
+      )
+    },
+  })
+
+  ctx.tools.register({
+    name: 'manage_batch_queue',
+    description: 'Manages batch queues: status inquiry, cancellation, or retrying failed items.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        batchId: {
+          type: 'string',
+          description: 'Target batch queue identifier.',
+        },
+        action: {
+          type: 'string',
+          enum: ['status', 'cancel', 'retry_failed'],
+          description: 'Action to perform: check status, cancel, or retry failed items.',
+        },
+        itemId: {
+          type: 'string',
+          description: 'Optional single item ID to cancel.',
+        },
+      },
+      required: ['batchId', 'action'],
+    },
+    output: {
+      render(args, value) {
+        if (args.action === 'status') {
+          const p = value?.progress || {}
+          return [
+            {
+              type: 'text',
+              text: `Batch [${args.batchId}] Status: ${value?.status} (${p.percent}%)\n` +
+                `Total: ${p.total} | Completed: ${p.completed} | Failed: ${p.failed} | Queued: ${p.queued} | Running: ${p.running} | Interrupted: ${p.interrupted || 0}`,
+            },
+          ]
+        }
+        if (args.action === 'cancel') {
+          return [{ type: 'text', text: `Cancelled batch [${args.batchId}]. Queued jobs discarded.` }]
+        }
+        if (args.action === 'retry_failed') {
+          return [{ type: 'text', text: `Reset ${value?.resetCount || 0} failed items for retry in batch [${args.batchId}].` }]
+        }
+        return [{ type: 'text', text: JSON.stringify(value) }]
+      },
+    },
+    async execute(args) {
+      const storagePath = deps.queueStoragePath || null
+      if (args.action === 'status') {
+        const batch = getBatchQueue(args.batchId, storagePath)
+        if (!batch) return { ok: false, error: `Batch "${args.batchId}" not found` }
+        return { ok: true, batchId: batch.batchId, status: batch.status, progress: getBatchProgress(batch), items: batch.items }
+      }
+      if (args.action === 'cancel') {
+        return cancelBatch(args.batchId, args.itemId, storagePath)
+      }
+      if (args.action === 'retry_failed') {
+        return retryFailedBatchItems(args.batchId, args.itemId ? [args.itemId] : null, storagePath)
+      }
+      throw new Error(`Unknown action: ${args.action}`)
+    },
+  })
+}

package/lib/tools/inpaint-staging.js

@@ -0,0 +1,116 @@
+import {
+  createStagingSession,
+  reviewStagedEdit,
+  getStagingSession,
+} from '../inpaint-staging.js'
+
+/**
+ * Registers staging & review workflow tools (#436).
+ */
+export function registerInpaintStagingTools(ctx, deps = {}) {
+  ctx.tools.register({
+    name: 'stage_image_edit',
+    description: 'Stages a localized inpaint or image modification in preview state for user review before committing.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        image: {
+          type: 'string',
+          description: 'Original image path or URL to edit.',
+        },
+        prompt: {
+          type: 'string',
+          description: 'Edit instruction or prompt for the localized modification.',
+        },
+        mask: {
+          type: 'string',
+          description: 'Optional inpainting mask path, base64, or SVG string.',
+        },
+        bbox: {
+          type: 'array',
+          items: { type: 'number' },
+          description: 'Optional bounding box [x1, y1, x2, y2] (normalized 0-1000).',
+        },
+        previewImage: {
+          type: 'string',
+          description: 'Initial preview image path if already produced.',
+        },
+      },
+      required: ['image', 'prompt'],
+    },
+    output: {
+      render(args, value) {
+        return [
+          {
+            type: 'text',
+            text: `Staging Session Created: [${value?.stageId}]\n` +
+              `Status: ${value?.status} (preview only, original preserved)\n` +
+              `Instruction: "${value?.prompt}"\n` +
+              `Preview: ${value?.previewImage || 'Generating in background...'}`,
+          },
+        ]
+      },
+    },
+    async execute(args) {
+      const storagePath = deps.stagingStoragePath || null
+      return createStagingSession(
+        {
+          originalImage: args.image,
+          prompt: args.prompt,
+          mask: args.mask,
+          bbox: args.bbox,
+          previewImage: args.previewImage,
+          provider: deps.cfg?.provider || 'fal',
+        },
+        storagePath
+      )
+    },
+  })
+
+  ctx.tools.register({
+    name: 'review_staged_edit',
+    description: 'Reviews a staged image edit: accept (commits change), reject (restores original), retry (new prompt), or cancel.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        stageId: {
+          type: 'string',
+          description: 'ID of the staging session to review.',
+        },
+        action: {
+          type: 'string',
+          enum: ['accept', 'reject', 'retry', 'cancel'],
+          description: 'Review decision: accept, reject, retry, or cancel.',
+        },
+        prompt: {
+          type: 'string',
+          description: 'New instruction if retrying with updated prompt.',
+        },
+        reason: {
+          type: 'string',
+          description: 'Optional reason when rejecting or cancelling.',
+        },
+      },
+      required: ['stageId', 'action'],
+    },
+    output: {
+      render(args, value) {
+        if (!value?.ok) {
+          return [{ type: 'text', text: `Review failed: ${value?.error || 'Unknown error'}` }]
+        }
+        return [
+          {
+            type: 'text',
+            text: `Review Result: ${value.message}\nStatus: ${value.status}\nStage ID: ${args.stageId}`,
+          },
+        ]
+      },
+    },
+    async execute(args) {
+      const storagePath = deps.stagingStoragePath || null
+      return reviewStagedEdit(args.stageId, args.action, { prompt: args.prompt, reason: args.reason }, storagePath)
+    },
+  })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-image-gen",
-  "version": "0.11.40",
+  "version": "0.11.41",
   "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",