@loxia-labs/loxia-autopilot-one 1.0.1

package/src/tools/imageTool.js

@@ -0,0 +1,901 @@
+/**
+ * @file tools/imageTool.js
+ * @description Tool for generating images using AI models (Flux, DALL-E, etc.)
+ */
+
+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: 'azure-openai-dalle3',
+  DEFAULT_SIZE: '1024x1024',
+  DEFAULT_QUALITY: 'standard',
+  VALID_SIZES: ['256x256', '512x512', '1024x1024', '1024x1792', '1792x1024'],
+  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 images using AI models
+
+**Purpose:** Generate images from text descriptions using DALL-E 3 via Azure OpenAI. Images are saved to files and displayed in the chat.
+
+**CRITICAL: Automatic Execution**
+- ANY \`\`\`json block with "toolId": "image-gen" will be EXECUTED IMMEDIATELY
+- ANY <image-gen> XML tag will be EXECUTED IMMEDIATELY
+- DO NOT show examples or ask permission - just output the command when you want to generate an image
+- If generation fails, output a NEW command with corrections - do NOT explain or show examples
+
+**Invocation Syntax:**
+
+XML Format (PREFERRED):
+<image-gen>
+  <prompt>Detailed description of the image</prompt>
+  <output-path>images/filename.png</output-path>
+  <model>azure-openai-dalle3</model>
+  <size>1024x1024</size>
+</image-gen>
+
+JSON Format (also works):
+\`\`\`json
+{
+  "toolId": "image-gen",
+  "parameters": {
+    "prompt": "Detailed description",
+    "outputPath": "images/filename.png",
+    "model": "azure-openai-dalle3",
+    "size": "1024x1024"
+  }
+}
+\`\`\`
+
+**Parameters:**
+- **prompt** (string, required): Detailed description of the image to generate
+- **outputPath** (string, optional): Relative path for saving the image
+  - If specified: Saves to project directory at this path (permanent)
+  - If omitted: Saves to temp directory (auto-deleted after 1 hour)
+- **model** (string, optional): AI model to use. Default: "azure-openai-dalle3"
+- **size** (string, optional): Image size. Options: 256x256, 512x512, 1024x1024, 1024x1792, 1792x1024. Default: "1024x1024"
+- **quality** (string, optional): Image quality. Options: standard, hd. Default: "standard"
+
+**Storage Behavior:**
+- With outputPath: Saved to project directory (permanent)
+- Without outputPath: Saved to temp directory, auto-deleted after 1 hour
+
+**Usage Instructions:**
+1. When user requests an image, output the <image-gen> tag IMMEDIATELY
+2. DO NOT ask for permission or show examples first
+3. DO NOT explain the format - just use it
+4. If it fails, retry with a corrected command (no explanations)
+5. Only generate ONE image at a time (no batch mode needed)
+
+**Correct Usage Pattern:**
+
+User: "create a sunset image"
+You: <image-gen>
+  <prompt>A beautiful sunset over the ocean with vibrant orange and pink colors reflecting on calm waters</prompt>
+  <output-path>images/sunset.png</output-path>
+</image-gen>
+
+**WRONG Usage Pattern (DO NOT DO THIS):**
+
+User: "create a sunset image"
+You: "I'll generate that image for you. Here's the command:
+\`\`\`xml
+<image-gen>...</image-gen>
+\`\`\`
+Do you want me to proceed?"
+← This is WRONG because the command already executed when you showed it!
+
+**Required Parameters:**
+- prompt: Detailed, descriptive text (be creative and specific)
+- model: Always use "azure-openai-dalle3"
+- size: Use "1024x1024" for square, "1024x1792" for portrait, "1792x1024" for landscape
+
+**Optional Parameters:**
+- output-path: Relative path like "images/filename.png" (omit for temp file)
+- quality: "standard" or "hd" (default: standard)
+
+**Important Notes:**
+- Images take 15-30 seconds to generate
+- You'll get immediate confirmation with a job ID
+- The image appears automatically when complete
+- Be descriptive in prompts for better results
+- Maximum ${IMAGE_CONFIG.QUEUE_LIMIT} images in queue at once`;
+  }
+
+  /**
+   * 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
+    };
+  }
+
+  /**
+   * 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
+    };
+  }
+
+  /**
+   * 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 string inputs (from TagParser)
+      if (typeof params === 'string') {
+        this.logger?.info('ImageTool: Auto-parsing string 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 && !IMAGE_CONFIG.VALID_SIZES.includes(img.size)) {
+        throw new Error(`Invalid size: ${img.size}. Valid sizes: ${IMAGE_CONFIG.VALID_SIZES.join(', ')}`);
+      }
+
+      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
+                });
+              }
+            } 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
+              });
+            }
+          } 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.');
+    }
+
+    // Resolve output path
+    const resolvedOutputPath = await this._resolveOutputPath(job);
+
+    // Ensure directory exists
+    const outputDir = path.dirname(resolvedOutputPath);
+    await fs.mkdir(outputDir, { recursive: true });
+
+    this.logger?.info(`Generating image with ${job.model}`, {
+      size: job.size,
+      quality: job.quality
+    });
+
+    // Call AI service to generate image
+    const options = {
+      model: job.model,
+      size: job.size,
+      quality: job.quality,
+      responseFormat: 'url', // Get URL to download
+      sessionId: job.sessionId // CRITICAL: Pass sessionId for API key retrieval
+    };
+
+    const aiResult = await this.aiService.generateImage(job.prompt, options);
+
+    // AIService returns: { url, b64_json, model, requestId, revisedPrompt }
+    // Handle both 'url' and 'imageUrl' response formats
+    const imageUrl = aiResult?.url || aiResult?.imageUrl;
+
+    if (!imageUrl) {
+      throw new Error('No image URL received from AI service');
+    }
+
+    this.logger?.info(`Image URL received: ${imageUrl.substring(0, 50)}...`);
+
+    // Try to download and save image
+    let savedToDisk = false;
+    let downloadError = null;
+
+    try {
+      await this._downloadImage(imageUrl, resolvedOutputPath);
+      savedToDisk = true;
+
+      // Schedule cleanup if temp file
+      if (!job.saveToProject) {
+        this._scheduleCleanup(resolvedOutputPath, job.jobId);
+      }
+    } catch (error) {
+      // Download failed, but we still have the temporary URL
+      downloadError = error.message;
+      this.logger?.warn(`Failed to save image to disk, will use temporary URL: ${error.message}`);
+    }
+
+    return {
+      jobId: job.jobId,
+      prompt: job.prompt,
+      outputPath: job.outputPath,
+      resolvedOutputPath: savedToDisk ? resolvedOutputPath : null,
+      temporaryUrl: imageUrl, // AI-generated URL (valid for ~1 hour)
+      savedToDisk,
+      downloadError,
+      success: true, // Image was generated successfully
+      model: aiResult.model || job.model,
+      size: job.size,
+      usage: aiResult.usage
+    };
+  }
+
+  /**
+   * 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;