@jiggai/recipes 0.4.33 → 0.4.35

package/docs/WORKFLOW_RUNS_FILE_FIRST.md

@@ -3,6 +3,8 @@
 This document explains how ClawRecipes workflows work in practice.
 
 If you want a copy-paste cookbook after reading this reference, also see:
+
+- [WORKFLOW_NODES.md](WORKFLOW_NODES.md) — runtime node config reference (LLM/media/tool/approval)
 - [WORKFLOW_EXAMPLES.md](WORKFLOW_EXAMPLES.md)
 
 If you are trying to answer any of these questions, start here:
@@ -104,6 +106,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 +375,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/index.ts

@@ -47,6 +47,7 @@ import { handleScaffold, scaffoldAgentFromRecipe } from "./src/handlers/scaffold
 import { handleAddRoleToTeam } from "./src/handlers/team-add-role";
 import { reconcileRecipeCronJobs } from "./src/handlers/cron";
 import { handleWorkflowsApprove, handleWorkflowsPollApprovals, handleWorkflowsResume, handleWorkflowsRun, handleWorkflowsRunnerOnce, handleWorkflowsRunnerTick, handleWorkflowsWorkerTick } from "./src/handlers/workflows";
+import { handleMediaDriversList } from "./src/handlers/media-drivers";
 import { listRecipeFiles, loadRecipeById, workspacePath } from "./src/lib/recipes";
 import {
   executeWorkspaceCleanup,
@@ -728,6 +729,14 @@ workflows
             console.log(JSON.stringify(res, null, 2));
           });
 
+        workflows
+          .command("media-drivers")
+          .description("List available media generation drivers with env-var availability")
+          .action(async () => {
+            const drivers = await handleMediaDriversList();
+            console.log(JSON.stringify(drivers));
+          });
+
         workflows
           .command("poll-approvals")
           .description("Auto-resume any workflow runs whose approval decision has been recorded (approved/rejected)")

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.33",
+  "version": "0.4.35",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

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

package/src/handlers/media-drivers.ts

@@ -0,0 +1,49 @@
+import { getAllDrivers, isDriverAvailable } from '../lib/workflows/media-drivers/registry';
+import { loadConfigEnv } from '../lib/workflows/media-drivers/utils';
+
+export interface DurationConstraintsInfo {
+  minSeconds: number;
+  maxSeconds: number;
+  defaultSeconds: number;
+  stepSeconds?: number;
+}
+
+export interface MediaDriverInfo {
+  slug: string;
+  displayName: string;
+  mediaType: 'image' | 'video' | 'audio';
+  requiredEnvVars: string[];
+  available: boolean;
+  missingEnvVars: string[];
+  durationConstraints: DurationConstraintsInfo | null;
+}
+
+/**
+ * List all known media drivers with availability status.
+ */
+export async function handleMediaDriversList(): Promise<MediaDriverInfo[]> {
+  const configEnv = await loadConfigEnv();
+
+  // Merge process.env (strings only) with config env vars
+  const mergedEnv: Record<string, string> = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (typeof v === 'string') mergedEnv[k] = v;
+  }
+  Object.assign(mergedEnv, configEnv);
+
+  return getAllDrivers().map((driver) => {
+    const available = isDriverAvailable(driver.slug, mergedEnv);
+    const missing = driver.requiredEnvVars.filter(
+      (v) => !mergedEnv[v] || mergedEnv[v].trim().length === 0
+    );
+    return {
+      slug: driver.slug,
+      displayName: driver.displayName,
+      mediaType: driver.mediaType,
+      requiredEnvVars: driver.requiredEnvVars,
+      available,
+      missingEnvVars: missing,
+      durationConstraints: driver.durationConstraints ?? null,
+    };
+  });
+}

package/src/lib/workflows/media-drivers/generic.driver.ts

@@ -0,0 +1,128 @@
+import { MediaDriver, MediaDriverInvokeOpts, MediaDriverResult } from './types';
+import { findSkillDir, findVenvPython, runScript, parseMediaOutput, findScriptInSkill } from './utils';
+
+export class GenericDriver implements MediaDriver {
+  slug: string;
+  mediaType: 'image' | 'video' | 'audio';
+  displayName: string;
+  requiredEnvVars: string[] = [];
+  durationConstraints = null;
+
+  constructor(slug: string, mediaType: 'image' | 'video' | 'audio', displayName?: string) {
+    this.slug = slug;
+    this.mediaType = mediaType;
+    this.displayName = displayName || `Generic ${mediaType} driver for ${slug}`;
+  }
+
+  async invoke(opts: MediaDriverInvokeOpts): Promise<MediaDriverResult> {
+    const { prompt, outputDir, env, timeout } = opts;
+
+    // Find the skill directory
+    const skillDir = await findSkillDir(this.slug);
+    if (!skillDir) {
+      throw new Error(`Skill directory not found for ${this.slug}`);
+    }
+
+    // Determine script candidates based on media type
+    const scriptCandidates = this.mediaType === 'image'
+      ? ['generate_image.py', 'generate_image.sh', 'generate.sh']
+      : this.mediaType === 'video'
+      ? ['generate_video.py', 'generate_video.sh', 'generate.py', 'generate.sh']
+      : ['generate_audio.py', 'generate_audio.sh', 'generate.py', 'generate.sh'];
+
+    // Find the script
+    const scriptPath = await findScriptInSkill(skillDir, scriptCandidates);
+    if (!scriptPath) {
+      throw new Error(`No generation script found in ${skillDir}. Looked for: ${scriptCandidates.join(', ')}`);
+    }
+
+    // Determine runner
+    let runner = 'bash';
+    if (scriptPath.endsWith('.py')) {
+      runner = await findVenvPython(skillDir);
+    }
+
+    // Execute the script with stdin input (most common interface)
+    const scriptOutput = runScript({
+      runner,
+      script: scriptPath,
+      stdin: prompt,
+      env: {
+        ...env,
+        HOME: process.env.HOME || '/home/control',
+      },
+      cwd: outputDir,
+      timeout,
+    });
+
+    // Try to parse MEDIA: output first
+    let filePath = parseMediaOutput(scriptOutput);
+    
+    // If no MEDIA: prefix, try to find the actual file path in the output
+    if (!filePath) {
+      const lines = scriptOutput.split('\n').map(line => line.trim()).filter(Boolean);
+      // Look for lines that look like file paths
+      for (const line of lines.reverse()) {
+        if (line.includes('/') && (line.includes('.') || line.includes(outputDir))) {
+          filePath = line;
+          break;
+        }
+      }
+    }
+    
+    if (!filePath) {
+      throw new Error(`No file path found in script output. Output: ${scriptOutput}`);
+    }
+
+    return {
+      filePath,
+      metadata: {
+        skill: this.slug,
+        prompt,
+        script_output: scriptOutput,
+        script_path: scriptPath,
+      },
+    };
+  }
+
+  /**
+   * Create a generic driver by auto-detecting a skill's capabilities
+   */
+  static async createFromSkill(slug: string): Promise<GenericDriver | null> {
+    const skillDir = await findSkillDir(slug);
+    if (!skillDir) {
+      return null;
+    }
+
+    // Check what types of scripts are available
+    const imageScripts = ['generate_image.py', 'generate_image.sh'];
+    const videoScripts = ['generate_video.py', 'generate_video.sh'];
+    const audioScripts = ['generate_audio.py', 'generate_audio.sh'];
+
+    // Check for image generation capability
+    const imageScript = await findScriptInSkill(skillDir, imageScripts);
+    if (imageScript) {
+      return new GenericDriver(slug, 'image', `${slug} Image Generation`);
+    }
+
+    // Check for video generation capability
+    const videoScript = await findScriptInSkill(skillDir, videoScripts);
+    if (videoScript) {
+      return new GenericDriver(slug, 'video', `${slug} Video Generation`);
+    }
+
+    // Check for audio generation capability
+    const audioScript = await findScriptInSkill(skillDir, audioScripts);
+    if (audioScript) {
+      return new GenericDriver(slug, 'audio', `${slug} Audio Generation`);
+    }
+
+    // Fall back to generic generate script
+    const genericScript = await findScriptInSkill(skillDir, ['generate.py', 'generate.sh']);
+    if (genericScript) {
+      return new GenericDriver(slug, 'image', `${slug} Generic Generation`);
+    }
+
+    return null;
+  }
+}

package/src/lib/workflows/media-drivers/index.ts

@@ -0,0 +1,22 @@
+export { 
+  getDriver, 
+  getDriversByType, 
+  getAllDrivers, 
+  isDriverAvailable,
+  getAvailableDrivers,
+  getAvailableDriversByType
+} from './registry';
+
+export type { 
+  MediaDriver, 
+  MediaDriverInvokeOpts, 
+  MediaDriverResult,
+  DurationConstraints
+} from './types';
+
+export { NanoBananaPro } from './nano-banana-pro.driver';
+export { OpenAIImageGen } from './openai-image-gen.driver';
+export { RunwayVideo } from './runway-video.driver';
+export { KlingVideo } from './kling-video.driver';
+export { LumaVideo } from './luma-video.driver';
+export { GenericDriver } from './generic.driver';

package/src/lib/workflows/media-drivers/kling-video.driver.ts

@@ -0,0 +1,110 @@
+import * as path from 'path';
+import * as fs from 'fs';
+import { MediaDriver, MediaDriverInvokeOpts, MediaDriverResult, DurationConstraints, parseDuration } from './types';
+import { findSkillDir, runScript, parseMediaOutput } from './utils';
+
+/**
+ * Kling AI video driver — uses official `klingai` ClawHub skill.
+ *
+ * Auth: JWT via ~/.config/kling/.credentials (Access Key + Secret Key).
+ * NOT a simple Bearer API key — the skill's auth.mjs handles JWT signing.
+ * No env var needed; credentials file is the source of truth.
+ */
+export class KlingVideo implements MediaDriver {
+  slug = 'klingai';
+  mediaType = 'video' as const;
+  displayName = 'Kling AI Video (Official)';
+  // Auth is via ~/.config/kling/.credentials, not env vars.
+  // We check for the credentials file in a custom availability method.
+  requiredEnvVars: string[] = [];
+  durationConstraints: DurationConstraints = { minSeconds: 3, maxSeconds: 15, defaultSeconds: 5, stepSeconds: 1 };
+
+  /**
+   * Check if Kling credentials are configured (credentials file exists with AK/SK).
+   */
+  isConfigured(): boolean {
+    const home = process.env.HOME || '/home/control';
+    const credPath = path.join(home, '.config', 'kling', '.credentials');
+    try {
+      const content = fs.readFileSync(credPath, 'utf8');
+      return content.includes('access_key_id') && content.includes('secret_access_key');
+    } catch {
+      return false;
+    }
+  }
+
+  async invoke(opts: MediaDriverInvokeOpts): Promise<MediaDriverResult> {
+    const { prompt, outputDir, env, timeout, config } = opts;
+    // Kling supports 3-15s; clamp to valid range
+    const rawDuration = Math.max(3, Math.min(15, Number(parseDuration(config))));
+    const duration = String(rawDuration);
+
+    const skillDir = await findSkillDir(this.slug);
+    if (!skillDir) {
+      throw new Error(
+        `Skill directory not found for ${this.slug}. Install it: clawhub install klingai --force`
+      );
+    }
+
+    const scriptPath = path.join(skillDir, 'scripts', 'video.mjs');
+
+    // The official skill is a Node.js script (not Python)
+    const runner = 'node';
+
+    const scriptOutput = runScript({
+      runner,
+      script: scriptPath,
+      args: [
+        '--prompt', prompt,
+        '--output_dir', outputDir,
+        '--duration', duration,
+        '--aspect_ratio', String(config?.aspect_ratio ?? config?.size ?? '16:9'),
+        '--mode', 'pro',
+      ],
+      env: {
+        ...env,
+        HOME: process.env.HOME || '/home/control',
+      },
+      cwd: outputDir,
+      timeout,
+    });
+
+    // The script prints "Done: /path/to/file.mp4" or "Saved: /path/to/file.mp4"
+    const doneMatch = scriptOutput.match(/(?:Done|完成|Saved|已保存):\s*(.+\.mp4)/m);
+    if (doneMatch) {
+      return {
+        filePath: doneMatch[1].trim(),
+        metadata: { skill: this.slug, prompt },
+      };
+    }
+
+    // Fallback: check for MEDIA: prefix (in case a bridge wrapper is used)
+    const mediaPath = parseMediaOutput(scriptOutput);
+    if (mediaPath) {
+      return {
+        filePath: mediaPath,
+        metadata: { skill: this.slug, prompt },
+      };
+    }
+
+    // Last resort: look for any .mp4 in output dir
+    try {
+      const files = fs.readdirSync(outputDir)
+        .filter(f => f.endsWith('.mp4'))
+        .sort()
+        .reverse();
+      if (files.length > 0) {
+        return {
+          filePath: path.join(outputDir, files[0]),
+          metadata: { skill: this.slug, prompt },
+        };
+      }
+    } catch {
+      // ignore
+    }
+
+    throw new Error(
+      `Could not find generated video in output. Script output:\n${scriptOutput}`
+    );
+  }
+}

package/src/lib/workflows/media-drivers/luma-video.driver.ts

@@ -0,0 +1,59 @@
+import * as path from 'path';
+import { MediaDriver, MediaDriverInvokeOpts, MediaDriverResult, DurationConstraints, parseDuration } from './types';
+import { findSkillDir, findVenvPython, runScript, parseMediaOutput } from './utils';
+
+export class LumaVideo implements MediaDriver {
+  slug = 'skill-luma-video';
+  mediaType = 'video' as const;
+  displayName = 'Luma Video Generation';
+  requiredEnvVars = ['LUMAAI_API_KEY'];
+  durationConstraints: DurationConstraints = { minSeconds: 5, maxSeconds: 9, defaultSeconds: 5, stepSeconds: 4 };
+
+  async invoke(opts: MediaDriverInvokeOpts): Promise<MediaDriverResult> {
+    const { prompt, outputDir, env, timeout, config } = opts;
+    const duration = parseDuration(config);
+
+    // Find the skill directory
+    const skillDir = await findSkillDir(this.slug);
+    if (!skillDir) {
+      throw new Error(`Skill directory not found for ${this.slug}`);
+    }
+
+    // Find the script
+    const scriptPath = path.join(skillDir, 'generate_video.py');
+    
+    // Find Python runner
+    const runner = await findVenvPython(skillDir);
+
+    // Execute the script with stdin input
+    const scriptOutput = runScript({
+      runner,
+      script: scriptPath,
+      stdin: prompt,
+      env: {
+        ...env,
+        HOME: process.env.HOME || '/home/control',
+        MEDIA_DURATION: duration,
+        MEDIA_ASPECT_RATIO: String(config?.aspect_ratio ?? config?.size ?? '16:9'),
+      },
+      cwd: outputDir,
+      timeout,
+    });
+
+    // Parse the MEDIA: output
+    const filePath = parseMediaOutput(scriptOutput);
+    
+    if (!filePath) {
+      throw new Error(`No MEDIA: path found in script output. Output: ${scriptOutput}`);
+    }
+
+    return {
+      filePath,
+      metadata: {
+        skill: this.slug,
+        prompt,
+        script_output: scriptOutput,
+      },
+    };
+  }
+}

package/src/lib/workflows/media-drivers/nano-banana-pro.driver.ts

@@ -0,0 +1,70 @@
+import * as path from 'path';
+import { MediaDriver, MediaDriverInvokeOpts, MediaDriverResult } from './types';
+import { findSkillDir, findVenvPython, runScript } from './utils';
+
+export class NanoBananaPro implements MediaDriver {
+  slug = 'nano-banana-pro';
+  mediaType = 'image' as const;
+  displayName = 'Nano Banana Pro (Gemini Image Generation)';
+  requiredEnvVars = ['GEMINI_API_KEY'];
+  durationConstraints = null;
+
+  async invoke(opts: MediaDriverInvokeOpts): Promise<MediaDriverResult> {
+    const { prompt, outputDir, env, timeout, config } = opts;
+
+    // Find the skill directory
+    const skillDir = await findSkillDir(this.slug);
+    if (!skillDir) {
+      throw new Error(`Skill directory not found for ${this.slug}`);
+    }
+
+    // Find the script
+    const scriptPath = path.join(skillDir, 'scripts', 'generate_image.py');
+    
+    // Find Python runner - check for venv first, fallback to uv run
+    let runner: string;
+    try {
+      runner = await findVenvPython(skillDir);
+    } catch {
+      // Fallback to uv run if no venv
+      runner = 'uv run python';
+    }
+
+    // Generate a filename for the output
+    const filename = 'output.png';
+
+    // Map pixel size to resolution tier (nano-banana-pro uses 1K/2K/4K)
+    const sizeStr = String(config?.size ?? '1024x1024');
+    const maxDim = Math.max(...sizeStr.split('x').map(Number).filter(n => !isNaN(n)), 1024);
+    const resolution = maxDim >= 3840 ? '4K' : maxDim >= 1792 ? '2K' : '1K';
+
+    // Execute the script with argparse CLI interface
+    const scriptOutput = runScript({
+      runner,
+      script: scriptPath,
+      args: ['--prompt', prompt, '--filename', filename, '--resolution', resolution],
+      env: {
+        ...env,
+        HOME: process.env.HOME || '/home/control',
+      },
+      cwd: outputDir,
+      timeout,
+    });
+
+    // nano-banana-pro prints the full path on stdout
+    const outputPath = scriptOutput.trim();
+    
+    if (!outputPath || !outputPath.includes('.')) {
+      throw new Error(`No valid file path returned from script. Output: ${scriptOutput}`);
+    }
+
+    return {
+      filePath: outputPath,
+      metadata: {
+        skill: this.slug,
+        prompt,
+        script_output: scriptOutput,
+      },
+    };
+  }
+}

package/src/lib/workflows/media-drivers/openai-image-gen.driver.ts

@@ -0,0 +1,60 @@
+import * as path from 'path';
+import { MediaDriver, MediaDriverInvokeOpts, MediaDriverResult } from './types';
+import { findSkillDir, findVenvPython, runScript, parseMediaOutput } from './utils';
+
+export class OpenAIImageGen implements MediaDriver {
+  slug = 'openai-image-gen';
+  mediaType = 'image' as const;
+  displayName = 'OpenAI Image Generation (DALL-E)';
+  requiredEnvVars = ['OPENAI_API_KEY'];
+  durationConstraints = null;
+
+  async invoke(opts: MediaDriverInvokeOpts): Promise<MediaDriverResult> {
+    const { prompt, outputDir, env, timeout, config } = opts;
+
+    // Find the skill directory
+    const skillDir = await findSkillDir(this.slug);
+    if (!skillDir) {
+      throw new Error(`Skill directory not found for ${this.slug}`);
+    }
+
+    // Find the script
+    const scriptPath = path.join(skillDir, 'generate_image.py');
+    
+    // Find Python runner
+    const runner = await findVenvPython(skillDir);
+
+    // Pass size via env var (script reads DALL_E_SIZE, defaults to 1024x1024)
+    const size = String(config?.size ?? '1024x1024');
+
+    // Execute the script with stdin input
+    const scriptOutput = runScript({
+      runner,
+      script: scriptPath,
+      stdin: prompt,
+      env: {
+        ...env,
+        HOME: process.env.HOME || '/home/control',
+        DALL_E_SIZE: size,
+      },
+      cwd: outputDir,
+      timeout,
+    });
+
+    // Parse the MEDIA: output
+    const filePath = parseMediaOutput(scriptOutput);
+    
+    if (!filePath) {
+      throw new Error(`No MEDIA: path found in script output. Output: ${scriptOutput}`);
+    }
+
+    return {
+      filePath,
+      metadata: {
+        skill: this.slug,
+        prompt,
+        script_output: scriptOutput,
+      },
+    };
+  }
+}