onbuzz 4.4.0 → 4.6.0

package/src/services/flowContextService.js

@@ -17,9 +17,13 @@ class FlowContextService {
    * Build flow execution context to inject into agent's system prompt
    * @param {Object} flowMetadata - Current flow execution metadata
    * @param {Object} previousAgentData - Data from previous agent (if any)
+   * @param {Object} [nodeContract] - v2 typed I/O { inputs, outputs }; when
+   *                                  present, the system prompt advertises
+   *                                  the EXACT named/typed payload the
+   *                                  agent receives and must produce.
    * @returns {string} Context string to inject into system prompt
    */
-  buildFlowAgentContext(flowMetadata, previousAgentData) {
+  buildFlowAgentContext(flowMetadata, previousAgentData, nodeContract) {
     const sections = [];
 
     // Flow execution header
@@ -27,12 +31,90 @@ class FlowContextService {
 <FLOW_EXECUTION_CONTEXT>
 You are executing step "${flowMetadata.nodeName || 'Agent'}" (${flowMetadata.nodePosition}/${flowMetadata.totalNodes}) in flow "${flowMetadata.flowName}".`);
 
+    // Phase 7: overall flow goal — orients each agent to the bigger
+    // picture so they reason about their step in context of the whole.
+    if (this._hasText(flowMetadata?.flowDescription)) {
+      sections.push(`
+FLOW GOAL:
+${flowMetadata.flowDescription.trim()}`);
+    }
+
+    // Phase 7: per-node instructions — role, working style, and
+    // success criteria for THIS step. Distinct from the user prompt
+    // template (which is the input message). Lives at node.data.instructions.
+    if (this._hasText(nodeContract?.instructions)) {
+      sections.push(`
+NODE INSTRUCTIONS (your role + how to succeed at this step):
+${nodeContract.instructions.trim()}`);
+    }
+
     // Critical instruction about context isolation
     sections.push(`
 CRITICAL HANDOFF REQUIREMENT:
 The NEXT agent in this flow has NO ACCESS to your conversation history or any context you've built up.
 Everything you learn, create, or discover must be explicitly passed via job-done.`);
 
+    // v2: declared INPUTS — what payload the agent is receiving.
+    // Phase 7: each input now optionally carries a description and an
+    // example. The description tells the agent what this input
+    // represents AND how to use it; the example shows concrete shape.
+    if (nodeContract && Array.isArray(nodeContract.inputs) && nodeContract.inputs.length > 0) {
+      const lines = nodeContract.inputs.map(i => this._renderIOEntry(i, /*required default*/ true));
+      sections.push(`
+INPUTS (this step receives these typed values; reference them in your reasoning):
+${lines.join('\n')}`);
+    }
+
+    // v2: declared OUTPUTS — exactly what the agent must produce.
+    // Phase 7 hardening: stronger framing + concrete example shape that
+    // the model can mimic literally. Empirical finding: weak instruction
+    // ("you MUST include outputs") + abstract placeholder (`<text value>`)
+    // → models default to schema-minimum. Loud framing + concrete shape
+    // dramatically improves first-pass compliance.
+    if (nodeContract && Array.isArray(nodeContract.outputs) && nodeContract.outputs.length > 0) {
+      const lines = nodeContract.outputs.map(o => this._renderIOEntry(o, /*required default*/ false));
+      // Build a concrete example object using each field's example if
+      // provided, else a typed placeholder. The agent should imitate
+      // this shape literally — only the values change.
+      const exampleEntries = nodeContract.outputs.map(o => {
+        let exVal;
+        if (o.example !== undefined && o.example !== null) {
+          try { exVal = JSON.stringify(o.example); }
+          catch { exVal = this._typedPlaceholder(o.type); }
+        } else {
+          exVal = this._typedPlaceholder(o.type);
+        }
+        return `      "${o.name}": ${exVal}`;
+      }).join(',\n');
+
+      sections.push(`
+═══════════════════════════════════════════════════════════════
+REQUIRED OUTPUTS — your job-done call MUST populate every field below
+═══════════════════════════════════════════════════════════════
+
+${lines.join('\n')}
+
+THE ONLY VALID FORMAT for ending this task is a jobdone tool call
+with this exact shape (replace example values with your real content,
+keep field names and structure identical):
+
+{
+  "toolId": "jobdone",
+  "actions": [{
+    "action": "complete",
+    "summary": "<your one-paragraph summary>",
+    "outputs": {
+${exampleEntries}
+    }
+  }]
+}
+
+Calls without the "outputs" field — or with "outputs" missing any of
+the field names listed above — will be REJECTED and you will be
+re-prompted. The flow CANNOT proceed without these structured outputs.
+═══════════════════════════════════════════════════════════════`);
+    }
+
     // Job-done instructions
     sections.push(`
 When you complete your task, you MUST call the job-done tool with comprehensive details:
@@ -54,6 +136,35 @@ ${previousAgentData.filesCreated?.length > 0 ? `- Files they created/modified:\n
 ${previousAgentData.output ? `
 - Their output:
 ${this._formatPreviousOutput(previousAgentData.output)}` : ''}`);
+
+      // v2: render the structured outputs bag if upstream agents
+      // produced one. THIS is the handoff payload — agents downstream
+      // should reason from these named fields, not from the prose
+      // summary. Without this section the typed contract is invisible
+      // at runtime and agents fabricate the data.
+      if (previousAgentData.outputs && typeof previousAgentData.outputs === 'object'
+          && Object.keys(previousAgentData.outputs).length > 0) {
+        const lines = Object.entries(previousAgentData.outputs).map(([k, v]) =>
+          `  • ${k} = ${this._formatStructuredValue(v)}`
+        );
+        sections.push(`
+STRUCTURED HANDOFF FROM UPSTREAM (use these as the source of truth — not the summary):
+${lines.join('\n')}`);
+      }
+
+      // If multiple agents fed this node, list contributors per-agent
+      // so the model knows who produced what. Helpful for fan-in nodes.
+      if (Array.isArray(previousAgentData.contributors) && previousAgentData.contributors.length > 1) {
+        const blocks = previousAgentData.contributors.map(c => {
+          const outs = c.outputs && Object.keys(c.outputs).length > 0
+            ? Object.entries(c.outputs).map(([k, v]) => `      ${k} = ${this._formatStructuredValue(v)}`).join('\n')
+            : '      (no structured outputs)';
+          return `  - ${c.agentName} (${c.agentId}):\n${outs}`;
+        });
+        sections.push(`
+ALL UPSTREAM CONTRIBUTORS (this node has multiple inputs):
+${blocks.join('\n')}`);
+      }
     } else {
       sections.push(`
 This is the FIRST agent in the flow - you are receiving the initial user input.`);
@@ -78,6 +189,234 @@ FLOW EXECUTION RULES:
    * @param {string|Object} output - Previous output
    * @returns {string} Formatted output
    */
+  /**
+   * Phase 8 (the big one): build a STANDALONE system prompt that REPLACES
+   * the agent's persisted system prompt for the duration of a flow step.
+   *
+   * Why: production findings showed the agent's own system prompt
+   * ("You are a software developer...") fights the flow contract.
+   * The agent's training pulls it toward its native role
+   * (engineering, code, task lists) instead of producing the typed
+   * outputs the flow declares. Appending flow context didn't beat the
+   * prior identity.
+   *
+   * This builder produces a single self-contained prompt that defines
+   * the agent's IDENTITY for this step in terms of the flow node's
+   * declared role + I/O contract. The agent's tools/capabilities/model
+   * stay the same — only the role-defining prose changes.
+   *
+   * Returns null when there's no node-level role to assert (no
+   * instructions AND no typed I/O). In that case the caller falls back
+   * to the legacy append-context behavior.
+   *
+   * @returns {string|null} the new system prompt, or null to keep native
+   */
+  buildFlowAgentSystemPrompt(flowMetadata, previousAgentData, nodeContract) {
+    if (!nodeContract) return null;
+    const hasInstructions = this._hasText(nodeContract.instructions);
+    const hasOutputs      = Array.isArray(nodeContract.outputs) && nodeContract.outputs.length > 0;
+    if (!hasInstructions && !hasOutputs) return null;
+
+    const sections = [];
+    sections.push(
+`You are acting as the "${flowMetadata.nodeName || 'Agent'}" step (${flowMetadata.nodePosition}/${flowMetadata.totalNodes}) of the flow "${flowMetadata.flowName}".`
+    );
+
+    if (this._hasText(flowMetadata?.flowDescription)) {
+      sections.push(`OVERALL FLOW GOAL:\n${flowMetadata.flowDescription.trim()}`);
+    }
+
+    if (hasInstructions) {
+      sections.push(`YOUR ROLE FOR THIS STEP:\n${nodeContract.instructions.trim()}`);
+    }
+
+    sections.push(
+`HOW TO COMPLETE THIS STEP — the only valid completion:
+1. Read the typed inputs you receive (listed below).
+2. Produce the typed outputs declared below.
+3. Call the job-done tool with summary, details, AND a populated
+   "outputs" object containing every required field.
+
+DO NOT:
+- Maintain or update task lists. This step has no other steps.
+- Write status paragraphs. The flow is autonomous.
+- Call any tool other than job-done unless it is genuinely required
+  to gather data for the structured outputs.
+- Defer the work. There is no human in this conversation — produce
+  the outputs and finish.
+
+The flow CANNOT proceed until you call job-done with the correct
+"outputs" object. Calls that omit any required field will be rejected
+and you will be asked to re-emit.`
+    );
+
+    // INPUTS — typed, with descriptions/examples
+    if (Array.isArray(nodeContract.inputs) && nodeContract.inputs.length > 0) {
+      const lines = nodeContract.inputs.map(i => this._renderIOEntry(i, true));
+      sections.push(`INPUTS (you receive these typed values from upstream):\n${lines.join('\n')}`);
+    }
+
+    // OUTPUTS — typed, with descriptions/examples + concrete shape
+    if (hasOutputs) {
+      const lines = nodeContract.outputs.map(o => this._renderIOEntry(o, false));
+      const exampleEntries = nodeContract.outputs.map(o => {
+        let exVal;
+        if (o.example !== undefined && o.example !== null) {
+          try { exVal = JSON.stringify(o.example); }
+          catch { exVal = this._typedPlaceholder(o.type); }
+        } else {
+          exVal = this._typedPlaceholder(o.type);
+        }
+        return `      "${o.name}": ${exVal}`;
+      }).join(',\n');
+
+      sections.push(
+`REQUIRED OUTPUTS — you MUST populate every field below in job-done's "outputs":
+${lines.join('\n')}
+
+EXACT job-done call shape (replace example values; keep keys identical):
+{
+  "toolId": "jobdone",
+  "actions": [{
+    "action": "complete",
+    "summary": "<one-paragraph summary of what you produced>",
+    "outputs": {
+${exampleEntries}
+    }
+  }]
+}`
+      );
+    }
+
+    // Previous agent context — same as in append mode but inside the
+    // standalone prompt now.
+    if (previousAgentData) {
+      const parts = [`Previous step: ${previousAgentData.agentName || previousAgentData.agentId}.`];
+      if (previousAgentData.summary) parts.push(`Their summary: ${previousAgentData.summary}`);
+      if (previousAgentData.outputs && Object.keys(previousAgentData.outputs).length > 0) {
+        const fields = Object.entries(previousAgentData.outputs)
+          .map(([k, v]) => `  • ${k} = ${this._formatStructuredValue(v)}`)
+          .join('\n');
+        parts.push(`Their structured outputs (use as your source of truth):\n${fields}`);
+      } else if (previousAgentData.output) {
+        parts.push(`Their output:\n${this._formatPreviousOutput(previousAgentData.output)}`);
+      }
+      sections.push(`UPSTREAM CONTEXT:\n${parts.join('\n')}`);
+    } else {
+      sections.push(`This is the FIRST step. You receive the user's initial input.`);
+    }
+
+    return sections.join('\n\n');
+  }
+
+  /**
+   * Phase 7 hardening helper: typed placeholder rendering for the
+   * concrete example block in REQUIRED OUTPUTS. Used only when the
+   * field has no `example` declared. Each placeholder is itself valid
+   * JSON of the right type so the agent can copy-paste the structure.
+   */
+  _typedPlaceholder(type) {
+    switch (type) {
+      case 'text':       return '"<your text content here>"';
+      case 'number':     return '0';
+      case 'boolean':    return 'true';
+      case 'json':       return '{ "key": "value" }';
+      case 'file':       return '"/path/to/file.ext"';
+      case 'file[]':     return '["/path/to/file1", "/path/to/file2"]';
+      case 'list<text>': return '["item 1", "item 2", "item 3"]';
+      default:           return '"<value>"';
+    }
+  }
+
+  /**
+   * Phase 7 helper: true when a string is present and non-empty after
+   * trimming. Empty/whitespace-only descriptions are treated as absent.
+   */
+  _hasText(s) {
+    return typeof s === 'string' && s.trim().length > 0;
+  }
+
+  /**
+   * Phase 7 helper: render one input or output declaration as a multi-
+   * line block:
+   *
+   *   • topic (text, required)
+   *     The research topic exactly as provided.
+   *     Example: "AI safety"
+   *
+   * Description and example are both optional. Required-marker policy
+   * differs slightly between inputs (default required:true) and outputs
+   * (no inherent required flag) — caller passes `requiredByDefault`.
+   *
+   * The same description text is read by BOTH the producer (interprets
+   * as "format thus") and the consumer (interprets as "expect thus").
+   * That bidirectional contract is the whole point.
+   */
+  _renderIOEntry(entry, requiredByDefault) {
+    if (!entry || typeof entry.name !== 'string') return '';
+    const reqLabel = (entry.required === true)  ? ', required'
+                   : (entry.required === false) ? ', optional'
+                   : (requiredByDefault ? ', required' : '');
+    const head = `  • ${entry.name} (${entry.type}${reqLabel})`;
+    const lines = [head];
+    if (this._hasText(entry.description)) {
+      // Indent every line of the description by 4 spaces.
+      const indented = entry.description.trim().split('\n').map(l => `    ${l}`).join('\n');
+      lines.push(indented);
+    }
+    if (entry.example !== undefined && entry.example !== null) {
+      let rendered;
+      try {
+        rendered = (typeof entry.example === 'string')
+          ? JSON.stringify(entry.example)
+          : JSON.stringify(entry.example, null, 2);
+      } catch {
+        rendered = '<unstringifiable example>';
+      }
+      // Single-line examples stay inline; multi-line get their own block.
+      if (rendered.includes('\n')) {
+        const indented = rendered.split('\n').map(l => `    ${l}`).join('\n');
+        lines.push(`    Example:\n${indented}`);
+      } else {
+        lines.push(`    Example: ${rendered}`);
+      }
+    }
+    return lines.join('\n');
+  }
+
+  /**
+   * Render a structured output value compactly for the system prompt.
+   * Strings are quoted, primitives are JSON-ified, arrays/objects are
+   * pretty-printed and truncated. Goal: the model can READ the value
+   * without it dominating the prompt.
+   */
+  _formatStructuredValue(v) {
+    if (v === null) return 'null';
+    if (v === undefined) return 'undefined';
+    if (typeof v === 'string') {
+      // Single-line: quote inline. Multi-line: truncate-and-quote.
+      if (!v.includes('\n') && v.length <= 200) return JSON.stringify(v);
+      const truncated = v.length > 1500 ? v.slice(0, 1500) + '\n... (truncated)' : v;
+      return `"""\n${truncated}\n"""`;
+    }
+    if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+    if (Array.isArray(v)) {
+      if (v.length === 0) return '[]';
+      if (v.every(x => typeof x === 'string') && v.length <= 10) {
+        return `[${v.map(x => JSON.stringify(x)).join(', ')}]`;
+      }
+      const json = JSON.stringify(v, null, 2);
+      return json.length > 1500 ? json.slice(0, 1500) + '\n... (truncated)' : json;
+    }
+    // Object
+    try {
+      const json = JSON.stringify(v, null, 2);
+      return json.length > 1500 ? json.slice(0, 1500) + '\n... (truncated)' : json;
+    } catch {
+      return String(v);
+    }
+  }
+
   _formatPreviousOutput(output) {
     if (!output) return '';
 
@@ -112,11 +451,17 @@ FLOW EXECUTION RULES:
   }
 
   /**
-   * Validate that job-done result has sufficient detail for flow handoff
+   * Validate that job-done result has sufficient detail for flow handoff.
+   *
    * @param {Object} jobDoneResult - The job-done tool result
+   * @param {Object} [nodeContract] - v2 typed contract { outputs: [...] }.
+   *   When provided, ALSO validates that jobDoneResult.outputs contains
+   *   every declared output field with a type-correct value. The result
+   *   gains a `missingOutputs[]` field listing field names that are
+   *   absent or null.
    * @returns {Object} Validation result with warnings if insufficient
    */
-  validateJobDoneForFlow(jobDoneResult) {
+  validateJobDoneForFlow(jobDoneResult, nodeContract) {
     const warnings = [];
 
     if (!jobDoneResult.summary || jobDoneResult.summary.length < 20) {
@@ -137,13 +482,39 @@ FLOW EXECUTION RULES:
       warnings.push('Files mentioned but no explicit paths provided - consider listing created files');
     }
 
-    return {
+    // v2: structured output validation against the node's declared contract.
+    // We check presence + a basic type sanity on each declared field.
+    // Type validation here is intentionally permissive (warn, don't reject
+    // on type widenings) — the goal is to surface real gaps to the agent
+    // so Phase 2 can re-prompt, not to reject borderline values.
+    let missingOutputs;
+    if (nodeContract && Array.isArray(nodeContract.outputs) && nodeContract.outputs.length > 0) {
+      missingOutputs = [];
+      const provided = (jobDoneResult.outputs && typeof jobDoneResult.outputs === 'object')
+        ? jobDoneResult.outputs : {};
+      for (const decl of nodeContract.outputs) {
+        if (!decl || typeof decl.name !== 'string') continue;
+        if (!(decl.name in provided) || provided[decl.name] === null || provided[decl.name] === undefined) {
+          missingOutputs.push(decl.name);
+          warnings.push(`Required output "${decl.name}" (${decl.type}) is missing from job-done.outputs`);
+          continue;
+        }
+        const val = provided[decl.name];
+        if (!_typeMatches(val, decl.type)) {
+          warnings.push(`Output "${decl.name}" expected ${decl.type} but got ${_describeRuntimeType(val)}`);
+        }
+      }
+    }
+
+    const result = {
       valid: warnings.length === 0,
       warnings,
       suggestions: warnings.length > 0
         ? 'Ensure your job-done includes: detailed summary, explicit file paths, and any context the next agent needs.'
         : null
     };
+    if (missingOutputs !== undefined) result.missingOutputs = missingOutputs;
+    return result;
   }
 
   /**
@@ -186,4 +557,30 @@ FLOW EXECUTION RULES:
   }
 }
 
+/**
+ * Runtime type check for declared output values. Permissive on purpose:
+ * we want to surface clear mismatches (number expected, string given)
+ * but allow widenings (json accepts anything; text accepts numbers
+ * because they'll stringify cleanly downstream).
+ */
+function _typeMatches(value, type) {
+  if (value === null || value === undefined) return false;
+  switch (type) {
+    case 'text':       return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
+    case 'number':     return typeof value === 'number' && Number.isFinite(value);
+    case 'boolean':    return typeof value === 'boolean';
+    case 'json':       return true;
+    case 'file':       return typeof value === 'string' && value.length > 0;
+    case 'file[]':     return Array.isArray(value) && value.every(v => typeof v === 'string' && v.length > 0);
+    case 'list<text>': return Array.isArray(value) && value.every(v => typeof v === 'string');
+    default:           return true; // unknown type → don't gatekeep
+  }
+}
+
+function _describeRuntimeType(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  return typeof value;
+}
+
 export default FlowContextService;

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

@@ -0,0 +1,208 @@
+/**
+ * Tests for imageFormat helpers — pure functions + the sharp-wrapper
+ * fallback path. We don't actually transcode in tests (sharp may not be
+ * installed in CI yet) — `transcodeIfNeeded` has clean fallbacks for
+ * "already in target format" and "unknown input" that we can pin.
+ */
+
+import { describe, test, expect, beforeEach } from '@jest/globals';
+import {
+  SUPPORTED_FORMATS,
+  DEFAULT_FORMAT,
+  normalizeFormat,
+  extensionFor,
+  resolveTargetFormat,
+  detectFormatFromBytes,
+  transcodeIfNeeded,
+  ensureExtension,
+  _resetSharpCacheForTests,
+} from '../imageFormat.js';
+
+beforeEach(() => { _resetSharpCacheForTests(); });
+
+describe('constants', () => {
+  test('default format is webp', () => {
+    expect(DEFAULT_FORMAT).toBe('webp');
+  });
+  test('supported formats include png, jpeg, webp', () => {
+    expect(SUPPORTED_FORMATS).toEqual(expect.arrayContaining(['png', 'jpeg', 'webp']));
+  });
+});
+
+describe('normalizeFormat', () => {
+  test.each([
+    ['png', 'png'], ['.png', 'png'], ['PNG', 'png'],
+    ['jpg', 'jpeg'], ['.jpg', 'jpeg'], ['jpeg', 'jpeg'], ['.jpeg', 'jpeg'], ['JPG', 'jpeg'],
+    ['webp', 'webp'], ['.webp', 'webp'], ['WEBP', 'webp'], ['  WebP  ', 'webp'],
+  ])('"%s" → %s', (input, expected) => {
+    expect(normalizeFormat(input)).toBe(expected);
+  });
+  test.each([null, undefined, '', 'gif', 'bmp', 'random', 42])('rejects "%p" → null', (input) => {
+    expect(normalizeFormat(input)).toBe(null);
+  });
+});
+
+describe('extensionFor', () => {
+  test('png → "png"', () => { expect(extensionFor('png')).toBe('png'); });
+  test('jpeg → "jpg" (the more common file extension)', () => { expect(extensionFor('jpeg')).toBe('jpg'); });
+  test('webp → "webp"', () => { expect(extensionFor('webp')).toBe('webp'); });
+  test('unknown → "webp" fallback (defensive)', () => { expect(extensionFor('xyz')).toBe('webp'); });
+});
+
+describe('resolveTargetFormat', () => {
+  test('outputPath extension wins when present', () => {
+    const r = resolveTargetFormat({ outputPath: 'images/foo.png', outputType: 'webp' });
+    expect(r).toEqual({ format: 'png', source: 'extension' });
+  });
+
+  test('outputType used when outputPath has no extension', () => {
+    const r = resolveTargetFormat({ outputPath: 'images/foo', outputType: 'png' });
+    expect(r).toEqual({ format: 'png', source: 'outputType' });
+  });
+
+  test('outputType used when no outputPath', () => {
+    const r = resolveTargetFormat({ outputType: 'webp' });
+    expect(r).toEqual({ format: 'webp', source: 'outputType' });
+  });
+
+  test('default webp when neither given', () => {
+    const r = resolveTargetFormat({});
+    expect(r).toEqual({ format: 'webp', source: 'default' });
+  });
+
+  test('outputType "jpg" canonicalizes to jpeg', () => {
+    expect(resolveTargetFormat({ outputType: 'jpg' }).format).toBe('jpeg');
+  });
+
+  test('invalid extension falls through to outputType / default', () => {
+    expect(resolveTargetFormat({ outputPath: 'foo.tiff', outputType: 'png' })).toEqual({
+      format: 'png', source: 'outputType',
+    });
+    expect(resolveTargetFormat({ outputPath: 'foo.tiff' })).toEqual({
+      format: 'webp', source: 'default',
+    });
+  });
+
+  test('outputPath extension wins even over a contradictory outputType', () => {
+    // An agent that says outputPath: "x.webp" + outputType: "png" probably
+    // typo'd one; the path is the clearer signal — honor it.
+    expect(resolveTargetFormat({ outputPath: 'foo.webp', outputType: 'png' })).toEqual({
+      format: 'webp', source: 'extension',
+    });
+  });
+});
+
+describe('detectFormatFromBytes', () => {
+  test('PNG signature', () => {
+    const buf = Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0,0,0,0]);
+    expect(detectFormatFromBytes(buf)).toBe('png');
+  });
+  test('JPEG signature', () => {
+    const buf = Buffer.from([0xFF, 0xD8, 0xFF, 0xE0, 0,0,0,0,0,0,0,0]);
+    expect(detectFormatFromBytes(buf)).toBe('jpeg');
+  });
+  test('WebP signature (RIFF...WEBP)', () => {
+    const buf = Buffer.from([
+      0x52, 0x49, 0x46, 0x46,    // RIFF
+      0,0,0,0,                   // size (4 bytes)
+      0x57, 0x45, 0x42, 0x50,    // WEBP
+    ]);
+    expect(detectFormatFromBytes(buf)).toBe('webp');
+  });
+  test('GIF signature', () => {
+    const buf = Buffer.concat([Buffer.from('GIF89a'), Buffer.alloc(8)]);
+    expect(detectFormatFromBytes(buf)).toBe('gif');
+  });
+  test('BMP signature', () => {
+    const buf = Buffer.from([0x42, 0x4D, 0,0,0,0,0,0,0,0,0,0]);
+    expect(detectFormatFromBytes(buf)).toBe('bmp');
+  });
+  test('unknown bytes → null', () => {
+    expect(detectFormatFromBytes(Buffer.from([0,0,0,0,0,0,0,0,0,0,0,0]))).toBe(null);
+  });
+  test('too-small buffer → null (defensive)', () => {
+    expect(detectFormatFromBytes(Buffer.from([0x89]))).toBe(null);
+  });
+  test('non-buffer → null', () => {
+    expect(detectFormatFromBytes(null)).toBe(null);
+    expect(detectFormatFromBytes('string')).toBe(null);
+    expect(detectFormatFromBytes(undefined)).toBe(null);
+  });
+});
+
+describe('ensureExtension', () => {
+  test('appends extension when missing', () => {
+    expect(ensureExtension('images/foo', 'webp')).toBe('images/foo.webp');
+    expect(ensureExtension('images/foo', 'png')).toBe('images/foo.png');
+    expect(ensureExtension('images/foo', 'jpeg')).toBe('images/foo.jpg');
+  });
+  test('leaves existing valid extension alone', () => {
+    expect(ensureExtension('images/foo.webp', 'png')).toBe('images/foo.webp');
+    expect(ensureExtension('images/foo.png', 'webp')).toBe('images/foo.png');
+  });
+  test('appends when extension is unknown (e.g. .bak)', () => {
+    expect(ensureExtension('foo.bak', 'webp')).toBe('foo.bak.webp');
+  });
+  test('null/empty → returned as-is', () => {
+    expect(ensureExtension('', 'webp')).toBe('');
+    expect(ensureExtension(null, 'webp')).toBe(null);
+  });
+});
+
+describe('transcodeIfNeeded — short-circuits without invoking sharp', () => {
+  test('input format already matches target → returns input bytes unchanged', async () => {
+    const png = Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0,0,0,0]);
+    const r = await transcodeIfNeeded(png, 'png');
+    expect(r.transcoded).toBe(false);
+    expect(r.reason).toBe('already-target');
+    expect(r.buffer).toBe(png);
+    expect(r.inputFormat).toBe('png');
+  });
+
+  test('unknown input format → writes bytes as-is, reason "unknown-input"', async () => {
+    const garbage = Buffer.alloc(64, 0x00);
+    const r = await transcodeIfNeeded(garbage, 'webp');
+    expect(r.transcoded).toBe(false);
+    expect(r.reason).toBe('unknown-input');
+    expect(r.buffer).toBe(garbage);
+  });
+
+  test('GIF input → reason "unsupported-input" (we don\'t transcode animations)', async () => {
+    const gif = Buffer.concat([Buffer.from('GIF89a'), Buffer.alloc(8)]);
+    const r = await transcodeIfNeeded(gif, 'webp');
+    expect(r.transcoded).toBe(false);
+    expect(r.reason).toBe('unsupported-input');
+    expect(r.inputFormat).toBe('gif');
+    expect(r.buffer).toBe(gif);
+  });
+});
+
+describe('transcodeIfNeeded — sharp-unavailable fallback', () => {
+  // Sharp may legitimately fail to load on platforms without prebuilt
+  // binaries. The module's design is to NEVER fail the render — fall
+  // back to writing raw bytes. We can't easily simulate sharp failure
+  // without complex module mocking, so the contract is pinned by the
+  // existing reason-code structure (also documented in the helper's
+  // JSDoc). When sharp IS available + transcode succeeds, the result
+  // shape is { transcoded: true, ... } — covered by integration tests
+  // that run with sharp present.
+
+  test('result shape is documented in the function — every failure path returns a buffer', async () => {
+    // Exercise once with PNG → WebP. Two outcomes are valid:
+    //   - sharp loaded → transcoded: true, reason undefined
+    //   - sharp unavailable → transcoded: false, reason 'sharp-unavailable'
+    // EITHER way, .buffer is non-null and .outputFormat is 'webp'.
+    const png = Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0,0,0,0]);
+    const r = await transcodeIfNeeded(png, 'webp');
+    expect(Buffer.isBuffer(r.buffer)).toBe(true);
+    expect(r.outputFormat).toBe('webp');
+    expect(r.inputFormat).toBe('png');
+    if (!r.transcoded) {
+      // Acceptable failure modes for this 12-byte fake buffer:
+      //  - sharp-unavailable (CI / weird host)
+      //  - transcode-failed  (sharp is loaded but rejects 12-byte fake PNG)
+      //  - unknown-input     (some readers may not recognize a header-only buffer)
+      expect(['sharp-unavailable', 'transcode-failed', 'unknown-input']).toContain(r.reason);
+    }
+  });
+});