onbuzz 4.5.0 → 4.6.1

package/src/tools/__tests__/platformControlFlow.test.js

@@ -0,0 +1,412 @@
+/**
+ * Tool-level tests for the flow CRUD + execution actions on
+ * platformcontrol.
+ *
+ * Stubs the injected services (stateManager, flowExecutor). Pins:
+ *   - Permission level gating per action (disabled / self-created / all)
+ *   - Read endpoints (list/get) unrestricted at any non-disabled level
+ *   - Mutation endpoints respect self-created vs all
+ *   - Quota enforcement (maxFlowsCreated)
+ *   - createdBy tagging on new flows
+ *   - delete cascades through stateManager.deleteFlow
+ *   - execute-flow attributes the run to the calling agent
+ *   - dry-run-flow accepts EITHER an existing flowId OR an inline flow def
+ */
+
+import { describe, test, expect, beforeEach, jest } from '@jest/globals';
+import { PlatformControlTool } from '../platformControlTool.js';
+
+const LOGGER = { info() {}, warn() {}, error() {}, debug() {} };
+
+// ── Stubs ───────────────────────────────────────────────────────────
+
+function makeStateManager(initialFlows = []) {
+  const flows = new Map(initialFlows.map(f => [f.id, f]));
+  let createCounter = flows.size;
+  return {
+    config: { project: { directory: '/test/proj' } },
+    getAllFlows: jest.fn(async () => Array.from(flows.values())),
+    getFlow:     jest.fn(async (id) => flows.get(id) || null),
+    createFlow:  jest.fn(async (def) => {
+      createCounter += 1;
+      const id = `flow-${createCounter}`;
+      const f = { id, version: 1, ...def };
+      flows.set(id, f);
+      return f;
+    }),
+    updateFlow:  jest.fn(async (id, patch) => {
+      const f = flows.get(id);
+      if (!f) throw new Error(`Flow not found: ${id}`);
+      Object.assign(f, patch);
+      return f;
+    }),
+    deleteFlow:  jest.fn(async (id) => {
+      if (!flows.has(id)) throw new Error(`Flow not found: ${id}`);
+      flows.delete(id);
+      return true;
+    }),
+    _flows: flows,
+  };
+}
+
+function makeFlowExecutor() {
+  return {
+    executeFlow: jest.fn(async (flowId) => ({ runId: `run-${flowId}-1`, status: 'queued' })),
+    dryRun:      jest.fn(async () => ({ ok: true, errors: [], warnings: [] })),
+  };
+}
+
+const ctx = ({ agentId = 'caller', cfg = {} } = {}) => ({
+  agentId,
+  toolConfig: cfg,
+});
+
+// Minimal valid flow definition the createFlow stub accepts.
+const validNodes = () => ([
+  { id: 'in', type: 'input', position: { x: 0, y: 0 }, inputs: [],
+    outputs: [{ name: 'topic', type: 'text', description: 'Topic.' }] },
+  { id: 'out', type: 'output', position: { x: 200, y: 0 }, data: { outputFormat: 'text' },
+    inputs: [{ name: 'context', type: 'text', required: true, description: 'Output ctx.' }],
+    outputs: [] },
+]);
+
+// ── Permission gating ──────────────────────────────────────────────
+
+describe('flow permission gating', () => {
+  let tool, stateManager;
+  beforeEach(() => {
+    tool = new PlatformControlTool({}, LOGGER);
+    stateManager = makeStateManager([
+      { id: 'f-mine',  name: 'Mine',  createdBy: 'caller',       nodes: [], edges: [] },
+      { id: 'f-other', name: 'Other', createdBy: 'someone-else', nodes: [], edges: [] },
+    ]);
+    tool.setStateManager(stateManager);
+    tool.setFlowExecutor(makeFlowExecutor());
+  });
+
+  test('disabled (default) → list-flows refused with disabled:true', async () => {
+    const r = await tool.execute({ action: 'list-flows' }, ctx());
+    expect(r).toMatchObject({ success: false, disabled: true });
+  });
+
+  test('self-created → list-flows OK (read is unrestricted)', async () => {
+    const r = await tool.execute({ action: 'list-flows' }, ctx({ cfg: { flows: 'self-created' } }));
+    expect(r.success).toBe(true);
+    // List exposes ALL flows even at self-created — so the agent can
+    // browse and decide what to run/clone. Mutability is annotated
+    // per-row.
+    expect(r.flows.length).toBe(2);
+    const byId = Object.fromEntries(r.flows.map(f => [f.id, f]));
+    expect(byId['f-mine'].mutable).toBe(true);
+    expect(byId['f-other'].mutable).toBe(false);
+  });
+
+  test('all → list-flows shows all rows mutable', async () => {
+    const r = await tool.execute({ action: 'list-flows' }, ctx({ cfg: { flows: 'all' } }));
+    expect(r.success).toBe(true);
+    expect(r.flows.every(f => f.mutable)).toBe(true);
+  });
+
+  test('self-created + delete-flow on someone else\'s → out of scope', async () => {
+    const r = await tool.execute({ action: 'delete-flow', flowId: 'f-other' },
+      ctx({ cfg: { flows: 'self-created' } }));
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/self-created/i);
+    expect(stateManager.deleteFlow).not.toHaveBeenCalled();
+  });
+
+  test('self-created + delete-flow on my own → success', async () => {
+    const r = await tool.execute({ action: 'delete-flow', flowId: 'f-mine' },
+      ctx({ cfg: { flows: 'self-created' } }));
+    expect(r.success).toBe(true);
+    expect(stateManager.deleteFlow).toHaveBeenCalledWith('f-mine', '/test/proj');
+  });
+
+  test('all mode → delete-flow on someone else\'s → success', async () => {
+    const r = await tool.execute({ action: 'delete-flow', flowId: 'f-other' },
+      ctx({ cfg: { flows: 'all' } }));
+    expect(r.success).toBe(true);
+    expect(stateManager.deleteFlow).toHaveBeenCalledWith('f-other', '/test/proj');
+  });
+
+  test('disabled mode rejects EVERY mutation action with disabled:true', async () => {
+    for (const action of ['create-flow', 'update-flow', 'delete-flow', 'execute-flow', 'dry-run-flow']) {
+      const r = await tool.execute({ action, flowId: 'f-mine' }, ctx());
+      expect(r).toMatchObject({ success: false, disabled: true });
+    }
+  });
+});
+
+// ── create-flow ────────────────────────────────────────────────────
+
+describe('create-flow', () => {
+  let tool, stateManager;
+  beforeEach(() => {
+    tool = new PlatformControlTool({}, LOGGER);
+    stateManager = makeStateManager();
+    tool.setStateManager(stateManager);
+    tool.setFlowExecutor(makeFlowExecutor());
+  });
+
+  test('stamps createdBy from caller (so self-created scope can find it later)', async () => {
+    const r = await tool.execute(
+      { action: 'create-flow', name: 'Test', nodes: validNodes() },
+      ctx({ agentId: 'caller-x', cfg: { flows: 'self-created' } })
+    );
+    expect(r.success).toBe(true);
+    expect(stateManager.createFlow).toHaveBeenCalledWith(
+      expect.objectContaining({ createdBy: 'caller-x', name: 'Test' }),
+      '/test/proj'
+    );
+  });
+
+  test('rejects when name is missing', async () => {
+    const r = await tool.execute(
+      { action: 'create-flow', nodes: validNodes() },
+      ctx({ cfg: { flows: 'all' } })
+    );
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/name is required/i);
+    expect(stateManager.createFlow).not.toHaveBeenCalled();
+  });
+
+  test('rejects when nodes is empty / missing', async () => {
+    const r1 = await tool.execute(
+      { action: 'create-flow', name: 'x', nodes: [] },
+      ctx({ cfg: { flows: 'all' } })
+    );
+    expect(r1.success).toBe(false);
+    const r2 = await tool.execute(
+      { action: 'create-flow', name: 'x' },
+      ctx({ cfg: { flows: 'all' } })
+    );
+    expect(r2.success).toBe(false);
+    expect(stateManager.createFlow).not.toHaveBeenCalled();
+  });
+});
+
+// ── maxFlowsCreated quota ──────────────────────────────────────────
+
+describe('maxFlowsCreated quota', () => {
+  test('rejects creation past the per-creator quota', async () => {
+    const tool = new PlatformControlTool({}, LOGGER);
+    const stateManager = makeStateManager([
+      { id: 'a', name: 'A', createdBy: 'caller', nodes: [], edges: [] },
+      { id: 'b', name: 'B', createdBy: 'caller', nodes: [], edges: [] },
+    ]);
+    tool.setStateManager(stateManager);
+    tool.setFlowExecutor(makeFlowExecutor());
+
+    const r = await tool.execute(
+      { action: 'create-flow', name: 'C', nodes: validNodes() },
+      ctx({ cfg: { flows: 'self-created', maxFlowsCreated: 2 } })
+    );
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/maxFlowsCreated quota/i);
+    expect(stateManager.createFlow).not.toHaveBeenCalled();
+  });
+
+  test('does not count flows authored by OTHER agents toward this caller\'s quota', async () => {
+    const tool = new PlatformControlTool({}, LOGGER);
+    const stateManager = makeStateManager([
+      { id: 'a', name: 'A', createdBy: 'someone-else', nodes: [], edges: [] },
+      { id: 'b', name: 'B', createdBy: 'someone-else', nodes: [], edges: [] },
+    ]);
+    tool.setStateManager(stateManager);
+    tool.setFlowExecutor(makeFlowExecutor());
+
+    const r = await tool.execute(
+      { action: 'create-flow', name: 'mine', nodes: validNodes() },
+      ctx({ cfg: { flows: 'self-created', maxFlowsCreated: 2 } })
+    );
+    // Caller has authored 0 of 2 — even though there are 2 flows total,
+    // they aren't theirs.
+    expect(r.success).toBe(true);
+  });
+
+  test('null/unset maxFlowsCreated = unlimited', async () => {
+    const tool = new PlatformControlTool({}, LOGGER);
+    const stateManager = makeStateManager([
+      ...Array.from({ length: 50 }, (_, i) => ({ id: `f-${i}`, createdBy: 'caller', nodes: [], edges: [] })),
+    ]);
+    tool.setStateManager(stateManager);
+    tool.setFlowExecutor(makeFlowExecutor());
+
+    const r = await tool.execute(
+      { action: 'create-flow', name: 'unlimited', nodes: validNodes() },
+      ctx({ cfg: { flows: 'all' } })  // no maxFlowsCreated set
+    );
+    expect(r.success).toBe(true);
+  });
+});
+
+// ── update-flow ────────────────────────────────────────────────────
+
+describe('update-flow', () => {
+  let tool, stateManager;
+  beforeEach(() => {
+    tool = new PlatformControlTool({}, LOGGER);
+    stateManager = makeStateManager([
+      { id: 'f1', name: 'Mine', createdBy: 'caller', nodes: validNodes(), edges: [] },
+    ]);
+    tool.setStateManager(stateManager);
+    tool.setFlowExecutor(makeFlowExecutor());
+  });
+
+  test('strips identity-spoof fields from the patch (id, createdBy, version)', async () => {
+    const r = await tool.execute(
+      { action: 'update-flow', flowId: 'f1',
+        id: 'spoofed-id', createdBy: 'spoofed-creator', version: 999,
+        name: 'Renamed', description: 'New desc' },
+      ctx({ cfg: { flows: 'self-created' } })
+    );
+    expect(r.success).toBe(true);
+    const callArgs = stateManager.updateFlow.mock.calls[0];
+    expect(callArgs[0]).toBe('f1');                                 // flowId
+    expect(callArgs[1]).not.toHaveProperty('id');
+    expect(callArgs[1]).not.toHaveProperty('createdBy');
+    expect(callArgs[1]).not.toHaveProperty('version');
+    expect(callArgs[1].name).toBe('Renamed');
+    expect(callArgs[1].description).toBe('New desc');
+  });
+
+  test('returns 404-shape for unknown flowId', async () => {
+    const r = await tool.execute(
+      { action: 'update-flow', flowId: 'nonexistent', name: 'x' },
+      ctx({ cfg: { flows: 'all' } })
+    );
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/not found/i);
+  });
+});
+
+// ── execute-flow ───────────────────────────────────────────────────
+
+describe('execute-flow', () => {
+  let tool, stateManager, flowExecutor;
+  beforeEach(() => {
+    tool = new PlatformControlTool({}, LOGGER);
+    stateManager = makeStateManager([
+      { id: 'f-mine',  name: 'M', createdBy: 'caller',       nodes: [] },
+      { id: 'f-other', name: 'O', createdBy: 'someone-else', nodes: [] },
+    ]);
+    flowExecutor = makeFlowExecutor();
+    tool.setStateManager(stateManager);
+    tool.setFlowExecutor(flowExecutor);
+  });
+
+  test('refuses when flowExecutor is not wired', async () => {
+    const t2 = new PlatformControlTool({}, LOGGER);
+    t2.setStateManager(stateManager);
+    // Note: setFlowExecutor NOT called.
+    const r = await t2.execute(
+      { action: 'execute-flow', flowId: 'f-mine' },
+      ctx({ cfg: { flows: 'all' } })
+    );
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/FlowExecutor not available/i);
+  });
+
+  test('runs the flow + tags the run with the caller as triggeredBy.agent', async () => {
+    const r = await tool.execute(
+      { action: 'execute-flow', flowId: 'f-mine', input: { x: 1 } },
+      ctx({ agentId: 'caller', cfg: { flows: 'self-created' } })
+    );
+    expect(r.success).toBe(true);
+    expect(r.runId).toBeDefined();
+    expect(flowExecutor.executeFlow).toHaveBeenCalledWith(
+      'f-mine',
+      { x: 1 },
+      expect.objectContaining({
+        triggeredBy: { kind: 'agent', agentId: 'caller' },
+      })
+    );
+  });
+
+  test('self-created mode + execute someone else\'s flow → out of scope', async () => {
+    const r = await tool.execute(
+      { action: 'execute-flow', flowId: 'f-other' },
+      ctx({ cfg: { flows: 'self-created' } })
+    );
+    expect(r.success).toBe(false);
+    expect(flowExecutor.executeFlow).not.toHaveBeenCalled();
+  });
+});
+
+// ── dry-run-flow ───────────────────────────────────────────────────
+
+describe('dry-run-flow', () => {
+  let tool, stateManager, flowExecutor;
+  beforeEach(() => {
+    tool = new PlatformControlTool({}, LOGGER);
+    stateManager = makeStateManager([
+      { id: 'saved', name: 'Saved', createdBy: 'caller', nodes: validNodes(), edges: [] },
+    ]);
+    flowExecutor = makeFlowExecutor();
+    tool.setStateManager(stateManager);
+    tool.setFlowExecutor(flowExecutor);
+  });
+
+  test('accepts an existing flowId and returns the executor\'s lint report', async () => {
+    const r = await tool.execute(
+      { action: 'dry-run-flow', flowId: 'saved' },
+      ctx({ cfg: { flows: 'self-created' } })
+    );
+    expect(r.success).toBe(true);
+    expect(r.report).toEqual({ ok: true, errors: [], warnings: [] });
+    expect(flowExecutor.dryRun).toHaveBeenCalled();
+  });
+
+  test('accepts an inline flow definition (so an agent can lint a draft before saving)', async () => {
+    const draft = { name: 'draft', nodes: validNodes(), edges: [] };
+    const r = await tool.execute(
+      { action: 'dry-run-flow', flow: draft },
+      ctx({ cfg: { flows: 'self-created' } })
+    );
+    expect(r.success).toBe(true);
+    expect(flowExecutor.dryRun).toHaveBeenCalledWith(draft);
+  });
+
+  test('rejects when neither flowId nor flow is provided', async () => {
+    const r = await tool.execute(
+      { action: 'dry-run-flow' },
+      ctx({ cfg: { flows: 'self-created' } })
+    );
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/flowId.*flow/i);
+  });
+});
+
+// ── list-capabilities surfaces flows ────────────────────────────────
+
+describe('list-capabilities (flows surface)', () => {
+  test('surfaces flow level + max + boolean caps', async () => {
+    const tool = new PlatformControlTool({}, LOGGER);
+    tool.setStateManager(makeStateManager());
+    tool.setFlowExecutor(makeFlowExecutor());
+    const r = await tool.execute({ action: 'list-capabilities' },
+      ctx({ cfg: { flows: 'self-created', maxFlowsCreated: 5 } }));
+    expect(r.success).toBe(true);
+    expect(r.capabilities.flows).toMatchObject({
+      level: 'self-created',
+      maxFlowsCreated: 5,
+      canList:        true,
+      canCreate:      true,
+      canMutateSelfCreated: true,
+      canMutateAll:   false,
+    });
+  });
+
+  test('disabled flow level surfaces canList=false / canCreate=false', async () => {
+    const tool = new PlatformControlTool({}, LOGGER);
+    tool.setStateManager(makeStateManager());
+    tool.setFlowExecutor(makeFlowExecutor());
+    const r = await tool.execute({ action: 'list-capabilities' }, ctx());
+    expect(r.success).toBe(true);
+    expect(r.capabilities.flows).toMatchObject({
+      level: 'disabled',
+      canList:   false,
+      canCreate: false,
+    });
+  });
+});

package/src/tools/imageFormat.js

@@ -0,0 +1,249 @@
+/**
+ * Image format helpers for the imageTool.
+ *
+ * The image providers (Flux, GPT-Image-1.5, etc.) typically return PNG
+ * bytes, but our default output is now WebP — meaning we need real
+ * format conversion before saving to disk. This module owns:
+ *
+ *   - Format resolution (what target format does the user want?)
+ *   - Magic-byte detection (what format ARE the provider's bytes?)
+ *   - Transcoding via sharp, with a graceful fallback if sharp fails
+ *     to load (e.g. weird platform without prebuilt binaries — we'd
+ *     rather save the original bytes than fail the whole render)
+ *   - Filename ↔ format mapping
+ *
+ * Pure-ish: `transcodeIfNeeded` is the only function with side effects
+ * (calls sharp, which spins up native code). Everything else is sync
+ * + side-effect-free → easy to unit test.
+ *
+ * Why a separate file: keeps imageTool.js focused on orchestration and
+ * makes the format logic testable WITHOUT mocking the entire tool +
+ * its provider clients.
+ */
+
+import path from 'path';
+
+/** Canonical formats we read/write. */
+export const SUPPORTED_FORMATS = Object.freeze(['png', 'jpeg', 'webp']);
+
+/** Default output when the agent doesn't specify. */
+export const DEFAULT_FORMAT = 'webp';
+
+/**
+ * Map an extension or alias to a canonical format name. Returns null
+ * if the input doesn't map cleanly.
+ *
+ * - 'jpg' / 'jpeg' / '.jpg' / '.jpeg' → 'jpeg'
+ * - 'png' / '.png' → 'png'
+ * - 'webp' / '.webp' → 'webp'
+ */
+export function normalizeFormat(input) {
+  if (typeof input !== 'string') return null;
+  const lower = input.trim().toLowerCase().replace(/^\./, '');
+  if (lower === 'jpg' || lower === 'jpeg') return 'jpeg';
+  if (lower === 'png')  return 'png';
+  if (lower === 'webp') return 'webp';
+  return null;
+}
+
+/**
+ * The on-disk extension for a canonical format. JPEG → "jpg" (the more
+ * common file extension); PNG → "png"; WebP → "webp".
+ */
+export function extensionFor(format) {
+  if (format === 'jpeg') return 'jpg';
+  if (format === 'png')  return 'png';
+  if (format === 'webp') return 'webp';
+  return 'webp';   // fallback — should never hit if callers respect SUPPORTED_FORMATS
+}
+
+/**
+ * Decide what target format to write, given the agent's request.
+ *
+ * Priority:
+ *   1. outputPath extension (e.g. "foo.png" forces PNG, "foo.jpg" → JPEG)
+ *   2. outputType field (explicit format request)
+ *   3. DEFAULT_FORMAT ('webp')
+ *
+ * @param {object} args
+ * @param {string} [args.outputPath]  May or may not have an extension.
+ * @param {string} [args.outputType]  e.g. 'png' | 'webp' | 'jpg' — agent-friendly.
+ * @returns {{ format: 'png'|'jpeg'|'webp', source: 'extension'|'outputType'|'default' }}
+ */
+export function resolveTargetFormat({ outputPath, outputType } = {}) {
+  if (typeof outputPath === 'string' && outputPath.length > 0) {
+    const ext = path.extname(outputPath);
+    const fmt = normalizeFormat(ext);
+    if (fmt) return { format: fmt, source: 'extension' };
+  }
+  if (outputType !== undefined && outputType !== null) {
+    const fmt = normalizeFormat(outputType);
+    if (fmt) return { format: fmt, source: 'outputType' };
+  }
+  return { format: DEFAULT_FORMAT, source: 'default' };
+}
+
+/**
+ * Sniff the encoded format of a buffer by inspecting the first few bytes.
+ * Returns null when nothing matches — caller then assumes "unknown" and
+ * MAY skip transcoding (safer than transcoding bytes we don't recognize).
+ *
+ * Magic-byte references:
+ *   PNG  : 89 50 4E 47 0D 0A 1A 0A
+ *   JPEG : FF D8 FF
+ *   WebP : "RIFF" .... "WEBP"
+ *   GIF  : "GIF87a" or "GIF89a"  (we don't transcode but recognize)
+ *   BMP  : 42 4D
+ */
+export function detectFormatFromBytes(buffer) {
+  if (!buffer || typeof buffer.length !== 'number' || buffer.length < 12) return null;
+  if (buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4E && buffer[3] === 0x47) return 'png';
+  if (buffer[0] === 0xFF && buffer[1] === 0xD8 && buffer[2] === 0xFF) return 'jpeg';
+  if (
+    buffer[0] === 0x52 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x46 &&
+    buffer[8] === 0x57 && buffer[9] === 0x45 && buffer[10] === 0x42 && buffer[11] === 0x50
+  ) return 'webp';
+  if (buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46) return 'gif';
+  if (buffer[0] === 0x42 && buffer[1] === 0x4D) return 'bmp';
+  return null;
+}
+
+/**
+ * Lazy sharp loader. Caches the module after first import; re-attempts
+ * on null cache so a transient failure (e.g. concurrent install) doesn't
+ * permanently disable transcoding.
+ *
+ * Wrapped in try/catch — if the native module fails to load on the
+ * host (rare but possible on uncommon platforms), we report null and
+ * the caller falls back to writing raw provider bytes.
+ */
+let _sharp = null;
+let _sharpLoadAttempted = false;
+let _sharpLoadError = null;
+async function _getSharp() {
+  if (_sharp) return _sharp;
+  if (_sharpLoadAttempted && _sharpLoadError) {
+    // Retry once after a small grace period rather than caching the
+    // failure forever — node module resolution can race during install.
+  }
+  try {
+    const mod = await import('sharp');
+    _sharp = mod.default || mod;
+    _sharpLoadError = null;
+    return _sharp;
+  } catch (err) {
+    _sharpLoadAttempted = true;
+    _sharpLoadError = err;
+    return null;
+  }
+}
+
+/** Test-only — clear sharp cache so a subsequent call re-imports. */
+export function _resetSharpCacheForTests() {
+  _sharp = null;
+  _sharpLoadAttempted = false;
+  _sharpLoadError = null;
+}
+
+/**
+ * Transcode `buffer` to `targetFormat`. Returns a result describing
+ * what happened so the caller can log + report:
+ *
+ *   { buffer: <out>, transcoded: true,  inputFormat: 'png', outputFormat: 'webp' }
+ *     — sharp converted the bytes
+ *   { buffer: <in>,  transcoded: false, inputFormat: 'webp', outputFormat: 'webp', reason: 'already-target' }
+ *     — input format already matches target; no work
+ *   { buffer: <in>,  transcoded: false, inputFormat: null,   outputFormat: 'webp', reason: 'unknown-input' }
+ *     — couldn't sniff input; safer to write bytes as-is
+ *   { buffer: <in>,  transcoded: false, inputFormat: 'png',  outputFormat: 'webp', reason: 'sharp-unavailable', error }
+ *     — sharp couldn't load; fall back to raw bytes
+ *   { buffer: <in>,  transcoded: false, inputFormat: 'png',  outputFormat: 'webp', reason: 'transcode-failed', error }
+ *     — sharp threw mid-transcode
+ *
+ * @param {Buffer} buffer
+ * @param {'png'|'jpeg'|'webp'} targetFormat
+ * @param {object} [opts]
+ * @param {number} [opts.quality=85]   For JPEG/WebP. PNG ignores it.
+ * @param {object} [opts.logger]
+ */
+export async function transcodeIfNeeded(buffer, targetFormat, opts = {}) {
+  const quality = Number.isFinite(opts.quality) ? opts.quality : 85;
+  const logger  = opts.logger || null;
+  const inputFormat = detectFormatFromBytes(buffer);
+
+  // Already in the desired format — no work, no quality loss.
+  if (inputFormat && inputFormat === targetFormat) {
+    return { buffer, transcoded: false, inputFormat, outputFormat: targetFormat, reason: 'already-target' };
+  }
+  if (!inputFormat) {
+    logger?.warn?.('[imageFormat] could not sniff input format; writing bytes as-is', { targetFormat });
+    return { buffer, transcoded: false, inputFormat: null, outputFormat: targetFormat, reason: 'unknown-input' };
+  }
+  // GIF / BMP — sharp can read these but transcoding GIFs to webp
+  // animation requires more thought; for now write bytes as-is.
+  if (inputFormat === 'gif' || inputFormat === 'bmp') {
+    return { buffer, transcoded: false, inputFormat, outputFormat: targetFormat, reason: 'unsupported-input' };
+  }
+
+  const sharpFn = await _getSharp();
+  if (!sharpFn) {
+    logger?.warn?.('[imageFormat] sharp not available; writing bytes as-is', {
+      targetFormat,
+      error: _sharpLoadError?.message,
+    });
+    return {
+      buffer,
+      transcoded: false,
+      inputFormat,
+      outputFormat: targetFormat,
+      reason: 'sharp-unavailable',
+      error: _sharpLoadError,
+    };
+  }
+
+  try {
+    let pipeline = sharpFn(buffer);
+    if (targetFormat === 'webp') pipeline = pipeline.webp({ quality });
+    else if (targetFormat === 'jpeg') pipeline = pipeline.jpeg({ quality });
+    else if (targetFormat === 'png')  pipeline = pipeline.png();
+    const out = await pipeline.toBuffer();
+    return { buffer: out, transcoded: true, inputFormat, outputFormat: targetFormat };
+  } catch (err) {
+    logger?.warn?.('[imageFormat] transcode failed; writing original bytes as-is', {
+      inputFormat, targetFormat, error: err?.message,
+    });
+    return {
+      buffer,
+      transcoded: false,
+      inputFormat,
+      outputFormat: targetFormat,
+      reason: 'transcode-failed',
+      error: err,
+    };
+  }
+}
+
+/**
+ * Convenience: if the user-supplied outputPath has no extension,
+ * append the target format's extension. Otherwise return as-is.
+ * (The agent might pass `images/foo` without an extension — we'd
+ * normally reject, but for the auto-extension case we just append.)
+ */
+export function ensureExtension(outputPath, targetFormat) {
+  if (!outputPath || typeof outputPath !== 'string') return outputPath;
+  const ext = path.extname(outputPath);
+  if (ext && normalizeFormat(ext)) return outputPath;
+  return `${outputPath}.${extensionFor(targetFormat)}`;
+}
+
+export default {
+  SUPPORTED_FORMATS,
+  DEFAULT_FORMAT,
+  normalizeFormat,
+  extensionFor,
+  resolveTargetFormat,
+  detectFormatFromBytes,
+  transcodeIfNeeded,
+  ensureExtension,
+  _resetSharpCacheForTests,
+};