@goodandready/dsh-image-gen 0.11.39 → 0.11.41

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/capabilities.js

@@ -0,0 +1,139 @@
+import {
+  getCapabilityRegistry,
+  recommendModelForTask,
+  validateModelCapability,
+} from '../capabilities.js'
+
+/**
+ * Registers capability-based model selection tools (#434).
+ */
+export function registerCapabilityTools(ctx, deps = {}) {
+  ctx.tools.register({
+    name: 'select_image_model',
+    description: 'Recommends the best provider and model based on required task capabilities (text rendering, inpainting, face preservation, cost limits).',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        operations: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Required operations, e.g. ["txt2img", "inpaint", "img2img"].',
+        },
+        textRendering: {
+          type: 'boolean',
+          description: 'Whether native high-precision text rendering is required.',
+        },
+        facePreservation: {
+          type: 'boolean',
+          description: 'Whether facial identity likeness preservation is required.',
+        },
+        maskInpainting: {
+          type: 'boolean',
+          description: 'Whether pixel-accurate inpainting mask support is required.',
+        },
+        referenceConditioning: {
+          type: 'boolean',
+          description: 'Whether reference image guidance is required.',
+        },
+        controlnet: {
+          type: 'boolean',
+          description: 'Whether structural ControlNet guidance is required.',
+        },
+        minResolution: {
+          type: 'number',
+          description: 'Minimum resolution in pixels (e.g. 1024 or 2048).',
+        },
+        maxCostUSD: {
+          type: 'number',
+          description: 'Maximum estimated cost in USD per generation.',
+        },
+      },
+    },
+    output: {
+      render(args, value) {
+        if (!value?.ok) {
+          return [{ type: 'text', text: `Capability selection: ${value?.message || 'No matching model found.'}` }]
+        }
+        const rec = value.recommended
+        return [
+          {
+            type: 'text',
+            text: `Recommended Model: ${rec.displayName} (${rec.provider}/${rec.modelId})\nReason: ${value.recommendationReason}\nEstimated Cost: $${rec.estimatedCostUSD} (Source: ${rec.pricingSource})`,
+          },
+        ]
+      },
+    },
+    async execute(args) {
+      const requirements = {
+        operations: args.operations || [],
+        textRendering: Boolean(args.textRendering),
+        facePreservation: Boolean(args.facePreservation),
+        maskInpainting: Boolean(args.maskInpainting),
+        referenceConditioning: Boolean(args.referenceConditioning),
+        controlnet: Boolean(args.controlnet),
+        minResolution: args.minResolution || 0,
+        maxCost: args.maxCostUSD || Infinity,
+      }
+
+      // Check configured provider list from deps or runtime
+      const configuredProviders = deps.cfg?.provider ? [deps.cfg.provider] : null
+      return recommendModelForTask(requirements, { configuredProviders })
+    },
+  })
+
+  ctx.tools.register({
+    name: 'validate_model_features',
+    description: 'Pre-flight check if a model or provider supports specific generation features before running the task.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        provider: {
+          type: 'string',
+          description: 'Provider name (fal, gemini, replicate, local, seedream).',
+        },
+        modelId: {
+          type: 'string',
+          description: 'Specific model identifier.',
+        },
+        operation: {
+          type: 'string',
+          description: 'Requested operation (txt2img, img2img, inpaint).',
+        },
+        requiresMask: {
+          type: 'boolean',
+          description: 'Whether operation requires inpainting mask.',
+        },
+        requiresReference: {
+          type: 'boolean',
+          description: 'Whether operation requires reference image.',
+        },
+        requiresFacePreservation: {
+          type: 'boolean',
+          description: 'Whether operation requires face preservation.',
+        },
+        requiresTextRender: {
+          type: 'boolean',
+          description: 'Whether operation requires text rendering.',
+        },
+      },
+      required: ['provider'],
+    },
+    output: {
+      render(args, value) {
+        return [
+          {
+            type: 'text',
+            text: value.valid
+              ? `Validation PASSED for ${args.provider}: ${value.model?.displayName}`
+              : `Validation FAILED (${value.status}): ${value.reason}`,
+          },
+        ]
+      },
+    },
+    async execute(args) {
+      return validateModelCapability(args.provider, args.modelId, args)
+    },
+  })
+}

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/project-profiles.js

@@ -0,0 +1,139 @@
+import {
+  getAllProjectProfiles,
+  getProjectProfileById,
+  saveCustomProfile,
+  deleteCustomProfile,
+  resolveEffectiveParams,
+} from '../project-profiles.js'
+
+/**
+ * Registers project visual profile management tools (#435).
+ */
+export function registerProjectProfileTools(ctx, deps = {}) {
+  ctx.tools.register({
+    name: 'manage_project_profiles',
+    description: 'Manages visual project and series profiles (list, get, save, delete) for consistent styling across generation sets.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['list', 'get', 'save', 'delete'],
+          description: 'Action to perform: list all profiles, get by id, save (create/update), or delete.',
+        },
+        id: {
+          type: 'string',
+          description: 'Profile ID for get or delete actions.',
+        },
+        profile: {
+          type: 'object',
+          additionalProperties: true,
+          description: 'Profile specification object for save action (id, name, palette, stylePrompt, negativePrompt, format, rules).',
+        },
+      },
+      required: ['action'],
+    },
+    output: {
+      render(args, value) {
+        if (args.action === 'list') {
+          const list = Array.isArray(value) ? value : []
+          return [
+            {
+              type: 'text',
+              text: `Project Profiles (${list.length}):\n` +
+                list.map((p) => `- [${p.id}] ${p.name} (v${p.version || '1.0.0'}) ${p.builtin ? '(builtin)' : '(custom)'}`).join('\n'),
+            },
+          ]
+        }
+        if (args.action === 'get') {
+          return [
+            {
+              type: 'text',
+              text: value ? `Profile [${value.id}] ${value.name}:\nStyle: "${value.stylePrompt || ''}"\nPalette: ${(value.palette || []).join(', ')}` : 'Profile not found.',
+            },
+          ]
+        }
+        if (args.action === 'save') {
+          return [{ type: 'text', text: `Saved profile [${value?.id}] ${value?.name} successfully.` }]
+        }
+        if (args.action === 'delete') {
+          return [{ type: 'text', text: value ? `Deleted profile ${args.id}.` : `Profile ${args.id} not found or cannot be deleted.` }]
+        }
+        return [{ type: 'text', text: JSON.stringify(value) }]
+      },
+    },
+    async execute(args) {
+      const storagePath = deps.profilesPath || null
+      if (args.action === 'list') {
+        return getAllProjectProfiles(storagePath)
+      }
+      if (args.action === 'get') {
+        return getProjectProfileById(args.id, storagePath)
+      }
+      if (args.action === 'save') {
+        return saveCustomProfile(args.profile, storagePath)
+      }
+      if (args.action === 'delete') {
+        return deleteCustomProfile(args.id, storagePath)
+      }
+      throw new Error(`Unknown action: ${args.action}`)
+    },
+  })
+
+  ctx.tools.register({
+    name: 'resolve_project_profile_params',
+    description: 'Calculates effective generation parameters by cascading request overrides over a project visual profile and system defaults.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        profileId: {
+          type: 'string',
+          description: 'Identifier of the project visual profile.',
+        },
+        prompt: {
+          type: 'string',
+          description: 'Specific image request prompt.',
+        },
+        negativePrompt: {
+          type: 'string',
+          description: 'Specific negative prompt overrides.',
+        },
+        size: {
+          type: 'string',
+          description: 'Specific dimensions (e.g. 1024x1024 or 1280x720).',
+        },
+        format: {
+          type: 'string',
+          description: 'Output format (webp, png, jpeg).',
+        },
+      },
+      required: ['profileId'],
+    },
+    output: {
+      render(args, value) {
+        return [
+          {
+            type: 'text',
+            text: `Effective Parameters for Profile [${value?.appliedProfile?.name || args.profileId}]:\n` +
+              `Prompt: "${value?.effectiveParams?.prompt || ''}"\n` +
+              `Negative: "${value?.effectiveParams?.negativePrompt || ''}"\n` +
+              `Dimensions: ${value?.effectiveParams?.size} (${value?.effectiveParams?.format})\n` +
+              `Provenance: ${JSON.stringify(value?.provenance || {})}`,
+          },
+        ]
+      },
+    },
+    async execute(args) {
+      const storagePath = deps.profilesPath || null
+      const requestParams = {
+        prompt: args.prompt,
+        negativePrompt: args.negativePrompt,
+        size: args.size,
+        format: args.format,
+      }
+      return resolveEffectiveParams(requestParams, args.profileId, storagePath)
+    },
+  })
+}

package/package.json

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