onbuzz 4.2.0 → 4.4.0

package/src/services/__tests__/aiService.stream.test.js

@@ -281,7 +281,11 @@ describe('_parseSSEResponseStream — tool-call inline JSON passthrough', () =>
     // The backend converts native tool_calls to inline JSON blocks and
     // yields them as regular `chunk` events. Verify the CLI receives
     // them intact so its TagParser can extract.
-    const inlineBlock = '\n**Calling filesystem** — action: read…\n\n'
+    // Header only — see toolCallBridge.js DESIGN NOTE: the preamble
+    // is "**Calling X**" with no param preview, because the JSON block
+    // below is the single source of truth and duplicating its contents
+    // in a preview was bloating the context.
+    const inlineBlock = '\n**Calling filesystem**\n\n'
       + '```json\n'
       + '{\n  "toolId": "filesystem",\n  "parameters": {\n    "action": "read"\n  }\n}\n'
       + '```\n';

package/src/services/__tests__/channelFilter.test.js

@@ -108,7 +108,9 @@ describe('filterContentForExternalRelay()', () => {
   });
 
   test('CONTENT VERBATIM — "Calling X" bridge preamble preserved if wrapped', () => {
-    const txt = '**Calling terminal** — cmd: ls…\n\nsee below';
+    // Bridge emits header-only (no em-dash param preview — see
+    // toolCallBridge.js DESIGN NOTE).
+    const txt = '**Calling terminal**\n\nsee below';
     const { blocks } = filterContentForExternalRelay(`<external>${txt}</external>`);
     expect(blocks[0].text).toBe(txt);
   });
@@ -134,7 +136,7 @@ describe('filterContentForExternalRelay()', () => {
     // after the bridge has converted native tool calls to inline blocks.
     const content =
       "Thinking through this…\n\n" +
-      "**Calling taskmanager** — type: create, title: foo…\n\n" +
+      "**Calling taskmanager**\n\n" +
       "```json\n{\"toolId\":\"taskmanager\",\"parameters\":{\"actions\":[{\"type\":\"create\",\"title\":\"foo\"}]}}\n```\n\n" +
       "<external to=\"discord:#ops\">\n" +
       "Created a task for you: **foo**. I'll post back when it's done.\n" +

package/src/services/__tests__/channelRelay.integration.test.js

@@ -454,7 +454,7 @@ describe('Cross-service isolation: a single agent response splits across platfor
     // for either Responses API or Chat Completions after the bridge.
     const content =
       'Private reasoning the operator sees.\n' +
-      '**Calling taskmanager** — type: complete…\n' +
+      '**Calling taskmanager**\n' +
       '```json\n{"toolId":"taskmanager","parameters":{"actions":[{"type":"complete","taskId":"t-1"}]}}\n```\n\n' +
       '<external to="discord:#ops">\n' +
       '**Deploy finished.** 42 tests passed.\n' +

package/src/services/__tests__/galleryService.test.js

@@ -0,0 +1,225 @@
+/**
+ * Tests for GalleryService — the durable store for tool-generated
+ * images + videos with metadata sidecars.
+ *
+ * Locks:
+ *   - save copies file + writes a JSON sidecar
+ *   - filename gets a timestamp prefix to avoid collisions
+ *   - list returns entries newest-first with metadata from the sidecar
+ *   - list filters by agentId when supplied
+ *   - delete removes both the asset and its sidecar
+ *   - delete rejects path traversal + unsupported extensions
+ *   - saveImage on a non-image source returns null (no-op, non-fatal)
+ *   - IO failures on the gallery path don't crash the caller (warn + null)
+ */
+
+import { jest, describe, test, expect, beforeEach, afterEach } from '@jest/globals';
+import path from 'path';
+import os from 'os';
+import { promises as fs } from 'fs';
+
+// Point userDataDir to a tmp dir for the duration of the test.
+let tmpRoot;
+jest.unstable_mockModule('../../utilities/userDataDir.js', () => ({
+  getUserDataDir: () => tmpRoot,
+  getUserDataPaths: () => ({
+    base: tmpRoot,
+    state: path.join(tmpRoot, 'state'),
+    agents: path.join(tmpRoot, 'state', 'agents'),
+    settings: path.join(tmpRoot, 'settings'),
+    attachments: path.join(tmpRoot, 'attachments'),
+    logs: path.join(tmpRoot, 'logs'),
+    cache: path.join(tmpRoot, 'cache'),
+    operations: path.join(tmpRoot, 'state', 'operations'),
+    models: path.join(tmpRoot, 'state', 'models'),
+    runtime: path.join(tmpRoot, 'runtime'),
+    skills: path.join(tmpRoot, 'state', 'skills'),
+    gallery: path.join(tmpRoot, 'gallery'),
+    galleryImages: path.join(tmpRoot, 'gallery', 'images'),
+    galleryVideos: path.join(tmpRoot, 'gallery', 'videos'),
+  }),
+  ensureUserDataDirs: async () => {},
+}));
+
+const mod = await import('../galleryService.js');
+const { GalleryService, _resetGalleryServiceForTests, getGalleryService } = mod;
+
+const LOGGER = { info() {}, warn() {}, error() {}, debug() {} };
+
+beforeEach(async () => {
+  _resetGalleryServiceForTests();
+  tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'gallery-svc-'));
+});
+
+afterEach(async () => {
+  await fs.rm(tmpRoot, { recursive: true, force: true }).catch(() => {});
+});
+
+async function makeSourceImage(name = 'fox.png') {
+  const srcDir = path.join(tmpRoot, 'src');
+  await fs.mkdir(srcDir, { recursive: true });
+  const src = path.join(srcDir, name);
+  await fs.writeFile(src, 'PNG-DATA');
+  return src;
+}
+
+async function makeSourceVideo(name = 'dragon.mp4') {
+  const srcDir = path.join(tmpRoot, 'src');
+  await fs.mkdir(srcDir, { recursive: true });
+  const src = path.join(srcDir, name);
+  await fs.writeFile(src, 'MP4-DATA');
+  return src;
+}
+
+describe('GalleryService.saveImage', () => {
+  test('copies the file into gallery/images and writes a sidecar', async () => {
+    const svc = new GalleryService(LOGGER);
+    const src = await makeSourceImage('fox.png');
+    const result = await svc.saveImage({
+      sourcePath: src,
+      metadata: { prompt: 'a fox', model: 'dall-e-3', agentId: 'agent-1', agentName: 'Alice' },
+    });
+    expect(result).toBeTruthy();
+    expect(result.filename).toMatch(/_fox\.png$/);
+    const contents = await fs.readFile(result.path, 'utf8');
+    expect(contents).toBe('PNG-DATA');
+    const sidecar = JSON.parse(await fs.readFile(`${result.path}.json`, 'utf8'));
+    expect(sidecar.prompt).toBe('a fox');
+    expect(sidecar.model).toBe('dall-e-3');
+    expect(sidecar.agentId).toBe('agent-1');
+    expect(sidecar.kind).toBe('image');
+    expect(sidecar.createdAt).toBeTruthy();
+  });
+
+  test('returns null for a non-image source (no throw, no file)', async () => {
+    const svc = new GalleryService(LOGGER);
+    const txt = path.join(tmpRoot, 'src', 'notes.txt');
+    await fs.mkdir(path.dirname(txt), { recursive: true });
+    await fs.writeFile(txt, 'hi');
+    const r = await svc.saveImage({ sourcePath: txt });
+    expect(r).toBeNull();
+  });
+
+  test('returns null when the source path does not exist (warn, not crash)', async () => {
+    const svc = new GalleryService(LOGGER);
+    const r = await svc.saveImage({
+      sourcePath: path.join(tmpRoot, 'does-not-exist.png'),
+    });
+    expect(r).toBeNull();
+  });
+
+  test('two saves of the same basename do not collide', async () => {
+    const svc = new GalleryService(LOGGER);
+    const src = await makeSourceImage('boom.png');
+    const a = await svc.saveImage({ sourcePath: src });
+    // Enough wall-clock for the timestamp prefix to change.
+    await new Promise(r => setTimeout(r, 5));
+    const b = await svc.saveImage({ sourcePath: src });
+    expect(a.filename).not.toBe(b.filename);
+  });
+});
+
+describe('GalleryService.saveVideo', () => {
+  test('copies + writes sidecar with kind=video', async () => {
+    const svc = new GalleryService(LOGGER);
+    const src = await makeSourceVideo('dragon.mp4');
+    const result = await svc.saveVideo({
+      sourcePath: src,
+      metadata: { prompt: 'a dragon', duration: 5, variants: 1, agentId: 'agent-1' },
+    });
+    expect(result).toBeTruthy();
+    const sidecar = JSON.parse(await fs.readFile(`${result.path}.json`, 'utf8'));
+    expect(sidecar.kind).toBe('video');
+    expect(sidecar.duration).toBe(5);
+  });
+});
+
+describe('GalleryService.listImages', () => {
+  test('returns saved images with sidecar metadata, newest first', async () => {
+    const svc = new GalleryService(LOGGER);
+    const src = await makeSourceImage('a.png');
+    const a = await svc.saveImage({ sourcePath: src, metadata: { prompt: 'first', agentId: 'x' } });
+    await new Promise(r => setTimeout(r, 20));
+    const b = await svc.saveImage({ sourcePath: src, metadata: { prompt: 'second', agentId: 'x' } });
+
+    const list = await svc.listImages();
+    expect(list.map(i => i.filename)).toEqual([b.filename, a.filename]);
+    expect(list[0].prompt).toBe('second');
+    expect(list[0].kind).toBe('image');
+    expect(list[0].bytes).toBeGreaterThan(0);
+    expect(list[0].mtime).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+  });
+
+  test('filters by agentId', async () => {
+    const svc = new GalleryService(LOGGER);
+    const src = await makeSourceImage('a.png');
+    await svc.saveImage({ sourcePath: src, metadata: { agentId: 'agent-A' } });
+    await svc.saveImage({ sourcePath: src, metadata: { agentId: 'agent-B' } });
+
+    const onlyB = await svc.listImages({ agentId: 'agent-B' });
+    expect(onlyB).toHaveLength(1);
+    expect(onlyB[0].agentId).toBe('agent-B');
+  });
+
+  test('empty gallery → empty list', async () => {
+    const svc = new GalleryService(LOGGER);
+    const list = await svc.listImages();
+    expect(list).toEqual([]);
+  });
+
+  test('files without sidecars are still listed (best-effort)', async () => {
+    const svc = new GalleryService(LOGGER);
+    const dir = path.join(tmpRoot, 'gallery', 'images');
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, 'orphan.png'), 'x');
+    const list = await svc.listImages();
+    expect(list.map(i => i.filename)).toEqual(['orphan.png']);
+    expect(list[0].prompt).toBeUndefined();
+  });
+});
+
+describe('GalleryService.deleteImage', () => {
+  test('removes the image AND its sidecar', async () => {
+    const svc = new GalleryService(LOGGER);
+    const src = await makeSourceImage('gone.png');
+    const { filename, path: assetPath } = await svc.saveImage({ sourcePath: src });
+    await fs.access(assetPath);
+    await fs.access(`${assetPath}.json`);
+
+    const ok = await svc.deleteImage(filename);
+    expect(ok).toBe(true);
+    await expect(fs.access(assetPath)).rejects.toBeTruthy();
+    await expect(fs.access(`${assetPath}.json`)).rejects.toBeTruthy();
+  });
+
+  test('rejects path-traversal filenames', async () => {
+    const svc = new GalleryService(LOGGER);
+    await expect(svc.deleteImage('../secret')).rejects.toMatchObject({ code: 'INVALID_FILENAME' });
+  });
+
+  test('rejects unsupported extensions', async () => {
+    const svc = new GalleryService(LOGGER);
+    await expect(svc.deleteImage('secret.txt')).rejects.toMatchObject({ code: 'INVALID_EXT' });
+  });
+
+  test('returns false when the file is already gone (no throw)', async () => {
+    const svc = new GalleryService(LOGGER);
+    const r = await svc.deleteImage('ghost.png');
+    expect(r).toBe(false);
+  });
+});
+
+describe('getGalleryService singleton', () => {
+  test('returns the same instance across calls', () => {
+    const a = getGalleryService(LOGGER);
+    const b = getGalleryService(LOGGER);
+    expect(a).toBe(b);
+  });
+
+  test('_resetGalleryServiceForTests creates a fresh instance', () => {
+    const a = getGalleryService(LOGGER);
+    _resetGalleryServiceForTests();
+    const b = getGalleryService(LOGGER);
+    expect(a).not.toBe(b);
+  });
+});

package/src/services/__tests__/toolCallBridgeContract.test.js

@@ -33,11 +33,9 @@ import TagParser from '../../utilities/tagParser.js';
  */
 function bridgeOutput({ name, args }) {
   const params = args ? JSON.parse(args) : {};
-  const paramSummary = Object.entries(params)
-    .map(([k, v]) => `${k}: ${typeof v === 'string' ? v : JSON.stringify(v)}`)
-    .join(', ')
-    .slice(0, 120);
-  return `\n**Calling ${name}** — ${paramSummary || 'no params'}…\n\n` +
+  // Header only — see autopilot-backend/services/toolCallBridge.js
+  // DESIGN NOTE. No em-dash / param preview line.
+  return `\n**Calling ${name}**\n\n` +
     '```json\n' +
     JSON.stringify({ toolId: name, parameters: params }, null, 2) +
     '\n```\n';

package/src/services/galleryService.js

@@ -0,0 +1,257 @@
+/**
+ * @file services/galleryService.js
+ * @description Durable gallery for tool-generated media.
+ *
+ * Why this exists:
+ *   Before, the web-UI gallery listed files by scanning each agent's
+ *   `working-dir/images/` folder. That breaks the moment a file is
+ *   moved, an agent is deleted, or the agent's workingDirectory
+ *   changes — and there's nowhere to store the prompt/model metadata
+ *   that made the image in the first place. GalleryService gives each
+ *   generation a durable home at `{userDataDir}/gallery/{images|videos}/`
+ *   with a `.json` sidecar carrying the full metadata.
+ *
+ * Layout:
+ *   {userDataDir}/gallery/
+ *     images/
+ *       2026-04-22T12-34-56_fox.png           ← the asset
+ *       2026-04-22T12-34-56_fox.png.json      ← metadata sidecar
+ *     videos/
+ *       2026-04-22T12-34-56_dragon.mp4
+ *       2026-04-22T12-34-56_dragon.mp4.json
+ *
+ * Sidecar shape (whatever the caller passed to saveImage/saveVideo):
+ *   {
+ *     filename:        "2026-04-22T12-34-56_fox.png",
+ *     sourcePath:      "/original/path/images/fox.png",
+ *     agentId:         "agent-xyz",
+ *     agentName:       "Alice",
+ *     prompt:          "a fox on a skateboard",
+ *     model:           "dall-e-3",
+ *     size:            "1024x1024",      // or width/height
+ *     duration:        5,                 // video only
+ *     variants:        1,                 // video only
+ *     createdAt:       "2026-04-22T12:34:56.789Z",
+ *     bytes:           834221,
+ *   }
+ *
+ * Save-time naming guarantees:
+ *   - Timestamp prefix prevents collisions when two agents pick the
+ *     same filename.
+ *   - Original filename is retained after the prefix so users can still
+ *     recognise what they asked for.
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { getUserDataPaths, ensureUserDataDirs } from '../utilities/userDataDir.js';
+
+const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif']);
+const VIDEO_EXTS = new Set(['.mp4', '.webm', '.mov', '.gif']);
+
+function _ts() {
+  // Filesystem-safe ISO — replaces ':' (illegal on Windows) with '-'.
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+function _isImage(name) { return IMAGE_EXTS.has(path.extname(name).toLowerCase()); }
+function _isVideo(name) { return VIDEO_EXTS.has(path.extname(name).toLowerCase()); }
+
+async function _ensureDir(dir) {
+  await fs.mkdir(dir, { recursive: true });
+}
+
+/** Write `data` to `{target}.json` — pretty, atomic-ish (write + rename). */
+async function _writeSidecar(target, data) {
+  const json = JSON.stringify(data, null, 2);
+  const tmp = `${target}.json.tmp`;
+  await fs.writeFile(tmp, json, 'utf8');
+  await fs.rename(tmp, `${target}.json`);
+}
+
+async function _readSidecar(target) {
+  try {
+    const raw = await fs.readFile(`${target}.json`, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/** Best-effort: strip known internal keys before returning to callers. */
+function _sanitiseMeta(meta, file, stat, url) {
+  const out = { ...(meta || {}) };
+  out.filename = file;
+  out.bytes = stat.size;
+  out.mtime = stat.mtime.toISOString();
+  if (url) out.url = url;
+  return out;
+}
+
+class GalleryService {
+  constructor(logger = null) {
+    this.logger = logger;
+    this.paths = getUserDataPaths();
+  }
+
+  /**
+   * Copy a freshly-generated image into the durable gallery.
+   * @param {object} opts
+   * @param {string} opts.sourcePath  absolute path to source file
+   * @param {object} opts.metadata    free-form sidecar data
+   * @param {string} [opts.filenameHint] override the suggested filename
+   * @returns {Promise<{ filename: string, path: string } | null>}
+   *          null when sourcePath couldn't be read (non-fatal)
+   */
+  async saveImage({ sourcePath, metadata = {}, filenameHint } = {}) {
+    if (!sourcePath) return null;
+    if (!_isImage(filenameHint || sourcePath)) return null;
+    try {
+      await _ensureDir(this.paths.galleryImages);
+      const base = path.basename(filenameHint || sourcePath);
+      const final = `${_ts()}_${base}`;
+      const target = path.join(this.paths.galleryImages, final);
+      await fs.copyFile(sourcePath, target);
+      const stat = await fs.stat(target);
+      await _writeSidecar(target, {
+        ...metadata,
+        filename: final,
+        sourcePath,
+        bytes: stat.size,
+        createdAt: metadata.createdAt || new Date().toISOString(),
+        kind: 'image',
+      });
+      this.logger?.info?.('[Gallery] saved image', { final, sourcePath });
+      return { filename: final, path: target };
+    } catch (err) {
+      // Gallery save is non-fatal — the tool's primary save to the
+      // agent's working dir already succeeded.
+      this.logger?.warn?.('[Gallery] saveImage failed', { error: err.message, sourcePath });
+      return null;
+    }
+  }
+
+  /** Same shape as saveImage, but for videos. */
+  async saveVideo({ sourcePath, metadata = {}, filenameHint } = {}) {
+    if (!sourcePath) return null;
+    if (!_isVideo(filenameHint || sourcePath)) return null;
+    try {
+      await _ensureDir(this.paths.galleryVideos);
+      const base = path.basename(filenameHint || sourcePath);
+      const final = `${_ts()}_${base}`;
+      const target = path.join(this.paths.galleryVideos, final);
+      await fs.copyFile(sourcePath, target);
+      const stat = await fs.stat(target);
+      await _writeSidecar(target, {
+        ...metadata,
+        filename: final,
+        sourcePath,
+        bytes: stat.size,
+        createdAt: metadata.createdAt || new Date().toISOString(),
+        kind: 'video',
+      });
+      this.logger?.info?.('[Gallery] saved video', { final, sourcePath });
+      return { filename: final, path: target };
+    } catch (err) {
+      this.logger?.warn?.('[Gallery] saveVideo failed', { error: err.message, sourcePath });
+      return null;
+    }
+  }
+
+  /**
+   * List gallery images, newest first. Optional { agentId } filter.
+   * Returns rich entries populated from the sidecar where available.
+   */
+  async listImages({ agentId } = {}) {
+    return this._listDir(this.paths.galleryImages, _isImage, agentId, 'image');
+  }
+
+  /** Same for videos. */
+  async listVideos({ agentId } = {}) {
+    return this._listDir(this.paths.galleryVideos, _isVideo, agentId, 'video');
+  }
+
+  async _listDir(dir, extCheck, agentId, kind) {
+    let entries;
+    try {
+      entries = await fs.readdir(dir);
+    } catch {
+      return [];
+    }
+    const results = [];
+    for (const name of entries) {
+      if (!extCheck(name)) continue;
+      const abs = path.join(dir, name);
+      let stat;
+      try { stat = await fs.stat(abs); } catch { continue; }
+      if (!stat.isFile()) continue;
+      const meta = (await _readSidecar(abs)) || {};
+      if (agentId && meta.agentId && meta.agentId !== agentId) continue;
+      results.push(_sanitiseMeta({ ...meta, kind }, name, stat, /* url */ null));
+    }
+    // Sort newest-first. Use createdAt from sidecar when available (more
+    // precise than mtime, which can collide at ms resolution on fast
+    // filesystems). Filename fallback works because we embed a timestamp
+    // prefix at save time.
+    results.sort((a, b) => {
+      const ka = a.createdAt || a.filename || '';
+      const kb = b.createdAt || b.filename || '';
+      return kb.localeCompare(ka);
+    });
+    return results;
+  }
+
+  /** Delete a gallery image by filename (+ its sidecar). 404 → false. */
+  async deleteImage(filename) {
+    return this._deleteFile(this.paths.galleryImages, filename, _isImage);
+  }
+
+  /** Delete a gallery video by filename (+ its sidecar). */
+  async deleteVideo(filename) {
+    return this._deleteFile(this.paths.galleryVideos, filename, _isVideo);
+  }
+
+  async _deleteFile(dir, filename, extCheck) {
+    const normalized = path.basename(filename || '');
+    if (!normalized || normalized !== filename) {
+      throw Object.assign(new Error('Invalid filename'), { code: 'INVALID_FILENAME' });
+    }
+    if (!extCheck(normalized)) {
+      throw Object.assign(new Error('Unsupported extension'), { code: 'INVALID_EXT' });
+    }
+    const target = path.join(dir, normalized);
+    let existed = false;
+    try {
+      await fs.unlink(target);
+      existed = true;
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+    }
+    // Sidecar is best-effort — missing sidecar is fine.
+    await fs.unlink(`${target}.json`).catch(() => {});
+    return existed;
+  }
+
+  /** Diagnostic helper (used by tests). */
+  async _ensureStructure() {
+    await ensureUserDataDirs();
+    await _ensureDir(this.paths.galleryImages);
+    await _ensureDir(this.paths.galleryVideos);
+  }
+}
+
+/* Singleton. Tools and webServer routes share one instance. */
+let _instance = null;
+
+export function getGalleryService(logger = null) {
+  if (!_instance) _instance = new GalleryService(logger);
+  return _instance;
+}
+
+/** Test-only — reset module state. */
+export function _resetGalleryServiceForTests() {
+  _instance = null;
+}
+
+export default GalleryService;
+export { GalleryService };

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

@@ -0,0 +1,134 @@
+/**
+ * Regression tests for the per-model size validator in imageTool.
+ *
+ * Motivation: an agent hit "Width 1536 out of range" when requesting
+ * 1536x1024 on gpt-image-1.5 (where that size IS valid) — because the
+ * validator was hardcoded to Flux constraints and didn't know the
+ * effective model. It also rejected `size: "auto"` despite the docs
+ * saying it's valid, and failed to remap the `portrait` preset when
+ * the tool auto-switched to gpt-image-1.5 (transparency=true).
+ *
+ * These tests lock the fixed behaviour end-to-end:
+ *   - Valid gpt-image-1.5 sizes accepted.
+ *   - Flux out-of-range errors still fire for Flux.
+ *   - Errors name the model + list valid sizes + hint at recovery.
+ *   - The transparency/sourceImage auto-switch runs BEFORE validation.
+ *   - Presets remap per model.
+ *   - _translateImageError produces actionable text for moderation,
+ *     size, and auth errors.
+ */
+
+import { describe, test, expect } from '@jest/globals';
+import {
+  resolveEffectiveImageModel,
+  _getModelSizeRule,
+  _translateImageError,
+} from '../imageTool.js';
+
+// ── resolveEffectiveImageModel ──────────────────────────────────────────
+
+describe('resolveEffectiveImageModel', () => {
+  test('returns explicit model when set', () => {
+    expect(resolveEffectiveImageModel({ model: 'gpt-image-1.5' })).toBe('gpt-image-1.5');
+    expect(resolveEffectiveImageModel({ model: 'Flux-1.1-pro' })).toBe('flux-1.1-pro');
+  });
+
+  test('auto-switches to gpt-image-1.5 when transparency=true', () => {
+    expect(resolveEffectiveImageModel({ transparency: true })).toBe('gpt-image-1.5');
+  });
+
+  test('auto-switches to gpt-image-1.5 when sourceImage is provided', () => {
+    expect(resolveEffectiveImageModel({ sourceImage: '/tmp/x.png' })).toBe('gpt-image-1.5');
+  });
+
+  test('returns "" when nothing forces a model (downstream will resolve)', () => {
+    expect(resolveEffectiveImageModel({})).toBe('');
+  });
+
+  test('explicit "auto" is treated as "defer to downstream"', () => {
+    expect(resolveEffectiveImageModel({ model: 'auto' })).toBe('');
+  });
+});
+
+// ── _getModelSizeRule ───────────────────────────────────────────────────
+
+describe('_getModelSizeRule', () => {
+  test('gpt-image-1.5 gets the enum rule', () => {
+    const { rule } = _getModelSizeRule('gpt-image-1.5');
+    expect(rule.kind).toBe('enum');
+    expect(rule.values).toContain('1024x1024');
+    expect(rule.values).toContain('1024x1536');
+    expect(rule.values).toContain('1536x1024');
+    expect(rule.values).toContain('auto');
+  });
+
+  test('substring match — "gpt-image-1.5-preview" still picks enum', () => {
+    const { rule } = _getModelSizeRule('gpt-image-1.5-preview');
+    expect(rule.kind).toBe('enum');
+  });
+
+  test('flux variants get the range rule', () => {
+    const { rule } = _getModelSizeRule('flux-1.1-pro');
+    expect(rule.kind).toBe('range');
+    expect(rule.min).toBe(256);
+    expect(rule.max).toBe(1440);
+    expect(rule.increment).toBe(32);
+  });
+
+  test('unknown model falls back to default (range)', () => {
+    const { rule, modelKey } = _getModelSizeRule('completely-unknown-model');
+    expect(rule.kind).toBe('range');
+    expect(modelKey).toBe('default');
+  });
+});
+
+// ── _translateImageError ────────────────────────────────────────────────
+
+describe('_translateImageError', () => {
+  test('moderation error — rewrites with rephrasing hint', () => {
+    const msg = _translateImageError(
+      new Error('HTTP 400: Bad Request - content_policy violation'),
+      { prompt: 'blood', model: 'gpt-image-1.5' }
+    );
+    expect(msg).toMatch(/content moderation/i);
+    expect(msg).toMatch(/Rephrase/i);
+    expect(msg).toContain('gpt-image-1.5');
+    // Original text preserved for auditability
+    expect(msg).toContain('content_policy violation');
+  });
+
+  test('size error — lists valid sizes for gpt-image-1.5', () => {
+    const msg = _translateImageError(
+      new Error('Invalid image size: must be one of 1024x1024, 1024x1536, 1536x1024'),
+      { size: '1280x720', transparency: true }
+    );
+    expect(msg).toMatch(/size "1280x720" not accepted/);
+    expect(msg).toContain('gpt-image-1.5');
+    expect(msg).toContain('1024x1024');
+    expect(msg).toContain('1024x1536');
+    expect(msg).toContain('1536x1024');
+  });
+
+  test('size error — Flux: range hint', () => {
+    const msg = _translateImageError(
+      new Error('out of range'),
+      { size: '2000x2000', model: 'flux-1.1-pro' }
+    );
+    expect(msg).toMatch(/flux/);
+    expect(msg).toMatch(/256-1440/);
+    expect(msg).toMatch(/multiples of 32/);
+  });
+
+  test('auth error — flags non-retryability', () => {
+    const msg = _translateImageError(new Error('401 Unauthorized'), { model: 'gpt-image-1.5' });
+    expect(msg).toMatch(/authentication/i);
+    expect(msg).toMatch(/Retrying.*will likely fail/i);
+  });
+
+  test('unknown error — still includes model + size context', () => {
+    const msg = _translateImageError(new Error('network wobble'), { model: 'flux-1.1-pro', size: '1024x1024' });
+    expect(msg).toContain('flux-1.1-pro');
+    expect(msg).toContain('1024x1024');
+    expect(msg).toContain('network wobble');
+  });
+});