@jiggai/recipes 0.4.32 → 0.4.34

package/docs/WORKFLOW_RUNS_FILE_FIRST.md

@@ -104,6 +104,9 @@ Use this when you are deciding what kind of node to add:
 - use **`tool`** when you want the workflow to call a tool or side-effecting action
 - use **`human_approval`** when a person must approve before the workflow continues
 - use **`writeback`** when you want to append workflow breadcrumbs/results into team files
+- use **`media-image`** when you want to generate images as part of the workflow
+- use **`media-video`** when you want to generate video content as part of the workflow
+- use **`media-audio`** when you want to generate audio content as part of the workflow
 
 ### `start`
 Purpose:
@@ -370,6 +373,102 @@ Example:
 }
 ```
 
+### `media-image`
+Purpose:
+- generate images using available media generation skills
+
+Use it when:
+- you want to create visual content as part of a workflow
+- you need to generate images from text prompts
+- you want to create marketing visuals or illustrations
+
+Required pieces:
+- `assignedTo.agentId`
+- either `action.image_prompt` or upstream node output with image prompt
+
+What it does:
+- scans available skills for image generation capabilities
+- executes image generation via skill auto-discovery
+- writes generated image data to node outputs
+
+Example:
+
+```json
+{
+  "id": "generate_hero_image",
+  "kind": "media-image",
+  "assignedTo": { "agentId": "development-team-lead" },
+  "action": {
+    "image_prompt": "A modern, clean illustration of a workflow automation dashboard",
+    "mediaType": "image"
+  }
+}
+```
+
+### `media-video`
+Purpose:
+- generate video content using available media generation skills
+
+Use it when:
+- you want to create video content as part of a workflow
+- you need to generate promotional or educational videos
+- you want to create dynamic visual content
+
+Required pieces:
+- `assignedTo.agentId`
+- either `action.video_prompt` or upstream node output with video prompt
+
+What it does:
+- scans available skills for video generation capabilities
+- executes video generation via skill auto-discovery
+- writes generated video data to node outputs
+
+Example:
+
+```json
+{
+  "id": "generate_demo_video",
+  "kind": "media-video",
+  "assignedTo": { "agentId": "development-team-lead" },
+  "action": {
+    "video_prompt": "A 30-second demo of workflow automation in action",
+    "mediaType": "video"
+  }
+}
+```
+
+### `media-audio`
+Purpose:
+- generate audio content using available media generation skills
+
+Use it when:
+- you want to create audio content as part of a workflow
+- you need to generate voiceovers or music
+- you want to create podcast content or audio narration
+
+Required pieces:
+- `assignedTo.agentId`
+- either `action.audio_prompt` or upstream node output with audio prompt
+
+What it does:
+- scans available skills for audio generation capabilities
+- executes audio generation via skill auto-discovery
+- writes generated audio data to node outputs
+
+Example:
+
+```json
+{
+  "id": "generate_voiceover",
+  "kind": "media-audio",
+  "assignedTo": { "agentId": "development-team-lead" },
+  "action": {
+    "audio_prompt": "Professional voiceover explaining our new feature launch",
+    "mediaType": "audio"
+  }
+}
+```
+
 ---
 
 ## What is **not** currently a first-class built-in node type?

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "recipes",
   "name": "Recipes",
   "description": "Markdown recipes that scaffold agents and teams (workspace-local).",
-  "version": "0.4.32",
+  "version": "0.4.34",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jiggai/recipes",
-  "version": "0.4.32",
+  "version": "0.4.34",
   "description": "ClawRecipes plugin for OpenClaw (markdown recipes -> scaffold agents/teams)",
   "main": "index.ts",
   "type": "commonjs",

package/src/lib/workflows/workflow-worker.ts

@@ -399,7 +399,38 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
       
       // Apply template variable replacement
       const prompt = templateReplace(promptRaw, vars);
-      
+
+      // Build output format instructions from outputFields when defined
+      const nodeConfig = asRecord((node as unknown as Record<string, unknown>)['config']);
+      const outputFields = Array.isArray(nodeConfig['outputFields']) ? nodeConfig['outputFields'] as Array<Record<string, string>> : [];
+      const validFields = outputFields.filter(f => typeof f === 'object' && f && typeof f['name'] === 'string' && f['name'].trim());
+
+      let outputFormatBlock: string;
+      if (validFields.length > 0) {
+        const fieldDescriptions = validFields.map(f => {
+          const name = String(f['name']).trim();
+          const type = String(f['type'] ?? 'text').trim();
+          const typeHint = type === 'list' ? '(array of strings)'
+                         : type === 'json' ? '(JSON object)'
+                         : '(string)';
+          return `  - "${name}" ${typeHint}`;
+        }).join('\n');
+        outputFormatBlock = [
+          'Return a JSON object with EXACTLY these fields:',
+          fieldDescriptions,
+          '',
+          'Rules:',
+          '- Return ONLY the JSON object, no markdown fences or explanation.',
+          '- Every field listed above MUST be present in your response.',
+          '- "text" fields → string values.',
+          '- "list" fields → arrays of strings.',
+          '- "json" fields → nested JSON objects.',
+          '- You may include additional fields if genuinely useful, but the listed fields are required.',
+        ].join('\n');
+      } else {
+        outputFormatBlock = 'Return ONLY the final content (the worker will store it as JSON).';
+      }
+
       const taskText = [
         `You are executing a workflow run for teamId=${teamId}.`,
         `Workflow: ${workflow.name ?? workflow.id ?? workflowFile}`,
@@ -408,7 +439,7 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
         `\n---\nPROMPT TEMPLATE\n---\n`,
         prompt.trim(),
         `\n---\nOUTPUT FORMAT\n---\n`,
-        `Return ONLY the final content (the worker will store it as JSON).`,
+        outputFormatBlock,
       ].join('\n');
 
       let text = '';
@@ -436,6 +467,30 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
         const memoryContext = await buildMemoryContext(teamDir);
         const promptWithMemory = memoryContext ? `${memoryContext}\n\n${taskText}` : taskText;
 
+        // Build JSON Schema from outputFields for structured validation
+        let outputSchema: Record<string, unknown> | undefined;
+        if (validFields.length > 0) {
+          const properties: Record<string, Record<string, unknown>> = {};
+          const required: string[] = [];
+          for (const f of validFields) {
+            const name = String(f['name']).trim();
+            const type = String(f['type'] ?? 'text').trim();
+            required.push(name);
+            if (type === 'list') {
+              properties[name] = { type: 'array', items: { type: 'string' } };
+            } else if (type === 'json') {
+              properties[name] = { type: 'object' };
+            } else {
+              properties[name] = { type: 'string' };
+            }
+          }
+          outputSchema = {
+            type: 'object',
+            properties,
+            required,
+          };
+        }
+
         const llmRes = await toolsInvoke<unknown>(api, {
           tool: 'llm-task',
           action: 'json',
@@ -445,6 +500,7 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
             timeoutMs,
             ...(provider ? { provider } : {}),
             ...(model ? { model } : {}),
+            ...(outputSchema ? { schema: outputSchema } : {}),
           },
         });
 
@@ -956,11 +1012,14 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
         const timeoutMsRaw = Number(asString(config['timeoutMs'] ?? '300000'));
         const timeoutMs = Number.isFinite(timeoutMsRaw) && timeoutMsRaw > 0 ? timeoutMsRaw : 300000;
 
-        // ── Step 1: Prompt refinement (optional — skip for images, use llm-task for video) ──
+        // ── Step 1: Prompt refinement (optional) ──
+        // skipRefinement: when the upstream LLM already produced a clean brief,
+        // skip the extra llm-task call that tends to over-elaborate.
+        const skipRefinement = String(config['skipRefinement'] ?? config['skip_refinement'] ?? 'false').toLowerCase() === 'true';
         let refinedPrompt = prompt.trim();
 
-        if (mediaType !== 'image') {
-          // Only use llm-task refinement for non-image media (video/audio)
+        if (!skipRefinement && mediaType !== 'image') {
+          // Use llm-task refinement for non-image media (video/audio)
           const step1Text = [
             `You are a media prompt engineer for teamId=${teamId}.`,
             `Workflow: ${workflow.name ?? workflow.id ?? workflowFile}`,
@@ -1066,18 +1125,64 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
           try {
             const cfgRaw = await fs.readFile(path.join(homedir, '.openclaw', 'openclaw.json'), 'utf8');
             const cfgParsed = JSON.parse(cfgRaw);
-            if (cfgParsed?.env && typeof cfgParsed.env === 'object') {
+
+            // openclaw.json supports multiple shapes historically:
+            // - { env: { KEY: "..." } }
+            // - { env: { vars: { KEY: "..." } } }  (current)
+            const envBlock = (cfgParsed as any)?.env;
+            const maybeVars = envBlock && typeof envBlock === 'object' ? (envBlock as any).vars : null;
+            const rawVars = (maybeVars && typeof maybeVars === 'object') ? maybeVars : envBlock;
+
+            if (rawVars && typeof rawVars === 'object') {
               configEnv = Object.fromEntries(
-                Object.entries(cfgParsed.env).filter(([, v]) => typeof v === 'string')
+                Object.entries(rawVars).filter(([, v]) => typeof v === 'string')
               ) as Record<string, string>;
             }
           } catch { /* config read failed — proceed with process.env only */ }
 
-          const runner = scriptPath.endsWith('.py') ? 'python3' : 'bash';
-          const scriptOutput = execSync(
-            `${runner} ${JSON.stringify(scriptPath)}`,
-            { cwd: mediaDir, timeout: timeoutMs, encoding: 'utf8', input: refinedPrompt, env: { ...process.env, ...configEnv, HOME: homedir } }
-          ).trim();
+          // If the .py script has a venv alongside it, use that Python; otherwise system python3.
+          let runner = 'bash';
+          if (scriptPath.endsWith('.py')) {
+            const scriptDir = path.dirname(scriptPath);
+            const venvPython = path.join(scriptDir, '.venv', 'bin', 'python');
+            try {
+              await fs.access(venvPython);
+              runner = venvPython;
+            } catch {
+              runner = 'python3';
+            }
+          }
+
+          let scriptOutput = '';
+          try {
+            scriptOutput = execSync(
+              `${runner} ${JSON.stringify(scriptPath)}`,
+              {
+                cwd: mediaDir,
+                timeout: timeoutMs,
+                encoding: 'utf8',
+                input: refinedPrompt,
+                env: {
+                  ...process.env,
+                  ...configEnv,
+                  HOME: homedir,
+                  MEDIA_OUTPUT_DIR: mediaDir,
+                },
+              }
+            ).trim();
+          } catch (err) {
+            // Surface stderr/stdout to make debugging skill scripts possible.
+            // execSync throws an Error with extra fields: stdout/stderr (Buffer|string)
+            const e = err as any;
+            const stdout = typeof e?.stdout === 'string' ? e.stdout : (Buffer.isBuffer(e?.stdout) ? e.stdout.toString('utf8') : '');
+            const stderr = typeof e?.stderr === 'string' ? e.stderr : (Buffer.isBuffer(e?.stderr) ? e.stderr.toString('utf8') : '');
+            const msg = [
+              e?.message ? String(e.message) : 'Skill script failed',
+              stdout ? `\n--- stdout ---\n${stdout.trim()}` : '',
+              stderr ? `\n--- stderr ---\n${stderr.trim()}` : '',
+            ].filter(Boolean).join('');
+            throw new Error(msg);
+          }
 
           // Parse the output — skill scripts print "MEDIA:/path/to/file"
           const mediaMatch = scriptOutput.match(/MEDIA:(.+)$/m);