@goodandready/dsh-image-gen 0.11.40 → 0.11.42

package/lib/lineage.js

@@ -0,0 +1,188 @@
+/**
+ * Image Lineage & Version Branching (#439)
+ * Traverses parent-child relationships across revisions, provides DAG queries,
+ * branching support, and sanitized parameter replay payloads.
+ */
+
+/**
+ * Sanitizes parameters to remove credentials and internal server paths.
+ */
+export function sanitizeLineageParams(params = {}) {
+  if (!params || typeof params !== 'object') return {}
+  const sanitized = {}
+  for (const [key, val] of Object.entries(params)) {
+    const lowerKey = key.toLowerCase()
+    // Exclude API keys and secrets
+    if (
+      lowerKey.includes('key') ||
+      lowerKey.includes('secret') ||
+      lowerKey.includes('token') ||
+      lowerKey.includes('auth') ||
+      lowerKey.includes('password')
+    ) {
+      continue
+    }
+
+    if (typeof val === 'string') {
+      // Clean host absolute paths (e.g. /mnt/external/... -> filename)
+      if (val.startsWith('/mnt/') || val.startsWith('/home/') || val.includes(':\\')) {
+        sanitized[key] = val.split(/[/\\]/).pop()
+      } else {
+        sanitized[key] = val
+      }
+    } else if (typeof val === 'object' && val !== null) {
+      sanitized[key] = sanitizeLineageParams(val)
+    } else {
+      sanitized[key] = val
+    }
+  }
+  return sanitized
+}
+
+/**
+ * Normalizes history entry into standard lineage node.
+ */
+export function normalizeLineageNode(entry, idx = 0) {
+  if (!entry) return null
+  const revisionId = entry.revisionId || entry.id || entry.attachmentId || `rev_${entry.timestamp || idx}`
+  const parentId = entry.parentId || entry.parentImageId || null
+  const branchId = entry.branchId || 'main'
+  const operation = entry.operation || (parentId ? 'edit' : 'generate')
+
+  return {
+    revisionId: String(revisionId),
+    parentId: parentId ? String(parentId) : null,
+    branchId: String(branchId),
+    operation,
+    timestamp: entry.timestamp || new Date().toISOString(),
+    prompt: entry.prompt || '',
+    seed: entry.seed !== undefined ? entry.seed : null,
+    provider: entry.provider || 'unknown',
+    model: entry.model || 'unknown',
+    path: entry.path || entry.url || '',
+    appliedProfile: entry.appliedProfile || null,
+    params: sanitizeLineageParams(entry.params || {
+      size: entry.size || entry.image_size,
+      aspectRatio: entry.aspectRatio || entry.aspect_ratio,
+      format: entry.format,
+    }),
+  }
+}
+
+/**
+ * Builds Lineage DAG map from array of history entries.
+ */
+export function buildLineageDAG(historyEntries = []) {
+  const nodes = new Map()
+  const childrenMap = new Map()
+
+  for (let i = 0; i < historyEntries.length; i++) {
+    const node = normalizeLineageNode(historyEntries[i], i)
+    if (node) {
+      nodes.set(node.revisionId, node)
+      // Also index by path or attachmentId for backward compatibility
+      if (historyEntries[i].path) {
+        nodes.set(historyEntries[i].path, node)
+      }
+      if (historyEntries[i].attachmentId) {
+        nodes.set(historyEntries[i].attachmentId, node)
+      }
+    }
+  }
+
+  // Build children relationships
+  for (const node of new Set(nodes.values())) {
+    if (node.parentId) {
+      const parent = nodes.get(node.parentId)
+      const parentKey = parent ? parent.revisionId : node.parentId
+      if (!childrenMap.has(parentKey)) {
+        childrenMap.set(parentKey, [])
+      }
+      childrenMap.get(parentKey).push(node)
+    }
+  }
+
+  return { nodes, childrenMap }
+}
+
+/**
+ * Retrieves the full ancestry chain and child branches for a revision.
+ */
+export function getImageLineage(targetId, historyEntries = []) {
+  if (!targetId) return null
+  const { nodes, childrenMap } = buildLineageDAG(historyEntries)
+
+  const targetNode = nodes.get(String(targetId))
+  if (!targetNode) return null
+
+  // 1. Ancestry chain (upward traversal from target to root)
+  const ancestry = []
+  let curr = targetNode
+  const visited = new Set()
+
+  while (curr && curr.parentId && !visited.has(curr.revisionId)) {
+    visited.add(curr.revisionId)
+    const parent = nodes.get(curr.parentId)
+    if (parent) {
+      ancestry.unshift(parent)
+      curr = parent
+    } else {
+      // Parent exists outside current history limit
+      ancestry.unshift({
+        revisionId: curr.parentId,
+        parentId: null,
+        branchId: 'unknown',
+        operation: 'unknown',
+        prompt: '[Historical ancestor not in current window]',
+        missing: true,
+      })
+      break
+    }
+  }
+
+  // 2. Direct children and branches
+  const children = childrenMap.get(targetNode.revisionId) || []
+  const branches = [...new Set(children.map((c) => c.branchId))]
+
+  return {
+    target: targetNode,
+    ancestry,
+    children,
+    branches,
+    depth: ancestry.length,
+  }
+}
+
+/**
+ * Produces a sanitized replay payload for re-running generation from a specific revision.
+ */
+export function getReplayPayload(revisionId, historyEntries = []) {
+  const lineage = getImageLineage(revisionId, historyEntries)
+  if (!lineage) {
+    return { ok: false, error: `Revision "${revisionId}" not found in history.` }
+  }
+
+  const node = lineage.target
+  const toolName = node.operation === 'edit' ? 'edit_image' : 'generate_image'
+
+  const replayParams = {
+    prompt: node.prompt,
+    ...(node.seed !== null ? { seed: node.seed } : {}),
+    ...node.params,
+  }
+
+  if (node.parentId && node.operation === 'edit') {
+    replayParams.image = node.parentId
+  }
+
+  return {
+    ok: true,
+    revisionId: node.revisionId,
+    tool: toolName,
+    provider: node.provider,
+    model: node.model,
+    params: replayParams,
+    reproducibilityNotes:
+      'Cloud models may exhibit minor pixel variations across runs with identical seed; ComfyUI/local models provide deterministic outputs when models and workflow match.',
+  }
+}

package/lib/register-tools.js

@@ -22,6 +22,10 @@ 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 { registerVariantTools } from './tools/variant-selection.js'
+import { registerLineageTools } from './tools/lineage.js'
 import {
   createLiveProgressSession,
   publishLiveProgress,
@@ -157,6 +161,18 @@ 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)
+    }
+    if (Boolean(sets.variants)) {
+      registerVariantTools(targetCtx, deps)
+    }
+    if (Boolean(sets.lineage)) {
+      registerLineageTools(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/lib/tools/lineage.js

@@ -0,0 +1,83 @@
+import {
+  getImageLineage,
+  getReplayPayload,
+} from '../lineage.js'
+import { readHistory } from '../history.js'
+
+/**
+ * Registers lineage inspection and replay tools (#439).
+ */
+export function registerLineageTools(ctx, deps = {}) {
+  ctx.tools.register({
+    name: 'inspect_image_lineage',
+    description: 'Inspects generation and edit history ancestry DAG for an image revision, showing parents, branches, and prompts.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        revisionId: {
+          type: 'string',
+          description: 'Revision ID, attachment ID, or image file path to inspect.',
+        },
+      },
+      required: ['revisionId'],
+    },
+    output: {
+      render(args, value) {
+        if (!value?.target) return [{ type: 'text', text: `No lineage found for "${args.revisionId}".` }]
+        const t = value.target
+        const ancestryLines = (value.ancestry || []).map((a, i) => `  [Parent ${i + 1}] (${a.operation}) ${a.prompt || a.revisionId}`).join('\n')
+        const childrenLines = (value.children || []).map((c) => `  [Child] (${c.operation}) ${c.prompt || c.revisionId}`).join('\n')
+
+        return [
+          {
+            type: 'text',
+            text: `Lineage for Revision: [${t.revisionId}]\n` +
+              `Branch: ${t.branchId} | Operation: ${t.operation}\n` +
+              `Prompt: "${t.prompt}"\n` +
+              (ancestryLines ? `Ancestry (${value.depth}):\n${ancestryLines}\n` : 'Root generation (no parents)\n') +
+              (childrenLines ? `Children:\n${childrenLines}` : 'Leaf revision (no children yet)'),
+          },
+        ]
+      },
+    },
+    async execute(args) {
+      const entries = typeof deps.readHistory === 'function' ? await deps.readHistory() : await readHistory()
+      return getImageLineage(args.revisionId, entries)
+    },
+  })
+
+  ctx.tools.register({
+    name: 'get_image_replay_payload',
+    description: 'Extracts sanitized parameter payload from a past image revision to replay or branch generation without credential leaks.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        revisionId: {
+          type: 'string',
+          description: 'Revision ID to extract replay configuration from.',
+        },
+      },
+      required: ['revisionId'],
+    },
+    output: {
+      render(args, value) {
+        if (!value?.ok) return [{ type: 'text', text: `Replay extraction failed: ${value?.error}` }]
+        return [
+          {
+            type: 'text',
+            text: `Replay Payload for [${value.revisionId}]:\n` +
+              `Tool: ${value.tool} (${value.provider}/${value.model})\n` +
+              `Parameters: ${JSON.stringify(value.params, null, 2)}\n` +
+              `Notes: ${value.reproducibilityNotes}`,
+          },
+        ]
+      },
+    },
+    async execute(args) {
+      const entries = typeof deps.readHistory === 'function' ? await deps.readHistory() : await readHistory()
+      return getReplayPayload(args.revisionId, entries)
+    },
+  })
+}

package/lib/tools/variant-selection.js

@@ -0,0 +1,132 @@
+import {
+  createVariantSession,
+  selectVariantWinner,
+  getVariantSession,
+} from '../variant-selection.js'
+
+/**
+ * Registers variant comparison and winner selection tools (#438).
+ */
+export function registerVariantTools(ctx, deps = {}) {
+  ctx.tools.register({
+    name: 'evaluate_image_variants',
+    description: 'Sets up a side-by-side comparison session for multiple image options with structured criteria.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        name: {
+          type: 'string',
+          description: 'Title for the evaluation session.',
+        },
+        variants: {
+          type: 'array',
+          items: {
+            type: 'object',
+            additionalProperties: true,
+            properties: {
+              path: { type: 'string' },
+              label: { type: 'string' },
+              seed: { type: 'number' },
+              prompt: { type: 'string' },
+            },
+          },
+          description: 'Array of at least 2 image variants to evaluate.',
+        },
+      },
+      required: ['variants'],
+    },
+    output: {
+      render(args, value) {
+        return [
+          {
+            type: 'text',
+            text: `Variant Session Created: [${value?.selectionId}] "${value?.name}"\n` +
+              `Variants (${value?.variants?.length}):\n` +
+              (value?.variants || [])
+                .map((v) => `  #${v.index}: ${v.label} (seed: ${v.seed || 'none'}) - ${v.path}`)
+                .join('\n'),
+          },
+        ]
+      },
+    },
+    async execute(args) {
+      const storagePath = deps.variantStoragePath || null
+      return createVariantSession(
+        {
+          name: args.name,
+          variants: args.variants,
+        },
+        storagePath
+      )
+    },
+  })
+
+  ctx.tools.register({
+    name: 'select_variant_winner',
+    description: 'Designates the winning variant, tags discards/refinements, and prepares continuation payload for next pipeline step.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        selectionId: {
+          type: 'string',
+          description: 'Evaluation session ID.',
+        },
+        winnerIndex: {
+          type: 'number',
+          description: 'Index of winning variant (0-based).',
+        },
+        winnerPath: {
+          type: 'string',
+          description: 'Path of winning variant (alternative to winnerIndex).',
+        },
+        refineIndexes: {
+          type: 'array',
+          items: { type: 'number' },
+          description: 'Optional indexes of variants kept for refinement.',
+        },
+        nextAction: {
+          type: 'string',
+          enum: ['none', 'upscale', 'edit', 'remix', 'vectorize'],
+          description: 'Next action to execute with the winner.',
+        },
+        actionParams: {
+          type: 'object',
+          additionalProperties: true,
+          description: 'Parameters for the next action.',
+        },
+      },
+      required: ['selectionId'],
+    },
+    output: {
+      render(args, value) {
+        if (!value?.ok) return [{ type: 'text', text: `Selection failed: ${value?.error}` }]
+        const w = value.winner
+        return [
+          {
+            type: 'text',
+            text: `Selected Winner: Option #${w.index} (${w.label})\n` +
+              `Path: ${w.path}\n` +
+              `Next Action: ${value.continuationPayload?.action || 'None'}\n` +
+              (value.continuationPayload ? `Continuation Ready: ${JSON.stringify(value.continuationPayload.params)}` : ''),
+          },
+        ]
+      },
+    },
+    async execute(args) {
+      const storagePath = deps.variantStoragePath || null
+      return selectVariantWinner(
+        args.selectionId,
+        {
+          winnerIndex: args.winnerIndex,
+          winnerPath: args.winnerPath,
+          refineIndexes: args.refineIndexes,
+          nextAction: args.nextAction,
+          actionParams: args.actionParams,
+        },
+        storagePath
+      )
+    },
+  })
+}