@goodandready/dsh-image-gen 0.11.41 → 0.11.42

package/lib/index.js

@@ -54,6 +54,8 @@ import { getCapabilityRegistry, filterModelsByCapabilities, recommendModelForTas
 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'
@@ -583,6 +585,71 @@ export function apply(ctx, rawConfig) {
     },
   }), '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/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

@@ -24,6 +24,8 @@ 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,
@@ -165,6 +167,12 @@ export function registerAllTools(ctx, 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/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
+      )
+    },
+  })
+}

package/lib/variant-selection.js

@@ -0,0 +1,170 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+
+/**
+ * Variant Comparison & Winner Selection Workflow (#438)
+ * Manages side-by-side variant comparisons, winner/refine/discard tagging,
+ * and continuation payload construction for downstream editing or upscaling.
+ */
+
+export function getVariantStoragePath(customPath) {
+  if (customPath) return customPath
+  if (process.env.DSH_VARIANT_STORAGE_PATH) return process.env.DSH_VARIANT_STORAGE_PATH
+  const home = os.homedir() || '/tmp'
+  return path.join(home, '.dsh', 'dsh-image-gen', 'variant-selections.json')
+}
+
+export function loadVariantSessions(storagePath) {
+  const filePath = getVariantStoragePath(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 saveVariantSession(session, storagePath) {
+  const filePath = getVariantStoragePath(storagePath)
+  const dir = path.dirname(filePath)
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true })
+  }
+
+  const existing = loadVariantSessions(storagePath)
+  const index = existing.findIndex((s) => s.selectionId === session.selectionId)
+  if (index >= 0) {
+    existing[index] = session
+  } else {
+    existing.push(session)
+  }
+  fs.writeFileSync(filePath, JSON.stringify(existing, null, 2), 'utf8')
+  return session
+}
+
+export function getVariantSession(selectionId, storagePath) {
+  const sessions = loadVariantSessions(storagePath)
+  return sessions.find((s) => s.selectionId === selectionId) || null
+}
+
+/**
+ * Creates a new variant evaluation session.
+ */
+export function createVariantSession(params, storagePath) {
+  const {
+    name = 'Variant Shootout',
+    variants = [],
+    criteria = {},
+  } = params
+
+  if (!Array.isArray(variants) || variants.length < 2) {
+    throw new Error('Variant evaluation requires at least 2 image variants to compare.')
+  }
+
+  const selectionId = `vs_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+  const preparedVariants = variants.map((v, idx) => ({
+    index: idx,
+    id: v.id || `v_${idx + 1}`,
+    path: v.path || v.url || '',
+    label: v.label || `Option ${idx + 1}`,
+    seed: v.seed !== undefined ? v.seed : null,
+    prompt: v.prompt || '',
+    params: v.params || {},
+    status: 'undecided', // 'undecided' | 'winner' | 'refine' | 'discard'
+  }))
+
+  const session = {
+    selectionId,
+    name,
+    status: 'evaluating', // 'evaluating' | 'decided' | 'discarded'
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    criteria,
+    winnerIndex: null,
+    continuationPayload: null,
+    variants: preparedVariants,
+  }
+
+  return saveVariantSession(session, storagePath)
+}
+
+/**
+ * Selects the winning variant and constructs continuation payload for next step.
+ */
+export function selectVariantWinner(selectionId, options = {}, storagePath) {
+  const session = getVariantSession(selectionId, storagePath)
+  if (!session) {
+    return { ok: false, error: `Variant session "${selectionId}" not found.` }
+  }
+
+  const {
+    winnerIndex,
+    winnerPath,
+    refineIndexes = [],
+    nextAction = 'none',
+    actionParams = {},
+  } = options
+
+  // Find winner
+  let winner = null
+  if (typeof winnerIndex === 'number' && session.variants[winnerIndex]) {
+    winner = session.variants[winnerIndex]
+  } else if (winnerPath) {
+    winner = session.variants.find((v) => v.path === winnerPath) || null
+  }
+
+  if (!winner) {
+    return { ok: false, error: 'Valid winnerIndex or winnerPath must be specified.' }
+  }
+
+  // Update statuses
+  for (const v of session.variants) {
+    if (v.id === winner.id) {
+      v.status = 'winner'
+    } else if (refineIndexes.includes(v.index)) {
+      v.status = 'refine'
+    } else {
+      v.status = 'discard'
+    }
+  }
+
+  session.winnerIndex = winner.index
+  session.status = 'decided'
+  session.updatedAt = new Date().toISOString()
+
+  // Construct continuation payload
+  let continuationPayload = null
+  if (nextAction && nextAction !== 'none') {
+    continuationPayload = {
+      action: nextAction,
+      sourceImage: winner.path,
+      parentImageId: winner.path,
+      inheritedPrompt: winner.prompt,
+      inheritedSeed: winner.seed,
+      params: {
+        ...winner.params,
+        ...actionParams,
+        image: winner.path,
+      },
+    }
+  }
+
+  session.continuationPayload = continuationPayload
+  saveVariantSession(session, storagePath)
+
+  return {
+    ok: true,
+    selectionId,
+    status: 'decided',
+    winner: {
+      index: winner.index,
+      id: winner.id,
+      path: winner.path,
+      label: winner.label,
+    },
+    continuationPayload,
+  }
+}

package/package.json

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