onbuzz 4.5.0 → 4.6.0

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,
+};

package/src/tools/imageTool.js

@@ -8,6 +8,13 @@ import os from 'os';
 import { promises as fs } from 'fs';
 import { BaseTool } from './baseTool.js';
 import { getGalleryService } from '../services/galleryService.js';
+import {
+  resolveTargetFormat,
+  transcodeIfNeeded,
+  extensionFor,
+  ensureExtension,
+  DEFAULT_FORMAT,
+} from './imageFormat.js';
 
 /**
  * Configuration constants for image generation
@@ -224,19 +231,37 @@ export class ImageTool extends BaseTool {
 - Just output the command when you want to generate or edit an image
 - If generation fails, output a NEW command with corrections
 
-**USAGE — Generate:**
+**USAGE — Generate (default WebP):**
 \`\`\`json
 {
   "toolId": "image-gen",
   "parameters": {
     "prompt": "Detailed description of the image",
-    "outputPath": "images/filename.png",
+    "outputPath": "images/filename.webp",
     "size": "1024x1024"
   }
 }
 \`\`\`
 
-**USAGE — Generate with Transparency:**
+**USAGE — Force PNG output (when you specifically need lossless / older-tool compat):**
+\`\`\`json
+{
+  "toolId": "image-gen",
+  "parameters": {
+    "prompt": "Pixel-art icon set on white",
+    "outputPath": "images/icons.png"
+  }
+}
+\`\`\`
+Or, equivalently, with the explicit field:
+\`\`\`json
+{
+  "toolId": "image-gen",
+  "parameters": { "prompt": "Pixel-art icon set", "outputType": "png" }
+}
+\`\`\`
+
+**USAGE — Generate with Transparency (WebP supports alpha):**
 \`\`\`json
 {
   "toolId": "image-gen",
@@ -244,7 +269,7 @@ export class ImageTool extends BaseTool {
     "prompt": "A cute fox mascot on a transparent background",
     "model": "gpt-image-1.5",
     "transparency": true,
-    "outputPath": "images/fox-mascot.png"
+    "outputPath": "images/fox-mascot.webp"
   }
 }
 \`\`\`
@@ -257,14 +282,19 @@ export class ImageTool extends BaseTool {
     "prompt": "Remove the background and make it transparent",
     "sourceImage": "images/photo.png",
     "model": "gpt-image-1.5",
-    "outputPath": "images/photo-nobg.png"
+    "outputPath": "images/photo-nobg.webp"
   }
 }
 \`\`\`
+(The \`sourceImage\` can be any common format — PNG, JPEG, WebP, etc. The OUTPUT format is whatever you specify on \`outputPath\` / \`outputType\`, defaulting to WebP.)
 
 **Parameters:**
 - **prompt** (required): Description of image to generate OR editing instruction
 - **outputPath** (optional): Path to save image (permanent). Omit for temp file.
+  The file extension determines output format (.webp / .png / .jpg / .jpeg).
+- **outputType** (optional): Explicit format request when outputPath has no extension
+  or is omitted: 'webp' | 'png' | 'jpg' | 'jpeg'. Default: 'webp'.
+  An outputPath extension always wins over outputType if both are present.
 - **size** (optional): WIDTHxHEIGHT or preset name. DIFFERENT MODELS ACCEPT DIFFERENT SIZES — read the rules below. Default: 1024x1024.
 - **quality** (optional): "standard" or "hd" (default: standard)
 - **model** (optional): "gpt-image-1.5" or a flux variant. Default: auto. Auto-switches to gpt-image-1.5 if transparency=true OR sourceImage is set.
@@ -272,6 +302,13 @@ export class ImageTool extends BaseTool {
 - **mask** (optional): Path to mask image for editing (white=edit area, black=keep area)
 - **transparency** (optional): true to generate with transparent background (forces gpt-image-1.5)
 
+**Output format (NEW default: WebP):**
+The tool transcodes provider bytes (typically PNG) into WebP by default —
+smaller files, same visual quality. Force PNG with either an explicit
+.png extension on outputPath OR \`outputType: "png"\`. Pick PNG when you
+need lossless graphics or animated GIFs would otherwise be needed; WebP
+is the better default for photo-style outputs.
+
 ⚠ SIZE RULES — read before picking a size:
 
   (A) gpt-image-1.5 (auto-selected on transparency=true or sourceImage, or set explicitly):
@@ -391,10 +428,15 @@ Content moderation:
    */
   _parseImageParams(obj) {
     const outputPath = obj.outputPath || obj['output-path'] || null;
+    // Optional explicit format request. Accepts 'webp' (default if no
+    // outputPath ext), 'png', 'jpg' / 'jpeg'. The outputPath extension
+    // wins if both are present (handled in resolveTargetFormat).
+    const outputType = obj.outputType || obj['output-type'] || obj.format || null;
 
     return {
       prompt: obj.prompt || '',
       outputPath: outputPath,
+      outputType: outputType,
       saveToProject: outputPath !== null, // If path specified, save to project
       model: obj.model || IMAGE_CONFIG.DEFAULT_MODEL,
       size: obj.size || IMAGE_CONFIG.DEFAULT_SIZE,
@@ -417,10 +459,12 @@ Content moderation:
     };
 
     const outputPath = extractTag('output-path') || null;
+    const outputType = extractTag('output-type') || extractTag('format') || null;
 
     return {
       prompt: extractTag('prompt') || '',
       outputPath: outputPath,
+      outputType: outputType,
       saveToProject: outputPath !== null, // If path specified, save to project
       model: extractTag('model') || IMAGE_CONFIG.DEFAULT_MODEL,
       size: extractTag('size') || IMAGE_CONFIG.DEFAULT_SIZE,
@@ -468,6 +512,10 @@ Content moderation:
           sessionId,
           prompt: imageParams.prompt,
           outputPath: imageParams.outputPath,
+          // Explicit format request — used by the save path to decide the
+          // target format. Default behavior (no outputPath, no outputType):
+          // WebP. See imageFormat.resolveTargetFormat for precedence.
+          outputType: imageParams.outputType || null,
           saveToProject: imageParams.saveToProject,
           model: imageParams.model,
           size: imageParams.size,
@@ -1046,10 +1094,23 @@ Content moderation:
 
     try {
       if (b64Json) {
-        // Flux/GPT-Image response: Save base64 directly to disk
+        // Flux/GPT-Image response: Save base64 to disk, transcoding to
+        // the resolved target format (default webp). If transcoding
+        // fails, the helper falls back to writing original bytes — the
+        // call doesn't fail, but a warning is logged via the logger.
         this.logger?.info(`Saving base64 image to disk: ${resolvedOutputPath}`);
-        const imageBuffer = Buffer.from(b64Json, 'base64');
-        await fs.writeFile(resolvedOutputPath, imageBuffer);
+        const rawBuffer = Buffer.from(b64Json, 'base64');
+        const transcode = await transcodeIfNeeded(rawBuffer, job._targetFormat || DEFAULT_FORMAT, {
+          quality: 85, logger: this.logger,
+        });
+        await fs.writeFile(resolvedOutputPath, transcode.buffer);
+        if (transcode.transcoded) {
+          this.logger?.info(`Image transcoded ${transcode.inputFormat} → ${transcode.outputFormat}`, {
+            outputPath: resolvedOutputPath,
+            inputBytes:  rawBuffer.length,
+            outputBytes: transcode.buffer.length,
+          });
+        }
 
         // Verify the file was actually written
         const stat = await fs.stat(resolvedOutputPath);
@@ -1063,9 +1124,9 @@ Content moderation:
         // For web display, we'll use our local server endpoint (set below)
         displayUrl = null; // Will be converted to web URL later
       } else if (imageUrl) {
-        // URL response: Download from URL
+        // URL response: Download from URL, then transcode to target format.
         this.logger?.info(`Downloading image from URL: ${imageUrl.substring(0, 50)}...`);
-        await this._downloadImage(imageUrl, resolvedOutputPath);
+        await this._downloadImage(imageUrl, resolvedOutputPath, job._targetFormat || DEFAULT_FORMAT);
 
         // Verify the file was actually written
         const stat = await fs.stat(resolvedOutputPath);
@@ -1114,15 +1175,30 @@ Content moderation:
    * @private
    */
   async _resolveOutputPath(job) {
+    // Resolve target format ONCE here so the auto-generated filename
+    // uses the right extension. Caller should also use job._targetFormat
+    // (cached on the job) when transcoding bytes.
+    const { format: targetFormat } = resolveTargetFormat({
+      outputPath: job.outputPath,
+      outputType: job.outputType,
+    });
+    job._targetFormat = targetFormat;
+    const ext = extensionFor(targetFormat);
+
     if (job.saveToProject) {
       // Save to project directory
       const projectDir = job.projectDir || process.cwd();
 
       let outputPath = job.outputPath;
       if (!outputPath) {
-        // Auto-generate filename
+        // Auto-generate filename — DEFAULT format is webp now (was png).
+        // Agents that need PNG must pass an explicit outputPath with
+        // .png extension OR outputType:'png'.
         const timestamp = Date.now();
-        outputPath = `images/generated-${timestamp}.png`;
+        outputPath = `images/generated-${timestamp}.${ext}`;
+      } else {
+        // Append format extension when the agent supplied a name without one
+        outputPath = ensureExtension(outputPath, targetFormat);
       }
 
       const resolvedPath = path.isAbsolute(outputPath)
@@ -1149,9 +1225,10 @@ Content moderation:
       // Save to temp directory
       await fs.mkdir(this.tempDir, { recursive: true });
 
+      // Temp dir path — same default-extension policy as project save.
       let filename = job.outputPath
-        ? path.basename(job.outputPath)
-        : `generated-${job.jobId}.png`;
+        ? path.basename(ensureExtension(job.outputPath, targetFormat))
+        : `generated-${job.jobId}.${ext}`;
 
       return path.join(this.tempDir, filename);
     }
@@ -1161,7 +1238,7 @@ Content moderation:
    * Download image from URL
    * @private
    */
-  async _downloadImage(imageUrl, outputPath) {
+  async _downloadImage(imageUrl, outputPath, targetFormat = DEFAULT_FORMAT) {
     try {
       const response = await fetch(imageUrl, {
         signal: AbortSignal.timeout(IMAGE_CONFIG.DOWNLOAD_TIMEOUT)
@@ -1172,9 +1249,21 @@ Content moderation:
       }
 
       const buffer = Buffer.from(await response.arrayBuffer());
-      await fs.writeFile(outputPath, buffer);
-
-      this.logger?.info(`Image saved to: ${outputPath}`);
+      // Transcode to target format if needed (defensive: fallback writes
+      // original bytes if sharp can't load — see imageFormat.js).
+      const transcode = await transcodeIfNeeded(buffer, targetFormat, {
+        quality: 85, logger: this.logger,
+      });
+      await fs.writeFile(outputPath, transcode.buffer);
+      if (transcode.transcoded) {
+        this.logger?.info(`Downloaded image transcoded ${transcode.inputFormat} → ${transcode.outputFormat}`, {
+          outputPath,
+          inputBytes:  buffer.length,
+          outputBytes: transcode.buffer.length,
+        });
+      } else {
+        this.logger?.info(`Image saved to: ${outputPath}`);
+      }
 
     } catch (error) {
       if (error.name === 'TimeoutError') {

package/src/tools/jobDoneTool.js

@@ -178,6 +178,18 @@ IMPORTANT - COMPLETION TIMING: - Call this tool IMMEDIATELY when your task is co
               details: {
                 type: 'string',
                 description: 'Optional: Additional details about what was done, what failed, any files created, or next steps for the user'
+              },
+              outputs: {
+                // v2 flows: when this agent is running inside a flow node
+                // that declares typed outputs, populate this object with
+                // each declared field. Runtime validation rejects missing
+                // fields and triggers a retry — schema is permissive but
+                // runtime is strict. The text below is what the LLM sees
+                // alongside REQUIRED OUTPUTS in the system prompt; phrased
+                // strongly so model defaults toward including it.
+                type: 'object',
+                description: 'REQUIRED when your system prompt contains a "REQUIRED OUTPUTS" section (i.e. you are in a flow). Provide a JSON object with one key per declared output field name, holding the value matching the declared type. Example: if REQUIRED OUTPUTS lists "draft (text), wordCount (number)", emit outputs: { "draft": "<full text>", "wordCount": 850 }. Omitting any required field causes the flow node to fail and retry. Outside of flows this field is ignored.',
+                additionalProperties: true
               }
             },
             required: ['action', 'summary'],
@@ -217,6 +229,90 @@ IMPORTANT - COMPLETION TIMING: - Call this tool IMMEDIATELY when your task is co
       }
 
       const agentId = context.agentId;
+
+      // Phase 8: when this agent is running inside a flow node with
+      // declared outputs, validate action.outputs against the contract
+      // BEFORE signaling completion. Returning a tool error here gives
+      // the model immediate feedback in its current response cycle —
+      // it can re-call jobdone with the missing fields populated, no
+      // executor round-trip, no conversation reset.
+      //
+      // Falls through (no validation) when not in a flow OR when the
+      // node has no declared outputs — keeps non-flow uses untouched.
+      let activeFlowContract = null;
+      if (this.flowExecutor && agentId && typeof this.flowExecutor.getActiveContract === 'function') {
+        activeFlowContract = this.flowExecutor.getActiveContract(agentId);
+      }
+      if (activeFlowContract) {
+        const contract = activeFlowContract;
+        if (contract && Array.isArray(contract.outputs) && contract.outputs.length > 0) {
+          const provided = (action.outputs && typeof action.outputs === 'object') ? action.outputs : {};
+          const missing = [];
+          for (const decl of contract.outputs) {
+            if (!decl || typeof decl.name !== 'string') continue;
+            if (!(decl.name in provided) || provided[decl.name] === null || provided[decl.name] === undefined) {
+              missing.push(decl);
+            }
+          }
+          if (missing.length > 0) {
+            const declList = contract.outputs
+              .map(o => `  • ${o.name}: ${o.type}${o.description ? ` — ${o.description}` : ''}`).join('\n');
+            const exampleEntries = contract.outputs.map(o => {
+              let exVal = '<value>';
+              if (o.example !== undefined && o.example !== null) {
+                try { exVal = JSON.stringify(o.example); } catch {}
+              } else {
+                // Type-specific placeholders
+                if (o.type === 'text')          exVal = '"<your text>"';
+                else if (o.type === 'number')   exVal = '0';
+                else if (o.type === 'boolean')  exVal = 'true';
+                else if (o.type === 'json')     exVal = '{ "key": "value" }';
+                else if (o.type === 'file')     exVal = '"/path/to/file"';
+                else if (o.type === 'file[]')   exVal = '["/path/to/file"]';
+                else if (o.type === 'list<text>') exVal = '["item 1", "item 2"]';
+              }
+              return `      "${o.name}": ${exVal}`;
+            }).join(',\n');
+            const errorMsg =
+              `Cannot complete: missing required output field(s): ${missing.map(m => m.name).join(', ')}.
+
+This step's flow node declares ALL of these outputs:
+${declList}
+
+Re-call jobdone with EVERY field above populated in the "outputs" object.
+Use this exact shape (replace placeholder values with your real content):
+
+{
+  "toolId": "jobdone",
+  "actions": [{
+    "action": "complete",
+    "summary": "<your summary>",
+    "outputs": {
+${exampleEntries}
+    }
+  }]
+}
+
+The flow CANNOT proceed until all required output fields are populated.`;
+
+            this.logger?.info(`JobDone: Rejected — flow contract missing outputs`, {
+              agentId,
+              missing: missing.map(m => m.name),
+              declared: contract.outputs.map(o => o.name),
+            });
+
+            return {
+              success: false,
+              error: errorMsg,
+              output: errorMsg,
+              taskComplete: false,
+              flowContractViolation: true,
+              missingOutputs: missing.map(m => m.name),
+            };
+          }
+        }
+      }
+
       let agent = null;
       let agentInfo = '';
 
@@ -239,7 +335,16 @@ IMPORTANT - COMPLETION TIMING: - Call this tool IMMEDIATELY when your task is co
       // If there are pending tasks and the agent claims success, reject.
       // The agent must clear/complete its task list first.
       // Exception: success=false means the agent is giving up (stuck/unable to proceed).
-      if (pendingTasks.length > 0 && action.success !== false) {
+      //
+      // Flow exception: when this agent is running inside a flow node, the
+      // Phase 8 contract validation above is the authoritative gate. The
+      // task list contains scheduler-poke artifacts (auto-created from
+      // queued user messages) that aren't real "user-tracked work" — they
+      // exist purely so the scheduler picks the agent up. Letting the
+      // legacy pendingTasks check fire here would block legitimate
+      // contract-correct job-done calls and force the agent into a
+      // taskmanager dance for tasks the user never actually authored.
+      if (pendingTasks.length > 0 && action.success !== false && !activeFlowContract) {
         const taskListStr = pendingTasks
           .map((t, i) => `${i + 1}. [${t.status}] ${t.title}`)
           .join('\n');
@@ -284,12 +389,15 @@ IMPORTANT - COMPLETION TIMING: - Call this tool IMMEDIATELY when your task is co
           agent.lastCompletionDetails = action.details || null;
           await this.agentPool.persistAgentState(agentId);
 
-          // Signal flow executor directly (if agent is running inside a flow)
+          // Signal flow executor directly (if agent is running inside a flow).
+          // v2: forward structured `outputs` bag verbatim — the executor
+          // validates it against the node's declared contract.
           if (this.flowExecutor) {
             this.flowExecutor.notifyAgentCompletion(agentId, {
               summary: action.summary,
               details: action.details,
-              success: isSuccessful
+              success: isSuccessful,
+              outputs: action.outputs
             });
           }