onbuzz 5.1.0 → 5.4.0

package/src/tools/__tests__/imageTool.coverage.test.js

@@ -0,0 +1,512 @@
+/**
+ * Full-coverage tests for imageTool.js — the async queue-processing,
+ * persistence, broadcast, file/URL plumbing, and helper surface that the
+ * focused validator/edit suites don't reach.
+ *
+ * fs, the gallery service, and imageFormat are mocked so the save/transcode
+ * paths are deterministic and never touch disk or sharp. The WebSocket server
+ * (global.loxiaWebServer) and agentPool are fakes whose calls we assert.
+ */
+import { jest, describe, test, expect, beforeEach, afterEach } from '@jest/globals';
+import path from 'path';
+
+const fsp = {
+  readFile: jest.fn(),
+  writeFile: jest.fn(),
+  mkdir: jest.fn(),
+  stat: jest.fn(),
+  unlink: jest.fn(),
+};
+jest.unstable_mockModule('fs', () => ({ promises: fsp }));
+
+const saveImage = jest.fn().mockResolvedValue(undefined);
+jest.unstable_mockModule('../../services/galleryService.js', () => ({
+  getGalleryService: () => ({ saveImage }),
+}));
+
+// Deterministic format helpers (no sharp).
+jest.unstable_mockModule('../imageFormat.js', () => ({
+  resolveTargetFormat: jest.fn(() => ({ format: 'webp' })),
+  transcodeIfNeeded: jest.fn(async (buf) => ({ buffer: buf, transcoded: false, inputFormat: 'png', outputFormat: 'webp' })),
+  extensionFor: jest.fn(() => 'webp'),
+  ensureExtension: jest.fn((p) => (p.endsWith('.webp') ? p : `${p}.webp`)),
+  DEFAULT_FORMAT: 'webp',
+}));
+
+const { ImageTool } = await import('../imageTool.js');
+const imgFmt = await import('../imageFormat.js'); // mocked — for per-test transcode overrides
+
+const logger = { info() {}, warn() {}, error() {}, debug() {} };
+
+function makeTool() {
+  const tool = new ImageTool({}, logger);
+  tool.aiService = {
+    generateImage: jest.fn().mockResolvedValue({ b64_json: Buffer.from('img').toString('base64'), model: 'flux' }),
+    editImage: jest.fn().mockResolvedValue({ b64_json: Buffer.from('img').toString('base64'), model: 'gpt-image-1.5' }),
+  };
+  return tool;
+}
+
+function fakeAgent() {
+  return {
+    name: 'Agent', currentModel: null, lastActivity: null,
+    conversations: { full: { messages: [], lastUpdated: null } },
+  };
+}
+function fakeAgentPool() {
+  return {
+    getAgent: jest.fn().mockResolvedValue(fakeAgent()),
+    persistAgentState: jest.fn().mockResolvedValue(undefined),
+    addToolResult: jest.fn().mockResolvedValue(undefined),
+  };
+}
+
+let origWebServer;
+beforeEach(() => {
+  jest.clearAllMocks();
+  fsp.readFile.mockResolvedValue(Buffer.from('src'));
+  fsp.writeFile.mockResolvedValue(undefined);
+  fsp.mkdir.mockResolvedValue(undefined);
+  fsp.stat.mockResolvedValue({ size: 100 });
+  fsp.unlink.mockResolvedValue(undefined);
+  origWebServer = global.loxiaWebServer;
+  global.loxiaWebServer = { broadcastToSession: jest.fn(), port: 8080, host: 'localhost' };
+});
+afterEach(() => { global.loxiaWebServer = origWebServer; });
+
+// ───────────────────────── simple helpers ─────────────────────────
+
+describe('description + small helpers', () => {
+  test('getDescription returns the tool spec', () => {
+    expect(makeTool().getDescription()).toContain('image-gen');
+  });
+  test('setAIService / setAgentPool wire dependencies', () => {
+    const t = new ImageTool({}, logger);
+    const ai = {}; const ap = {};
+    t.setAIService(ai); t.setAgentPool(ap);
+    expect(t.aiService).toBe(ai);
+    expect(t.agentPool).toBe(ap);
+  });
+  test('_generateJobId is unique-ish and prefixed', () => {
+    const t = makeTool();
+    expect(t._generateJobId()).toMatch(/^img-/);
+  });
+  test('_estimateWaitTime across queue depths', () => {
+    const t = makeTool();
+    expect(t._estimateWaitTime()).toBe('~30 seconds');
+    t.queue = [1, 2];                       // 2 * 30 = 60s → "1m 0s"
+    expect(t._estimateWaitTime()).toMatch(/1m 0s/);
+    t.queue = [1];                          // 30s
+    expect(t._estimateWaitTime()).toMatch(/30s/);
+  });
+  test('_convertToWebUrl builds a server url and maps 0.0.0.0 → localhost', () => {
+    const t = makeTool();
+    expect(t._convertToWebUrl('/a/b/pic.webp', 'sess')).toBe('http://localhost:8080/api/images/sess/pic.webp');
+    global.loxiaWebServer.host = '0.0.0.0';
+    expect(t._convertToWebUrl('/a/b/pic.webp', 'sess')).toContain('localhost:8080');
+  });
+});
+
+describe('getJobStatus', () => {
+  test('returns completed, current, queued, or not_found', () => {
+    const t = makeTool();
+    expect(t.getJobStatus('x')).toEqual({ jobId: 'x', status: 'not_found' });
+    t.queue.push({ jobId: 'q', status: 'queued' });
+    expect(t.getJobStatus('q').status).toBe('queued');
+    t.currentJob = { jobId: 'c', status: 'processing' };
+    expect(t.getJobStatus('c').status).toBe('processing');
+    t.completedJobs.set('d', { jobId: 'd', status: 'completed' });
+    expect(t.getJobStatus('d').status).toBe('completed');
+  });
+});
+
+// ───────────────────────── _resolveOutputPath ─────────────────────────
+
+describe('_resolveOutputPath', () => {
+  test('project save with an explicit relative path', async () => {
+    const t = makeTool();
+    const job = { saveToProject: true, projectDir: process.cwd(), outputPath: 'images/pic' };
+    const p = await t._resolveOutputPath(job);
+    expect(p).toContain('images');
+    expect(job._targetFormat).toBe('webp');
+  });
+  test('project save with no path auto-generates a filename', async () => {
+    const t = makeTool();
+    const p = await t._resolveOutputPath({ saveToProject: true, projectDir: process.cwd() });
+    expect(p).toMatch(/generated-\d+\.webp$/);
+  });
+  test('rejects path traversal', async () => {
+    const t = makeTool();
+    const job = { saveToProject: true, projectDir: process.cwd(), outputPath: '../'.repeat(12) + 'evil' };
+    await expect(t._resolveOutputPath(job)).rejects.toThrow(/traversal/i);
+  });
+  test('with directoryAccess set, a valid in-project path is allowed', async () => {
+    const t = makeTool();
+    const job = { saveToProject: true, projectDir: process.cwd(), outputPath: 'images/ok', directoryAccess: {} };
+    await expect(t._resolveOutputPath(job)).resolves.toContain('images');
+  });
+  test('directoryAccess denies a sibling dir that shares a name prefix', async () => {
+    // The string-prefix traversal guard passes for `…/projXX` vs `…/proj`,
+    // but path.relative yields a `..` path → the directoryAccess check catches it.
+    const t = makeTool();
+    const base = process.cwd();
+    const job = {
+      saveToProject: true,
+      projectDir: path.join(base, 'proj'),
+      outputPath: path.join(base, 'projXX', 'evil.webp'),
+      directoryAccess: {},
+    };
+    await expect(t._resolveOutputPath(job)).rejects.toThrow(/Access denied/);
+  });
+  test('temp save (no project) with and without an output name', async () => {
+    const t = makeTool();
+    expect(await t._resolveOutputPath({ saveToProject: false, jobId: 'j1' })).toContain('generated-j1');
+    expect(await t._resolveOutputPath({ saveToProject: false, jobId: 'j2', outputPath: 'custom' })).toContain('custom');
+  });
+});
+
+// ───────────────────────── _downloadImage ─────────────────────────
+
+describe('_downloadImage', () => {
+  afterEach(() => { delete global.fetch; });
+
+  test('downloads and writes on a 2xx', async () => {
+    global.fetch = jest.fn().mockResolvedValue({ ok: true, arrayBuffer: async () => new Uint8Array([1, 2]).buffer });
+    await makeTool()._downloadImage('http://x/img.png', '/out.webp', 'webp');
+    expect(fsp.writeFile).toHaveBeenCalled();
+  });
+  test('throws on a non-2xx', async () => {
+    global.fetch = jest.fn().mockResolvedValue({ ok: false, status: 500 });
+    await expect(makeTool()._downloadImage('http://x', '/o', 'webp')).rejects.toThrow(/HTTP 500/);
+  });
+  test('maps a timeout error', async () => {
+    global.fetch = jest.fn().mockRejectedValue(Object.assign(new Error('to'), { name: 'TimeoutError' }));
+    await expect(makeTool()._downloadImage('http://x', '/o', 'webp')).rejects.toThrow(/timeout/i);
+  });
+  test('maps a network (TypeError)', async () => {
+    global.fetch = jest.fn().mockRejectedValue(Object.assign(new Error('net'), { name: 'TypeError' }));
+    await expect(makeTool()._downloadImage('http://x', '/o', 'webp')).rejects.toThrow(/Network error/);
+  });
+  test('maps a generic error', async () => {
+    global.fetch = jest.fn().mockRejectedValue(new Error('boom'));
+    await expect(makeTool()._downloadImage('http://x', '/o', 'webp')).rejects.toThrow(/Download failed/);
+  });
+});
+
+// ───────────────────────── cleanup / timers ─────────────────────────
+
+describe('cleanup + scheduled temp removal', () => {
+  beforeEach(() => jest.useFakeTimers());
+  afterEach(() => jest.useRealTimers());
+
+  test('_scheduleCleanup unlinks the temp file after the delay', async () => {
+    const t = makeTool();
+    t._scheduleCleanup('/tmp/x.webp', 'job1');
+    await jest.advanceTimersByTimeAsync(3600000);
+    expect(fsp.unlink).toHaveBeenCalledWith('/tmp/x.webp');
+  });
+  test('cleanup clears timers and cancels queued jobs', async () => {
+    const t = makeTool();
+    t._scheduleCleanup('/tmp/y.webp', 'job2');
+    t.queue.push({ jobId: 'q', status: 'queued' });
+    await t.cleanup();
+    expect(t.queue).toHaveLength(0);
+  });
+});
+
+// ───────────────────────── _generateImage save paths ─────────────────────────
+
+describe('_generateImage save paths', () => {
+  const job = (over = {}) => ({ jobId: 'g', prompt: 'p', saveToProject: true, projectDir: process.cwd(), model: 'flux', size: '1024x1024', ...over });
+
+  test('throws when no AI service', async () => {
+    const t = new ImageTool({}, logger); // aiService null
+    await expect(t._generateImage(job())).rejects.toThrow(/AI service not available/);
+  });
+  test('b64 success → savedToDisk + resolvedOutputPath', async () => {
+    const t = makeTool();
+    const res = await t._generateImage(job());
+    expect(res.savedToDisk).toBe(true);
+    expect(res.resolvedOutputPath).toBeTruthy();
+  });
+  test('b64 but empty file → savedToDisk false', async () => {
+    const t = makeTool();
+    fsp.stat.mockResolvedValueOnce({ size: 0 });
+    const res = await t._generateImage(job());
+    expect(res.savedToDisk).toBe(false);
+  });
+  test('URL response → downloads, savedToDisk true', async () => {
+    const t = makeTool();
+    t.aiService.generateImage.mockResolvedValueOnce({ url: 'http://x/img.png', model: 'flux' });
+    global.fetch = jest.fn().mockResolvedValue({ ok: true, arrayBuffer: async () => new Uint8Array([1]).buffer });
+    const res = await t._generateImage(job());
+    expect(res.savedToDisk).toBe(true);
+    delete global.fetch;
+  });
+  test('no url and no b64 → throws', async () => {
+    const t = makeTool();
+    t.aiService.generateImage.mockResolvedValueOnce({ model: 'flux' });
+    await expect(t._generateImage(job())).rejects.toThrow(/No image data/);
+  });
+  test('save failure WITH a url falls back (downloadError, no throw)', async () => {
+    const t = makeTool();
+    t.aiService.generateImage.mockResolvedValueOnce({ url: 'http://x/i.png', model: 'flux' });
+    global.fetch = jest.fn().mockResolvedValue({ ok: false, status: 503 }); // download throws inside save
+    const res = await t._generateImage(job());
+    expect(res.savedToDisk).toBe(false);
+    expect(res.downloadError).toBeTruthy();
+    delete global.fetch;
+  });
+  test('save failure with NO url (b64 write fails) → throws', async () => {
+    const t = makeTool();
+    fsp.writeFile.mockRejectedValueOnce(new Error('disk full'));
+    await expect(t._generateImage(job())).rejects.toThrow(/Failed to save image/);
+  });
+});
+
+// ───────────────────────── _processQueue ─────────────────────────
+
+describe('_processQueue', () => {
+  function queued(tool, over = {}) {
+    tool.queue.push({
+      jobId: 'j', sessionId: 'sess', agentId: 'a1', prompt: 'p',
+      saveToProject: true, projectDir: process.cwd(), model: 'flux', size: '1024x1024',
+      outputPath: 'images/out', status: 'queued', createdAt: 'now', ...over,
+    });
+  }
+
+  test('success → broadcasts, saves to gallery, records tool result', async () => {
+    const t = makeTool();
+    t.agentPool = fakeAgentPool();
+    queued(t);
+    await t._processQueue();
+    expect(global.loxiaWebServer.broadcastToSession).toHaveBeenCalledWith('sess', expect.objectContaining({ type: 'imageGenerated', success: true }));
+    expect(saveImage).toHaveBeenCalled();
+    expect(t.agentPool.addToolResult).toHaveBeenCalledWith('a1', expect.objectContaining({ status: 'completed' }));
+    expect(t.completedJobs.get('j').status).toBe('completed');
+  });
+
+  test('saveToGallery=false skips the gallery copy', async () => {
+    const t = makeTool();
+    t.agentPool = fakeAgentPool();
+    queued(t, { toolConfig: { saveToGallery: false } });
+    await t._processQueue();
+    expect(saveImage).not.toHaveBeenCalled();
+  });
+
+  test('temporary-url path (disk save failed but url present) broadcasts isTemporary', async () => {
+    const t = makeTool();
+    t.agentPool = fakeAgentPool();
+    // URL result + failing download → savedToDisk false, temporaryUrl set
+    t.aiService.generateImage.mockResolvedValueOnce({ url: 'http://x/i.png', model: 'flux' });
+    global.fetch = jest.fn().mockResolvedValue({ ok: false, status: 500 });
+    queued(t);
+    await t._processQueue();
+    expect(global.loxiaWebServer.broadcastToSession).toHaveBeenCalledWith('sess', expect.objectContaining({ isTemporary: true }));
+    delete global.fetch;
+  });
+
+  test('error path → broadcasts failure and records a failed tool result', async () => {
+    const t = makeTool();
+    t.agentPool = fakeAgentPool();
+    t.aiService.generateImage.mockRejectedValueOnce(new Error('content moderation blocked'));
+    queued(t);
+    await t._processQueue();
+    expect(t.completedJobs.get('j').status).toBe('failed');
+    expect(global.loxiaWebServer.broadcastToSession).toHaveBeenCalledWith('sess', expect.objectContaining({ success: false }));
+    expect(t.agentPool.addToolResult).toHaveBeenCalledWith('a1', expect.objectContaining({ status: 'failed' }));
+  });
+
+  test('runs without a web server / agentPool without throwing', async () => {
+    const t = makeTool();
+    global.loxiaWebServer = undefined;
+    queued(t, { sessionId: null });
+    await expect(t._processQueue()).resolves.toBeUndefined();
+  });
+});
+
+// ───────────────────────── execute() ─────────────────────────
+
+describe('execute', () => {
+  test('queues a single image and reports queue length', async () => {
+    const t = makeTool();
+    t._processQueue = jest.fn().mockResolvedValue(); // don't run
+    const res = await t.execute({ prompt: 'a cat' });
+    expect(res.success).toBe(true);
+    expect(res.jobIds).toHaveLength(1);
+  });
+
+  test('batch mode queues each image', async () => {
+    const t = makeTool();
+    t._processQueue = jest.fn().mockResolvedValue();
+    const res = await t.execute({ batch: [{ prompt: 'one' }, { prompt: 'two' }] });
+    expect(res.jobIds).toHaveLength(2);
+    expect(res.message).toMatch(/2 images queued/);
+  });
+
+  test('validation error → success:false', async () => {
+    const res = await makeTool().execute({ prompt: '' });
+    expect(res.success).toBe(false);
+    expect(res.error).toMatch(/prompt is required/i);
+  });
+
+  test('queue limit reached → success:false', async () => {
+    const t = makeTool();
+    t._processQueue = jest.fn().mockResolvedValue();
+    for (let i = 0; i < 10; i++) t.queue.push({ jobId: `x${i}` });
+    const res = await t.execute({ prompt: 'overflow' });
+    expect(res.success).toBe(false);
+    expect(res.error).toMatch(/Queue limit/);
+  });
+
+  test('parses an XML string input', async () => {
+    const t = makeTool();
+    t._processQueue = jest.fn().mockResolvedValue();
+    const res = await t.execute('<prompt>from xml</prompt>');
+    expect(res.success).toBe(true);
+    expect(t.queue[0].prompt).toBe('from xml');
+  });
+});
+
+// ───────────────────────── parser edge cases ─────────────────────────
+
+describe('parseParameters edge cases', () => {
+  test('XML batch with multiple <image> blocks', () => {
+    const t = makeTool();
+    const parsed = t.parseParameters('<batch><image><prompt>a</prompt></image><image><prompt>b</prompt></image></batch>');
+    expect(parsed.batch).toBe(true);
+    expect(parsed.images).toHaveLength(2);
+  });
+  test('invalid (non-string/object) input throws', () => {
+    expect(() => makeTool().parseParameters(42)).toThrow(/Invalid parameter format/);
+  });
+  test('empty XML (no image content) throws', () => {
+    expect(() => makeTool().parseParameters('<batch></batch>')).toThrow(/No valid image parameters/);
+  });
+  test('JSON string input is parsed', () => {
+    expect(makeTool().parseParameters('{"prompt":"x"}').images[0].prompt).toBe('x');
+  });
+  test('a {parameters:{…}} wrapper is unwrapped', () => {
+    expect(makeTool().parseParameters({ parameters: { prompt: 'wrapped' } }).images[0].prompt).toBe('wrapped');
+  });
+});
+
+// ───────────────────────── remaining branches ─────────────────────────
+
+describe('validator — Flux height rules', () => {
+  const bad = (size, re) => expect(() => makeTool()._validateParameters({ images: [{ prompt: 'p', model: 'flux-1.1-pro', size }] })).toThrow(re);
+  test('width out of range', () => bad('2048x1024', /Width 2048 out of range/));
+  test('height out of range', () => bad('1024x2048', /Height 2048 out of range/));
+  test('height not a multiple of 32', () => bad('1024x1000', /Height 1000 must be a multiple/));
+  test('unparseable size (not WxH, not a preset, not auto)', () => bad('garbage', /Invalid size format/));
+});
+
+describe('_processQueue / execute extra branches', () => {
+  test('re-entrancy guard: returns immediately when already processing', async () => {
+    const t = makeTool();
+    t.isProcessing = true;
+    await expect(t._processQueue()).resolves.toBeUndefined();
+  });
+
+  test('execute logs (does not throw) when the async queue rejects', async () => {
+    const t = makeTool();
+    t._processQueue = jest.fn().mockRejectedValue(new Error('queue boom'));
+    const res = await t.execute({ prompt: 'x' });
+    expect(res.success).toBe(true);
+    await new Promise((r) => setImmediate(r)); // let the .catch run
+  });
+
+  test('no image url available (disk save failed, no temp url) still broadcasts', async () => {
+    const t = makeTool();
+    t.agentPool = fakeAgentPool();
+    fsp.stat.mockResolvedValue({ size: 0 }); // b64 write produces empty file → savedToDisk false, no url
+    t.queue.push({ jobId: 'j', sessionId: 'sess', agentId: 'a1', prompt: 'p', saveToProject: true, projectDir: process.cwd(), model: 'flux', size: '1024x1024', outputPath: 'images/o', status: 'queued' });
+    await t._processQueue();
+    expect(global.loxiaWebServer.broadcastToSession).toHaveBeenCalledWith('sess', expect.objectContaining({ type: 'imageGenerated' }));
+  });
+
+  test('gallery save failure is non-fatal (warns, still completes)', async () => {
+    const t = makeTool();
+    t.agentPool = fakeAgentPool();
+    saveImage.mockRejectedValueOnce(new Error('gallery down'));
+    t.queue.push({ jobId: 'j', sessionId: 'sess', agentId: 'a1', prompt: 'p', saveToProject: true, projectDir: process.cwd(), model: 'flux', size: '1024x1024', outputPath: 'images/o', status: 'queued' });
+    await t._processQueue();
+    expect(t.completedJobs.get('j').status).toBe('completed');
+  });
+
+  test('history-save failure (getAgent throws) is caught on both success and error paths', async () => {
+    // success path
+    const t1 = makeTool();
+    t1.agentPool = { getAgent: jest.fn().mockRejectedValue(new Error('no agent')), persistAgentState: jest.fn(), addToolResult: jest.fn() };
+    t1.queue.push({ jobId: 'j', sessionId: 'sess', agentId: 'a1', prompt: 'p', saveToProject: true, projectDir: process.cwd(), model: 'flux', size: '1024x1024', outputPath: 'images/o', status: 'queued' });
+    await expect(t1._processQueue()).resolves.toBeUndefined();
+
+    // error path
+    const t2 = makeTool();
+    t2.aiService.generateImage.mockRejectedValueOnce(new Error('gen fail'));
+    t2.agentPool = { getAgent: jest.fn().mockRejectedValue(new Error('no agent')), persistAgentState: jest.fn(), addToolResult: jest.fn() };
+    t2.queue.push({ jobId: 'j2', sessionId: 'sess', agentId: 'a1', prompt: 'p', saveToProject: true, projectDir: process.cwd(), model: 'flux', size: '1024x1024', outputPath: 'images/o', status: 'queued' });
+    await expect(t2._processQueue()).resolves.toBeUndefined();
+  });
+
+  test('pushes into the current-model conversation when one is active (success + error)', async () => {
+    const agentWithModel = () => ({ name: 'A', currentModel: 'm', lastActivity: null, conversations: { full: { messages: [] }, m: { messages: [] } } });
+    const t = makeTool();
+    t.agentPool = { getAgent: jest.fn().mockResolvedValue(agentWithModel()), persistAgentState: jest.fn().mockResolvedValue(), addToolResult: jest.fn().mockResolvedValue() };
+    t.queue.push({ jobId: 'j', sessionId: 'sess', agentId: 'a1', prompt: 'p', saveToProject: true, projectDir: process.cwd(), model: 'flux', size: '1024x1024', outputPath: 'images/o', status: 'queued' });
+    await t._processQueue();
+
+    const t2 = makeTool();
+    t2.aiService.generateImage.mockRejectedValueOnce(new Error('boom'));
+    t2.agentPool = { getAgent: jest.fn().mockResolvedValue(agentWithModel()), persistAgentState: jest.fn().mockResolvedValue(), addToolResult: jest.fn().mockResolvedValue() };
+    t2.queue.push({ jobId: 'j2', sessionId: 'sess', agentId: 'a1', prompt: 'p', saveToProject: true, projectDir: process.cwd(), model: 'flux', size: '1024x1024', outputPath: 'images/o', status: 'queued' });
+    await t2._processQueue();
+    expect(t2.completedJobs.get('j2').status).toBe('failed');
+  });
+});
+
+describe('_generateImage extra branches', () => {
+  const projJob = (over = {}) => ({ jobId: 'g', prompt: 'p', saveToProject: true, projectDir: process.cwd(), size: '1024x1024', ...over });
+
+  test('transparency auto-selects gpt-image-1.5 when no model', async () => {
+    const t = makeTool();
+    const job = projJob({ transparency: true });
+    await t._generateImage(job);
+    expect(job.model).toBe('gpt-image-1.5');
+  });
+
+  test('a source image auto-selects gpt-image-1.5 and reads the mask', async () => {
+    const t = makeTool();
+    const job = projJob({ sourceImage: 'a.png', mask: 'm.png' });
+    await t._generateImage(job);
+    expect(job.model).toBe('gpt-image-1.5');
+    expect(t.aiService.editImage).toHaveBeenCalled();
+  });
+
+  test('logs a transcode on the b64 save path', async () => {
+    const t = makeTool();
+    imgFmt.transcodeIfNeeded.mockResolvedValueOnce({ buffer: Buffer.from('x'), transcoded: true, inputFormat: 'png', outputFormat: 'webp' });
+    const res = await t._generateImage(projJob());
+    expect(res.savedToDisk).toBe(true);
+  });
+
+  test('URL download: empty file is warned (savedToDisk false)', async () => {
+    const t = makeTool();
+    t.aiService.generateImage.mockResolvedValueOnce({ url: 'http://x/i.png', model: 'flux' });
+    global.fetch = jest.fn().mockResolvedValue({ ok: true, arrayBuffer: async () => new Uint8Array([1]).buffer });
+    fsp.stat.mockResolvedValueOnce({ size: 0 });
+    const res = await t._generateImage(projJob());
+    expect(res.savedToDisk).toBe(false);
+    delete global.fetch;
+  });
+});
+
+describe('_downloadImage transcode log', () => {
+  afterEach(() => { delete global.fetch; });
+  test('logs when the downloaded bytes are transcoded', async () => {
+    imgFmt.transcodeIfNeeded.mockResolvedValueOnce({ buffer: Buffer.from('x'), transcoded: true, inputFormat: 'png', outputFormat: 'webp' });
+    global.fetch = jest.fn().mockResolvedValue({ ok: true, arrayBuffer: async () => new Uint8Array([1]).buffer });
+    await makeTool()._downloadImage('http://x/i.png', '/o.webp', 'webp');
+    expect(fsp.writeFile).toHaveBeenCalled();
+  });
+});

package/src/tools/__tests__/imageTool.edit.test.js

@@ -0,0 +1,113 @@
+/**
+ * Edit-mode + multi-reference tests for imageTool.
+ *
+ * Covers:
+ *   - the latent bug fix: execute() now carries sourceImage / sourceImages /
+ *     mask / transparency onto the queued job (previously dropped, so edit
+ *     mode never triggered);
+ *   - resolveEffectiveImageModel auto-switching on sourceImages;
+ *   - parser support for sourceImages (JSON array + XML comma list);
+ *   - _generateImage reading every source and forwarding imagesBase64 to
+ *     aiService.editImage for multi-reference edits, while keeping the
+ *     single-image path (no imagesBase64) intact.
+ */
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+
+jest.unstable_mockModule('fs', () => ({
+  promises: {
+    readFile: jest.fn((p) => Promise.resolve(Buffer.from(`bytes:${p}`))),
+    writeFile: jest.fn().mockResolvedValue(undefined),
+    mkdir: jest.fn().mockResolvedValue(undefined),
+    stat: jest.fn().mockResolvedValue({ size: 42 }),
+    unlink: jest.fn().mockResolvedValue(undefined),
+  },
+}));
+
+const { ImageTool, resolveEffectiveImageModel } = await import('../imageTool.js');
+
+const logger = { info() {}, warn() {}, error() {}, debug() {} };
+function makeTool() {
+  const tool = new ImageTool({}, logger);
+  tool.aiService = {
+    editImage: jest.fn().mockResolvedValue({ b64_json: Buffer.from('out').toString('base64'), model: 'gpt-image-1.5' }),
+    generateImage: jest.fn().mockResolvedValue({ b64_json: Buffer.from('out').toString('base64'), model: 'flux' }),
+  };
+  return tool;
+}
+
+beforeEach(() => jest.clearAllMocks());
+
+describe('resolveEffectiveImageModel', () => {
+  test('auto-switches to gpt-image-1.5 when sourceImages is non-empty', () => {
+    expect(resolveEffectiveImageModel({ sourceImages: ['a.png', 'b.png'] })).toBe('gpt-image-1.5');
+  });
+  test('explicit model still wins over the sourceImages auto-switch', () => {
+    expect(resolveEffectiveImageModel({ model: 'gpt-image-2', sourceImages: ['a.png'] })).toBe('gpt-image-2');
+  });
+  test('empty sourceImages does not force a model', () => {
+    expect(resolveEffectiveImageModel({ sourceImages: [] })).toBe('');
+  });
+});
+
+describe('parser carries edit inputs', () => {
+  test('JSON: sourceImages array is parsed', () => {
+    const tool = makeTool();
+    const parsed = tool.parseParameters({ prompt: 'x', sourceImages: ['a.png', 'b.png', ''] });
+    expect(parsed.images[0].sourceImages).toEqual(['a.png', 'b.png']); // falsy filtered
+  });
+  test('XML: <source-images> comma list is parsed', () => {
+    const tool = makeTool();
+    const parsed = tool.parseParameters('<prompt>x</prompt><source-images>a.png, b.png</source-images>');
+    expect(parsed.images[0].sourceImages).toEqual(['a.png', 'b.png']);
+  });
+});
+
+describe('execute() carries edit fields onto the queued job (bug fix)', () => {
+  test('sourceImage / mask / transparency reach the job', async () => {
+    const tool = makeTool();
+    tool._processQueue = jest.fn(); // don't actually run generation
+    await tool.execute({ prompt: 'edit it', sourceImage: 'photo.png', mask: 'm.png', transparency: true });
+    expect(tool.queue).toHaveLength(1);
+    expect(tool.queue[0]).toMatchObject({ sourceImage: 'photo.png', mask: 'm.png', transparency: true });
+  });
+
+  test('sourceImages reaches the job', async () => {
+    const tool = makeTool();
+    tool._processQueue = jest.fn();
+    await tool.execute({ prompt: 'compose', sourceImages: ['a.png', 'b.png'] });
+    expect(tool.queue[0].sourceImages).toEqual(['a.png', 'b.png']);
+  });
+});
+
+describe('_generateImage edit dispatch', () => {
+  const baseJob = { jobId: 'j', prompt: 'compose', saveToProject: false, projectDir: '/proj', model: 'gpt-image-1.5' };
+
+  test('multiple sources → editImage receives the imagesBase64 array', async () => {
+    const tool = makeTool();
+    await tool._generateImage({ ...baseJob, sourceImages: ['a.png', 'b.png'] });
+
+    expect(tool.aiService.editImage).toHaveBeenCalledTimes(1);
+    const [prompt, firstImg, opts] = tool.aiService.editImage.mock.calls[0];
+    expect(prompt).toBe('compose');
+    expect(opts.imagesBase64).toHaveLength(2);
+    expect(firstImg).toBe(opts.imagesBase64[0]); // first positional = first of array
+    expect(tool.aiService.generateImage).not.toHaveBeenCalled();
+  });
+
+  test('single source → editImage receives no imagesBase64 (legacy single path)', async () => {
+    const tool = makeTool();
+    await tool._generateImage({ ...baseJob, sourceImage: 'only.png' });
+
+    expect(tool.aiService.editImage).toHaveBeenCalledTimes(1);
+    const [, firstImg, opts] = tool.aiService.editImage.mock.calls[0];
+    expect(opts.imagesBase64).toBeUndefined();
+    expect(typeof firstImg).toBe('string');
+  });
+
+  test('no source → standard generation path (no editImage)', async () => {
+    const tool = makeTool();
+    await tool._generateImage({ ...baseJob, model: 'flux-1.1-pro', size: '1024x1024' });
+    expect(tool.aiService.editImage).not.toHaveBeenCalled();
+    expect(tool.aiService.generateImage).toHaveBeenCalledTimes(1);
+  });
+});

package/src/tools/__tests__/imageTool.validator.test.js

@@ -80,6 +80,43 @@ describe('_validateParameters — gpt-image-1.5 explicit', () => {
   });
 });
 
+// ── gpt-image-2 (explicit) ──────────────────────────────────────────────
+
+describe('_validateParameters — gpt-image-2 explicit', () => {
+  test.each(['1024x1024', '1024x1536', '1536x1024', 'auto'])('accepts %s', (size) => {
+    expectValidates({ images: [{ prompt: 'cat', model: 'gpt-image-2', size }] });
+  });
+
+  test('rejects a Flux-shaped size with the gpt-image enum hint', () => {
+    expectRejects(
+      { images: [{ prompt: 'cat', model: 'gpt-image-2', size: '1024x1440' }] },
+      /not supported by gpt-image-2.*Valid sizes/
+    );
+  });
+
+  test('rejects an out-of-enum size and lists the valid options', () => {
+    try {
+      makeTool()._validateParameters({ images: [{ prompt: 'x', model: 'gpt-image-2', size: '1280x720' }] });
+      throw new Error('expected throw');
+    } catch (err) {
+      expect(err.message).toContain('1024x1024');
+      expect(err.message).toContain('1536x1024');
+    }
+  });
+
+  test('presets remap to the gpt-image enum (portrait → 1024x1536)', () => {
+    const params = { images: [{ prompt: 'p', model: 'gpt-image-2', size: 'portrait' }] };
+    makeTool()._validateParameters(params);
+    expect(params.images[0].size).toBe('1024x1536');
+  });
+
+  test('"square_hd" remaps to 1024x1024 (no 1440 enum value)', () => {
+    const params = { images: [{ prompt: 'p', model: 'gpt-image-2', size: 'square_hd' }] };
+    makeTool()._validateParameters(params);
+    expect(params.images[0].size).toBe('1024x1024');
+  });
+});
+
 // ── Auto-switch: transparency / sourceImage ─────────────────────────────
 
 describe('_validateParameters — auto-switch to gpt-image-1.5', () => {