onbuzz 4.5.0 → 4.6.1

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
             });
           }
 

package/src/tools/platformControl/permissions.js

@@ -222,6 +222,88 @@ export function filterMutableAgents(level, callerAgentId, agents, opts = {}) {
   return agents.filter(a => checkAgentMutationAccess(level, callerAgentId, a, opts).allow);
 }
 
+// ─── Flow CRUD permissions ───────────────────────────────────────────
+//
+// Flows are user-authored multi-agent pipelines (typed I/O, retry,
+// versioned, runnable on schedule). Permission model mirrors agents:
+// `disabled` (default), `self-created` (only your own flows), or
+// `all` (admin scope). Hard rules layered on top:
+//   - flows referencing the caller as a node are still creatable; we
+//     don't try to detect "self-trapping" flows here. The executor
+//     handles wedged-lock cases via the agent processing lock.
+//   - delete cascades the run history + checkpoints + versions (the
+//     cascade itself lives in cascadeService.js, not this file).
+
+export const FLOW_ACCESS_LEVELS = Object.freeze({
+  DISABLED:     'disabled',
+  SELF_CREATED: 'self-created',
+  ALL:          'all',
+});
+
+const VALID_FLOW_LEVELS = new Set(Object.values(FLOW_ACCESS_LEVELS));
+
+/**
+ * Resolve the per-agent `flows` permission level. Default `'disabled'`;
+ * unknown values collapse to `'disabled'` (no silent grant).
+ */
+export function getFlowAccessLevel(toolConfig) {
+  const v = toolConfig && typeof toolConfig === 'object' ? toolConfig.flows : undefined;
+  if (!VALID_FLOW_LEVELS.has(v)) return FLOW_ACCESS_LEVELS.DISABLED;
+  return v;
+}
+
+/**
+ * Per-creator flow quota. Same semantics as `maxAgentsCreated`:
+ * `null` = unlimited; non-finite / negative collapses to unlimited.
+ * The actual cap is enforced in the create-flow path.
+ */
+export function getMaxFlowsCreated(toolConfig) {
+  const v = toolConfig && typeof toolConfig === 'object' ? toolConfig.maxFlowsCreated : undefined;
+  if (v == null) return null;
+  if (typeof v !== 'number' || !Number.isFinite(v) || v < 0) return null;
+  return Math.floor(v);
+}
+
+/**
+ * Decide whether `callerAgentId` may MUTATE `targetFlow` at this level.
+ * Mutation = create/update/delete/execute/dry-run. Read (list/get) is
+ * unrestricted at any non-disabled level — same convention as agent.
+ *
+ * Permission-level rules:
+ *   disabled      → never
+ *   self-created  → only when targetFlow.createdBy === callerAgentId
+ *   all           → any flow
+ *
+ * @returns {{ allow: true } | { allow: false, reason: string }}
+ */
+export function checkFlowMutationAccess(level, callerAgentId, targetFlow) {
+  if (level === FLOW_ACCESS_LEVELS.DISABLED) {
+    return { allow: false, reason: 'Flow management is disabled for this caller.' };
+  }
+  if (!targetFlow || !targetFlow.id) {
+    return { allow: false, reason: 'Missing target flow.' };
+  }
+  if (level === FLOW_ACCESS_LEVELS.ALL) return { allow: true };
+  if (level === FLOW_ACCESS_LEVELS.SELF_CREATED) {
+    if (targetFlow.createdBy === callerAgentId) return { allow: true };
+    return {
+      allow: false,
+      reason: 'Out of scope: in "self-created" mode you can only modify flows you have created.',
+    };
+  }
+  return { allow: false, reason: `Unknown permission level: ${level}` };
+}
+
+/**
+ * Filter a list of flows to those reachable for MUTATION by `callerAgentId`
+ * at `level`. Read endpoints should NOT use this filter — the tool exposes
+ * the full list at any non-disabled level.
+ */
+export function filterMutableFlows(level, callerAgentId, flows) {
+  if (!Array.isArray(flows)) return [];
+  return flows.filter(f => checkFlowMutationAccess(level, callerAgentId, f).allow);
+}
+
 // ─── Privilege clamp on toolConfig ───────────────────────────────────
 
 /**
@@ -230,6 +312,7 @@ export function filterMutableAgents(level, callerAgentId, agents, opts = {}) {
  */
 const SCHEDULE_ORDER = { disabled: 0, own: 1, all: 2 };
 const AGENT_ORDER    = { disabled: 0, 'self-created': 1, all: 2 };
+const FLOW_ORDER     = { disabled: 0, 'self-created': 1, all: 2 };
 
 function lower(a, b, order) {
   const ai = order[a] ?? 0;
@@ -256,8 +339,10 @@ function lower(a, b, order) {
 export function clampToolConfigForChild(callerCfg, desiredCfg) {
   const callerSchedule = getScheduleAccessLevel(callerCfg);
   const callerAgents   = getAgentAccessLevel(callerCfg);
+  const callerFlows    = getFlowAccessLevel(callerCfg);
   const callerTeams    = getTeamScope(callerCfg);
   const callerMax      = getMaxAgentsCreated(callerCfg);
+  const callerMaxFlows = getMaxFlowsCreated(callerCfg);
 
   const out = { ...(desiredCfg || {}) };
   const clamps = [];
@@ -294,6 +379,26 @@ export function clampToolConfigForChild(callerCfg, desiredCfg) {
     }
   }
 
+  // flows — same shape as agents.
+  if (desiredCfg && desiredCfg.flows !== undefined) {
+    const wanted = desiredCfg.flows;
+    const allowed = lower(wanted, callerFlows, FLOW_ORDER);
+    if (allowed !== wanted) {
+      out.flows = allowed;
+      clamps.push({ key: 'flows', requested: wanted, clampedTo: allowed });
+    }
+  }
+
+  // maxFlowsCreated — same quota-clamp rule as maxAgentsCreated.
+  if (desiredCfg && desiredCfg.maxFlowsCreated !== undefined && callerMaxFlows !== null) {
+    const wanted = desiredCfg.maxFlowsCreated;
+    const wantedNum = (wanted == null || typeof wanted !== 'number') ? null : wanted;
+    if (wantedNum === null || wantedNum > callerMaxFlows) {
+      out.maxFlowsCreated = callerMaxFlows;
+      clamps.push({ key: 'maxFlowsCreated', requested: wanted, clampedTo: callerMaxFlows });
+    }
+  }
+
   // teams scope — child cannot have any flag the caller doesn't have.
   // 'all' is the strongest; if caller doesn't have 'all', the child
   // can't either.
@@ -389,6 +494,12 @@ export default {
   isTeamAccessDisabled,
   checkTeamAccess,
   filterAccessibleTeams,
+  // flows
+  FLOW_ACCESS_LEVELS,
+  getFlowAccessLevel,
+  getMaxFlowsCreated,
+  checkFlowMutationAccess,
+  filterMutableFlows,
   // clamp
   clampToolConfigForChild,
 };