onbuzz 3.3.0

package/src/tools/imageTool.js

@@ -0,0 +1,1034 @@
+/**
+ * @file tools/imageTool.js
+ * @description Tool for generating images using AI models (resolved dynamically from backend)
+ */
+
+import path from 'path';
+import os from 'os';
+import { promises as fs } from 'fs';
+import { BaseTool } from './baseTool.js';
+
+/**
+ * Configuration constants for image generation
+ */
+const IMAGE_CONFIG = {
+  DEFAULT_MODEL: null, // Resolved dynamically from modelsService via aiService
+  DEFAULT_SIZE: '1024x1024',
+  DEFAULT_QUALITY: 'standard',
+  // Flux 1.1 Pro size constraints
+  SIZE_MIN: 256,
+  SIZE_MAX: 1440,
+  SIZE_INCREMENT: 32,  // Must be multiples of 32
+  // Common presets for convenience (all valid per constraints above)
+  SIZE_PRESETS: {
+    'square': '1024x1024',
+    'square_hd': '1440x1440',
+    'portrait': '1024x1440',
+    'landscape': '1440x1024',
+    'portrait_4_3': '768x1024',
+    'landscape_4_3': '1024x768',
+    'small': '512x512'
+  },
+  VALID_FORMATS: ['png', 'jpg', 'jpeg', 'webp'],
+  MAX_CONCURRENT: 3,
+  QUEUE_LIMIT: 10,
+  TEMP_CLEANUP_MS: 3600000, // 1 hour
+  MAX_PROMPT_LENGTH: 4000,
+  DOWNLOAD_TIMEOUT: 60000 // 60 seconds
+};
+
+/**
+ * ImageTool - Generate images using AI models
+ * Supports queueing, async processing, and both temp/project directory storage
+ */
+export class ImageTool extends BaseTool {
+  constructor(config = {}, logger = null) {
+    super(config, logger);
+
+    // Override tool ID
+    this.id = 'image-gen';
+
+    // Job queue and tracking
+    this.queue = [];
+    this.currentJob = null;
+    this.completedJobs = new Map();
+    this.isProcessing = false;
+
+    // AIService will be injected later
+    this.aiService = null;
+
+    // AgentPool will be injected later (for saving to conversation history)
+    this.agentPool = null;
+
+    // Temp directory for images
+    this.tempDir = path.join(os.tmpdir(), 'loxia-images');
+
+    // Cleanup timers
+    this.cleanupTimers = new Map();
+  }
+
+  /**
+   * Set AI service for image generation
+   * @param {AIService} aiService - AI service instance
+   */
+  setAIService(aiService) {
+    this.aiService = aiService;
+    this.logger?.info('AI Service set for ImageTool');
+  }
+
+  /**
+   * Set Agent Pool for saving results to conversation history
+   * @param {AgentPool} agentPool - AgentPool instance
+   */
+  setAgentPool(agentPool) {
+    this.agentPool = agentPool;
+    this.logger?.info('AgentPool set for ImageTool');
+  }
+
+  /**
+   * Get tool description for agent system prompt
+   * @returns {string} Formatted tool description
+   */
+  getDescription() {
+    return `Tool: Image Generator - Generate and edit images using AI models
+
+**Purpose:** Generate images from text descriptions, edit existing images, and create images with transparency. Images are saved to files and displayed in chat.
+
+**CRITICAL: Automatic Execution**
+- ANY \`\`\`json block with "toolId": "image-gen" will be EXECUTED IMMEDIATELY
+- Just output the command when you want to generate or edit an image
+- If generation fails, output a NEW command with corrections
+
+**USAGE — Generate:**
+\`\`\`json
+{
+  "toolId": "image-gen",
+  "parameters": {
+    "prompt": "Detailed description of the image",
+    "outputPath": "images/filename.png",
+    "size": "1024x1024"
+  }
+}
+\`\`\`
+
+**USAGE — Generate with Transparency:**
+\`\`\`json
+{
+  "toolId": "image-gen",
+  "parameters": {
+    "prompt": "A cute fox mascot on a transparent background",
+    "model": "gpt-image-1.5",
+    "transparency": true,
+    "outputPath": "images/fox-mascot.png"
+  }
+}
+\`\`\`
+
+**USAGE — Edit Existing Image:**
+\`\`\`json
+{
+  "toolId": "image-gen",
+  "parameters": {
+    "prompt": "Remove the background and make it transparent",
+    "sourceImage": "images/photo.png",
+    "model": "gpt-image-1.5",
+    "outputPath": "images/photo-nobg.png"
+  }
+}
+\`\`\`
+
+**Parameters:**
+- **prompt** (required): Description of image to generate OR editing instruction
+- **outputPath** (optional): Path to save image (permanent). Omit for temp file.
+- **size** (optional): Custom WIDTHxHEIGHT or preset name (default: 1024x1024)
+  - For Flux models: 256-1440px, multiples of 32 (e.g., 1024x768, 1280x960)
+  - For gpt-image-1.5: 1024x1024, 1024x1536, 1536x1024, or "auto"
+  - Presets: square (1024x1024), square_hd (1440x1440), portrait (1024x1440), landscape (1440x1024), portrait_4_3 (768x1024), landscape_4_3 (1024x768), small (512x512)
+- **quality** (optional): "standard" or "hd" (default: standard)
+- **model** (optional): Use "gpt-image-1.5" for transparency and editing capabilities (default: auto)
+- **sourceImage** (optional): Path to source image for editing (enables edit mode)
+- **mask** (optional): Path to mask image for editing (white=edit area, black=keep area)
+- **transparency** (optional): true to generate image with transparent background (auto-selects gpt-image-1.5)
+
+**Notes:**
+- Images take 15-30 seconds to generate
+- Be descriptive in prompts for better results
+- Use **gpt-image-1.5** when you need: transparent backgrounds, image editing, or image-to-image transformations
+- Max ${IMAGE_CONFIG.QUEUE_LIMIT} images in queue`;
+  }
+
+  /**
+   * Parse image generation parameters
+   * @param {string|Object} content - Raw content or parsed object
+   * @returns {Object} Parsed parameters
+   */
+  parseParameters(content) {
+    // Handle JSON format
+    if (typeof content === 'object' && content !== null) {
+      return this._parseJSONParams(content);
+    }
+
+    // Handle string format
+    if (typeof content === 'string') {
+      const trimmed = content.trim();
+
+      // Try to parse as JSON first
+      if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+        try {
+          const parsed = JSON.parse(trimmed);
+          return this._parseJSONParams(parsed);
+        } catch (err) {
+          // Not valid JSON, fall through to XML parsing
+        }
+      }
+
+      // Parse as XML
+      return this._parseXMLParams(content);
+    }
+
+    throw new Error('Invalid parameter format');
+  }
+
+  /**
+   * Parse JSON parameters
+   * @private
+   */
+  _parseJSONParams(obj) {
+    // Handle parameters wrapper (when called via toolId/parameters structure)
+    if (obj.parameters) {
+      obj = obj.parameters;
+    }
+
+    // Check for batch mode
+    if (obj.batch && Array.isArray(obj.batch)) {
+      return {
+        batch: true,
+        images: obj.batch.map(img => this._parseImageParams(img))
+      };
+    }
+
+    return {
+      batch: false,
+      images: [this._parseImageParams(obj)]
+    };
+  }
+
+  /**
+   * Parse XML parameters
+   * @private
+   */
+  _parseXMLParams(content) {
+    const params = { batch: false, images: [] };
+
+    // Check for batch mode
+    const batchMatch = /<batch>([\s\S]*?)<\/batch>/i.exec(content);
+
+    if (batchMatch) {
+      params.batch = true;
+      const batchContent = batchMatch[1];
+
+      // Extract individual <image> blocks
+      const imageRegex = /<image>([\s\S]*?)<\/image>/gi;
+      let match;
+
+      while ((match = imageRegex.exec(batchContent)) !== null) {
+        params.images.push(this._parseXMLImage(match[1]));
+      }
+    } else {
+      // Single image mode
+      params.images.push(this._parseXMLImage(content));
+    }
+
+    if (params.images.length === 0) {
+      throw new Error('No valid image parameters found');
+    }
+
+    return params;
+  }
+
+  /**
+   * Parse single image parameters from object
+   * @private
+   */
+  _parseImageParams(obj) {
+    const outputPath = obj.outputPath || obj['output-path'] || null;
+
+    return {
+      prompt: obj.prompt || '',
+      outputPath: outputPath,
+      saveToProject: outputPath !== null, // If path specified, save to project
+      model: obj.model || IMAGE_CONFIG.DEFAULT_MODEL,
+      size: obj.size || IMAGE_CONFIG.DEFAULT_SIZE,
+      quality: obj.quality || IMAGE_CONFIG.DEFAULT_QUALITY,
+      sourceImage: obj.sourceImage || null,     // Edit mode: path to source image
+      mask: obj.mask || null,                   // Edit mode: path to mask image
+      transparency: obj.transparency || false   // Generate with transparent background
+    };
+  }
+
+  /**
+   * Parse single image parameters from XML string
+   * @private
+   */
+  _parseXMLImage(xmlContent) {
+    const extractTag = (tag) => {
+      const regex = new RegExp(`<${tag}>([\\s\\S]*?)<\\/${tag}>`, 'i');
+      const match = regex.exec(xmlContent);
+      return match ? match[1].trim() : null;
+    };
+
+    const outputPath = extractTag('output-path') || null;
+
+    return {
+      prompt: extractTag('prompt') || '',
+      outputPath: outputPath,
+      saveToProject: outputPath !== null, // If path specified, save to project
+      model: extractTag('model') || IMAGE_CONFIG.DEFAULT_MODEL,
+      size: extractTag('size') || IMAGE_CONFIG.DEFAULT_SIZE,
+      quality: extractTag('quality') || IMAGE_CONFIG.DEFAULT_QUALITY,
+      sourceImage: extractTag('source-image') || null,
+      mask: extractTag('mask') || null,
+      transparency: extractTag('transparency') === 'true'
+    };
+  }
+
+  /**
+   * Execute image generation
+   * @param {Object|string} params - Parsed parameters object OR raw XML/JSON string
+   * @param {Object} context - Execution context
+   * @returns {Promise<Object>} Execution result
+   */
+  async execute(params, context = {}) {
+    try {
+      const { agentId, projectDir, directoryAccess, sessionId } = context;
+
+      // Auto-detect and parse inputs (from TagParser or direct call)
+      // parseParameters() normalizes input to { batch: bool, images: [...] } format
+      if (typeof params === 'string') {
+        this.logger?.info('ImageTool: Auto-parsing string parameters');
+        params = this.parseParameters(params);
+      } else if (typeof params === 'object' && params !== null && !params.images) {
+        // Object params without 'images' array - needs parsing to normalize structure
+        this.logger?.info('ImageTool: Normalizing object parameters');
+        params = this.parseParameters(params);
+      }
+
+      // Validate parameters
+      this._validateParameters(params);
+
+      // Queue images
+      const jobIds = [];
+
+      for (const imageParams of params.images) {
+        // Create job
+        const jobId = this._generateJobId();
+
+        const job = {
+          jobId,
+          agentId,
+          sessionId,
+          prompt: imageParams.prompt,
+          outputPath: imageParams.outputPath,
+          saveToProject: imageParams.saveToProject,
+          model: imageParams.model,
+          size: imageParams.size,
+          quality: imageParams.quality,
+          projectDir: projectDir || process.cwd(),
+          directoryAccess,
+          status: 'queued',
+          createdAt: new Date().toISOString()
+        };
+
+        // Check queue limit
+        if (this.queue.length >= IMAGE_CONFIG.QUEUE_LIMIT) {
+          return {
+            success: false,
+            error: `Queue limit reached (${IMAGE_CONFIG.QUEUE_LIMIT} images). Please wait for current jobs to complete.`,
+            queueLength: this.queue.length
+          };
+        }
+
+        this.queue.push(job);
+        jobIds.push(jobId);
+
+        this.logger?.info(`Image generation job queued: ${jobId}`, {
+          prompt: imageParams.prompt.substring(0, 50) + '...',
+          queuePosition: this.queue.length
+        });
+      }
+
+      // Start processing if not already running
+      if (!this.isProcessing) {
+        this._processQueue().catch(err => {
+          this.logger?.error('Queue processing error:', err);
+        });
+      }
+
+      // Return immediate response
+      return {
+        success: true,
+        jobIds,
+        queueLength: this.queue.length,
+        message: params.batch
+          ? `${jobIds.length} images queued for generation`
+          : 'Image queued for generation',
+        estimatedWaitTime: this._estimateWaitTime()
+      };
+
+    } catch (error) {
+      this.logger?.error('Image generation error:', error);
+      return {
+        success: false,
+        error: error.message
+      };
+    }
+  }
+
+  /**
+   * Validate parameters
+   * @private
+   */
+  _validateParameters(params) {
+    if (!params.images || params.images.length === 0) {
+      throw new Error('No images specified');
+    }
+
+    for (const img of params.images) {
+      if (!img.prompt || img.prompt.trim().length === 0) {
+        throw new Error('Image prompt is required');
+      }
+
+      if (img.prompt.length > IMAGE_CONFIG.MAX_PROMPT_LENGTH) {
+        throw new Error(`Prompt too long (max ${IMAGE_CONFIG.MAX_PROMPT_LENGTH} characters)`);
+      }
+
+      if (img.size) {
+        // Check for preset names first
+        if (IMAGE_CONFIG.SIZE_PRESETS[img.size]) {
+          img.size = IMAGE_CONFIG.SIZE_PRESETS[img.size];
+        }
+
+        // Validate WxH format
+        const sizeMatch = img.size.match(/^(\d+)x(\d+)$/);
+        if (!sizeMatch) {
+          throw new Error(`Invalid size format: ${img.size}. Use WIDTHxHEIGHT (e.g., 1024x768) or preset: ${Object.keys(IMAGE_CONFIG.SIZE_PRESETS).join(', ')}`);
+        }
+
+        const width = parseInt(sizeMatch[1], 10);
+        const height = parseInt(sizeMatch[2], 10);
+
+        // Validate constraints
+        const { SIZE_MIN, SIZE_MAX, SIZE_INCREMENT } = IMAGE_CONFIG;
+
+        if (width < SIZE_MIN || width > SIZE_MAX) {
+          throw new Error(`Width ${width} out of range. Must be ${SIZE_MIN}-${SIZE_MAX}px.`);
+        }
+        if (height < SIZE_MIN || height > SIZE_MAX) {
+          throw new Error(`Height ${height} out of range. Must be ${SIZE_MIN}-${SIZE_MAX}px.`);
+        }
+        if (width % SIZE_INCREMENT !== 0) {
+          throw new Error(`Width ${width} must be a multiple of ${SIZE_INCREMENT}.`);
+        }
+        if (height % SIZE_INCREMENT !== 0) {
+          throw new Error(`Height ${height} must be a multiple of ${SIZE_INCREMENT}.`);
+        }
+      }
+
+      if (img.outputPath) {
+        const ext = path.extname(img.outputPath).toLowerCase().replace('.', '');
+        if (ext && !IMAGE_CONFIG.VALID_FORMATS.includes(ext)) {
+          throw new Error(`Invalid format: ${ext}. Valid formats: ${IMAGE_CONFIG.VALID_FORMATS.join(', ')}`);
+        }
+      }
+    }
+  }
+
+  /**
+   * Process the image generation queue
+   * @private
+   */
+  async _processQueue() {
+    if (this.isProcessing) {
+      return;
+    }
+
+    this.isProcessing = true;
+
+    while (this.queue.length > 0) {
+      const job = this.queue.shift();
+      this.currentJob = job;
+
+      this.logger?.info(`Processing image generation job: ${job.jobId}`);
+
+      try {
+        job.status = 'processing';
+
+        // Generate the image
+        const result = await this._generateImage(job);
+
+        job.status = 'completed';
+        job.result = result;
+        job.completedAt = new Date().toISOString();
+
+        // Store completed job
+        this.completedJobs.set(job.jobId, job);
+
+        // Broadcast result via WebSocket
+        if (global.loxiaWebServer && job.sessionId) {
+          // Determine which URL to use: local saved file or temporary AI URL
+          let imageUrl;
+          let isTemporary = false;
+
+          if (result.savedToDisk && result.resolvedOutputPath) {
+            // Image was saved successfully - use our server endpoint
+            imageUrl = this._convertToWebUrl(result.resolvedOutputPath, job.sessionId);
+          } else if (result.temporaryUrl) {
+            // Download failed - use temporary AI-generated URL (expires in ~1 hour)
+            imageUrl = result.temporaryUrl;
+            isTemporary = true;
+          }
+
+          global.loxiaWebServer.broadcastToSession(job.sessionId, {
+            type: 'imageGenerated',
+            agentId: job.agentId,
+            jobId: job.jobId,
+            imageUrl,
+            localPath: result.resolvedOutputPath,
+            prompt: job.prompt,
+            success: true,
+            isTemporary, // Indicates if URL will expire
+            savedToDisk: result.savedToDisk,
+            downloadError: result.downloadError, // Include error if save failed
+            timestamp: job.completedAt
+          });
+
+          this.logger?.info('Image generation broadcast sent', {
+            jobId: job.jobId,
+            imageUrl,
+            localPath: result.resolvedOutputPath,
+            savedToDisk: result.savedToDisk,
+            isTemporary
+          });
+
+          // Save image result to conversation history for persistence
+          if (this.agentPool && job.agentId) {
+            try {
+              const agent = await this.agentPool.getAgent(job.agentId);
+              if (agent) {
+                // Build message content with warnings if applicable
+                let content = `Image generated: ${job.prompt}`;
+
+                if (isTemporary) {
+                  content += '\n\n⚠️ **Warning:** Image is using a temporary URL (expires in ~1 hour). Failed to save to disk.';
+                  if (result.downloadError) {
+                    content += `\n**Error:** ${result.downloadError}`;
+                  }
+                }
+
+                // Create image message for conversation history
+                const imageMessage = {
+                  id: `img-result-${job.jobId}`,
+                  role: 'assistant',
+                  content,
+                  timestamp: job.completedAt,
+                  imageUrl, // CRITICAL: Include imageUrl so it persists across page refreshes
+                  type: 'image-result',
+                  toolId: 'image-gen',
+                  status: 'completed',
+                  isTemporary: isTemporary || false,
+                  savedToDisk: result.savedToDisk !== false
+                };
+
+                // Add to full conversation
+                agent.conversations.full.messages.push(imageMessage);
+                agent.conversations.full.lastUpdated = job.completedAt;
+
+                // Add to current model conversation if exists
+                if (agent.currentModel && agent.conversations[agent.currentModel]) {
+                  agent.conversations[agent.currentModel].messages.push(imageMessage);
+                  agent.conversations[agent.currentModel].lastUpdated = job.completedAt;
+                }
+
+                // Update agent activity
+                agent.lastActivity = job.completedAt;
+
+                // Persist agent state to save conversation history
+                await this.agentPool.persistAgentState(job.agentId);
+
+                this.logger?.info('Image result saved to conversation history', {
+                  agentId: job.agentId,
+                  jobId: job.jobId,
+                  messageId: imageMessage.id
+                });
+
+                // Queue tool result so agent "sees" the completion and can continue
+                await this.agentPool.addToolResult(job.agentId, {
+                  toolId: 'image-gen',
+                  status: 'completed',
+                  result: {
+                    jobId: job.jobId,
+                    prompt: job.prompt,
+                    imageUrl,
+                    localPath: result.resolvedOutputPath,
+                    savedToDisk: result.savedToDisk,
+                    isTemporary
+                  },
+                  timestamp: job.completedAt
+                });
+
+                this.logger?.info('Image result queued for agent processing', {
+                  agentId: job.agentId,
+                  jobId: job.jobId
+                });
+              }
+            } catch (error) {
+              this.logger?.error('Failed to save image result to conversation history', {
+                error: error.message,
+                agentId: job.agentId,
+                jobId: job.jobId
+              });
+            }
+          }
+        }
+
+        this.logger?.info(`Image generation completed: ${job.jobId}`, {
+          outputPath: result.resolvedOutputPath
+        });
+
+      } catch (error) {
+        this.logger?.error(`Image generation failed: ${job.jobId}`, error);
+
+        job.status = 'failed';
+        job.error = error.message;
+        job.completedAt = new Date().toISOString();
+
+        this.completedJobs.set(job.jobId, job);
+
+        // Broadcast error to specific session
+        if (global.loxiaWebServer && job.sessionId) {
+          global.loxiaWebServer.broadcastToSession(job.sessionId, {
+            type: 'imageGenerated',
+            jobId: job.jobId,
+            agentId: job.agentId,
+            prompt: job.prompt,
+            success: false,
+            error: error.message,
+            timestamp: job.completedAt
+          });
+
+          this.logger?.info('Image generation error broadcast sent', {
+            jobId: job.jobId,
+            sessionId: job.sessionId,
+            error: error.message
+          });
+        }
+
+        // Save error message to conversation history
+        if (this.agentPool && job.agentId) {
+          try {
+            const agent = await this.agentPool.getAgent(job.agentId);
+            if (agent) {
+              // Create error message for conversation history
+              const errorMessage = {
+                id: `img-error-${job.jobId}`,
+                role: 'system',
+                content: `❌ Image generation failed: ${error.message}\n\n**Prompt:** ${job.prompt}`,
+                timestamp: job.completedAt,
+                type: 'error',
+                toolId: 'image-gen',
+                status: 'failed',
+                jobId: job.jobId
+              };
+
+              // Add to full conversation
+              agent.conversations.full.messages.push(errorMessage);
+              agent.conversations.full.lastUpdated = job.completedAt;
+
+              // Add to current model conversation if exists
+              if (agent.currentModel && agent.conversations[agent.currentModel]) {
+                agent.conversations[agent.currentModel].messages.push(errorMessage);
+                agent.conversations[agent.currentModel].lastUpdated = job.completedAt;
+              }
+
+              // Update agent activity
+              agent.lastActivity = job.completedAt;
+
+              // Persist agent state to save conversation history
+              await this.agentPool.persistAgentState(job.agentId);
+
+              this.logger?.info('Image error saved to conversation history', {
+                agentId: job.agentId,
+                jobId: job.jobId,
+                error: error.message
+              });
+
+              // Queue tool result so agent "sees" the failure and can handle it
+              await this.agentPool.addToolResult(job.agentId, {
+                toolId: 'image-gen',
+                status: 'failed',
+                error: error.message,
+                result: {
+                  jobId: job.jobId,
+                  prompt: job.prompt
+                },
+                timestamp: job.completedAt
+              });
+
+              this.logger?.info('Image error queued for agent processing', {
+                agentId: job.agentId,
+                jobId: job.jobId
+              });
+            }
+          } catch (historyError) {
+            this.logger?.error('Failed to save image error to conversation history', {
+              error: historyError.message,
+              agentId: job.agentId,
+              jobId: job.jobId
+            });
+          }
+        }
+      }
+    }
+
+    this.isProcessing = false;
+    this.currentJob = null;
+  }
+
+  /**
+   * Generate a single image
+   * @private
+   */
+  async _generateImage(job) {
+    // Check if AI service is available
+    if (!this.aiService) {
+      throw new Error('AI service not available. Image generation requires AI service.');
+    }
+
+    // Auto-select gpt-image-1.5 for transparency or editing
+    if (job.transparency && !job.model) {
+      job.model = 'gpt-image-1.5';
+    }
+    if (job.sourceImage && !job.model) {
+      job.model = 'gpt-image-1.5';
+    }
+
+    // Resolve output path
+    const resolvedOutputPath = await this._resolveOutputPath(job);
+
+    // Ensure directory exists
+    const outputDir = path.dirname(resolvedOutputPath);
+    await fs.mkdir(outputDir, { recursive: true });
+
+    let aiResult;
+
+    // Edit mode: source image provided
+    if (job.sourceImage) {
+      this.logger?.info(`Editing image with ${job.model}`, {
+        sourceImage: job.sourceImage,
+        hasMask: !!job.mask
+      });
+
+      // Resolve source image path relative to project directory
+      const projectDir = job.projectDir || process.cwd();
+      const resolvedSourcePath = path.isAbsolute(job.sourceImage)
+        ? job.sourceImage
+        : path.resolve(projectDir, job.sourceImage);
+
+      // Read source image and convert to base64
+      const imageBuffer = await fs.readFile(resolvedSourcePath);
+      const imageBase64 = imageBuffer.toString('base64');
+
+      // Read mask if provided
+      let maskBase64 = null;
+      if (job.mask) {
+        const resolvedMaskPath = path.isAbsolute(job.mask)
+          ? job.mask
+          : path.resolve(projectDir, job.mask);
+        const maskBuffer = await fs.readFile(resolvedMaskPath);
+        maskBase64 = maskBuffer.toString('base64');
+      }
+
+      aiResult = await this.aiService.editImage(job.prompt, imageBase64, {
+        model: job.model,
+        maskBase64,
+        sessionId: job.sessionId
+      });
+    } else {
+      // Standard generation mode
+      this.logger?.info(`Generating image with ${job.model}`, {
+        size: job.size,
+        quality: job.quality,
+        transparency: job.transparency
+      });
+
+      const options = {
+        model: job.model,
+        size: job.size,
+        quality: job.quality,
+        responseFormat: 'url', // Prefer URL, but Flux/GPT-Image returns b64_json
+        sessionId: job.sessionId // CRITICAL: Pass sessionId for API key retrieval
+      };
+
+      aiResult = await this.aiService.generateImage(job.prompt, options);
+    }
+
+    // AIService returns: { url, b64_json, model, requestId, revisedPrompt }
+    // Flux API returns b64_json (base64 encoded image)
+    const imageUrl = aiResult?.url || aiResult?.imageUrl;
+    const b64Json = aiResult?.b64_json;
+
+    if (!imageUrl && !b64Json) {
+      throw new Error('No image data received from AI service (no URL or base64)');
+    }
+
+    // Try to save image to disk
+    let savedToDisk = false;
+    let downloadError = null;
+    let displayUrl = imageUrl; // URL for web display
+
+    try {
+      if (b64Json) {
+        // Flux response: Save base64 directly to disk
+        this.logger?.info('Saving base64 image directly to disk (Flux response)');
+        const imageBuffer = Buffer.from(b64Json, 'base64');
+        await fs.writeFile(resolvedOutputPath, imageBuffer);
+        savedToDisk = true;
+
+        // For web display, we'll use our local server endpoint (set below)
+        displayUrl = null; // Will be converted to web URL later
+      } else if (imageUrl) {
+        // URL response: Download from URL
+        this.logger?.info(`Downloading image from URL: ${imageUrl.substring(0, 50)}...`);
+        await this._downloadImage(imageUrl, resolvedOutputPath);
+        savedToDisk = true;
+        displayUrl = imageUrl;
+      }
+
+      // Schedule cleanup if temp file
+      if (savedToDisk && !job.saveToProject) {
+        this._scheduleCleanup(resolvedOutputPath, job.jobId);
+      }
+    } catch (error) {
+      // Save failed, but we might still have a temporary URL
+      downloadError = error.message;
+      this.logger?.warn(`Failed to save image to disk: ${error.message}`);
+
+      if (!imageUrl) {
+        // No URL fallback for Flux - this is a real failure
+        throw new Error(`Failed to save image: ${error.message}`);
+      }
+    }
+
+    return {
+      jobId: job.jobId,
+      prompt: job.prompt,
+      outputPath: job.outputPath,
+      resolvedOutputPath: savedToDisk ? resolvedOutputPath : null,
+      temporaryUrl: displayUrl, // AI-generated URL (valid for ~1 hour) or null for Flux
+      savedToDisk,
+      downloadError,
+      success: true, // Image was generated successfully
+      model: aiResult.model || job.model,
+      size: job.size,
+      usage: aiResult.usage,
+      isBase64Response: !!b64Json // Flag to indicate Flux response
+    };
+  }
+
+  /**
+   * Resolve output path (temp or project directory)
+   * @private
+   */
+  async _resolveOutputPath(job) {
+    if (job.saveToProject) {
+      // Save to project directory
+      const projectDir = job.projectDir || process.cwd();
+
+      let outputPath = job.outputPath;
+      if (!outputPath) {
+        // Auto-generate filename
+        const timestamp = Date.now();
+        outputPath = `images/generated-${timestamp}.png`;
+      }
+
+      const resolvedPath = path.isAbsolute(outputPath)
+        ? path.normalize(outputPath)
+        : path.normalize(path.join(projectDir, outputPath));
+
+      // Security: Check for path traversal
+      if (!resolvedPath.startsWith(path.normalize(projectDir))) {
+        throw new Error('Path traversal detected');
+      }
+
+      // Check directory access if provided
+      if (job.directoryAccess) {
+        // Simple check - file must be within allowed directories
+        // Full implementation would use DirectoryAccessManager
+        const relativePath = path.relative(projectDir, resolvedPath);
+        if (relativePath.startsWith('..')) {
+          throw new Error('Access denied: path outside project directory');
+        }
+      }
+
+      return resolvedPath;
+    } else {
+      // Save to temp directory
+      await fs.mkdir(this.tempDir, { recursive: true });
+
+      let filename = job.outputPath
+        ? path.basename(job.outputPath)
+        : `generated-${job.jobId}.png`;
+
+      return path.join(this.tempDir, filename);
+    }
+  }
+
+  /**
+   * Download image from URL
+   * @private
+   */
+  async _downloadImage(imageUrl, outputPath) {
+    try {
+      const response = await fetch(imageUrl, {
+        signal: AbortSignal.timeout(IMAGE_CONFIG.DOWNLOAD_TIMEOUT)
+      });
+
+      if (!response.ok) {
+        throw new Error(`Failed to download image: HTTP ${response.status}`);
+      }
+
+      const buffer = Buffer.from(await response.arrayBuffer());
+      await fs.writeFile(outputPath, buffer);
+
+      this.logger?.info(`Image saved to: ${outputPath}`);
+
+    } catch (error) {
+      if (error.name === 'TimeoutError') {
+        throw new Error('Image download timeout');
+      } else if (error.name === 'TypeError') {
+        throw new Error(`Network error: ${error.message}`);
+      } else {
+        throw new Error(`Download failed: ${error.message}`);
+      }
+    }
+  }
+
+  /**
+   * Schedule cleanup of temp file
+   * @private
+   */
+  _scheduleCleanup(filePath, jobId) {
+    const timer = setTimeout(async () => {
+      try {
+        await fs.unlink(filePath);
+        this.logger?.debug(`Cleaned up temp image: ${filePath}`);
+        this.cleanupTimers.delete(jobId);
+      } catch (error) {
+        // File might already be deleted, ignore
+      }
+    }, IMAGE_CONFIG.TEMP_CLEANUP_MS);
+
+    this.cleanupTimers.set(jobId, timer);
+  }
+
+  /**
+   * Convert local file path to web-accessible URL
+   * @private
+   */
+  _convertToWebUrl(localPath, sessionId) {
+    // Extract just the filename from the path
+    const filename = path.basename(localPath);
+
+    // Construct web URL using the image serving endpoint
+    // Assumes web server runs on port 8080 (can be made configurable)
+    const port = global.loxiaWebServer?.port || 8080;
+    let host = global.loxiaWebServer?.host || 'localhost';
+
+    // Convert 0.0.0.0 (server binding address) to localhost (browser-accessible)
+    // Browsers cannot connect to 0.0.0.0, even though servers can bind to it
+    if (host === '0.0.0.0') {
+      host = 'localhost';
+    }
+
+    return `http://${host}:${port}/api/images/${sessionId}/${filename}`;
+  }
+
+  /**
+   * Estimate wait time based on queue
+   * @private
+   */
+  _estimateWaitTime() {
+    const avgGenerationTime = 30; // seconds
+    const queuePosition = this.queue.length;
+
+    if (queuePosition === 0) {
+      return '~30 seconds';
+    }
+
+    const estimatedSeconds = queuePosition * avgGenerationTime;
+    const minutes = Math.floor(estimatedSeconds / 60);
+    const seconds = estimatedSeconds % 60;
+
+    if (minutes > 0) {
+      return `~${minutes}m ${seconds}s`;
+    }
+    return `~${seconds}s`;
+  }
+
+  /**
+   * Generate unique job ID
+   * @private
+   */
+  _generateJobId() {
+    return `img-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+  }
+
+  /**
+   * Get job status
+   * @param {string} jobId - Job ID
+   * @returns {Object} Job status
+   */
+  getJobStatus(jobId) {
+    // Check completed jobs
+    if (this.completedJobs.has(jobId)) {
+      return this.completedJobs.get(jobId);
+    }
+
+    // Check current job
+    if (this.currentJob && this.currentJob.jobId === jobId) {
+      return this.currentJob;
+    }
+
+    // Check queue
+    const queuedJob = this.queue.find(job => job.jobId === jobId);
+    if (queuedJob) {
+      return queuedJob;
+    }
+
+    return {
+      jobId,
+      status: 'not_found'
+    };
+  }
+
+  /**
+   * Cleanup on shutdown
+   */
+  async cleanup() {
+    this.logger?.info('Shutting down ImageTool');
+
+    // Clear all cleanup timers
+    for (const timer of this.cleanupTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.cleanupTimers.clear();
+
+    // Mark queued jobs as cancelled
+    for (const job of this.queue) {
+      job.status = 'cancelled';
+    }
+    this.queue = [];
+  }
+}
+
+export default ImageTool;