@jiggai/recipes 0.4.39 → 0.4.40

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

package/package.json

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

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

@@ -43,7 +43,8 @@ export class GenericDriver implements MediaDriver {
     }
 
     // Execute the script with stdin input (most common interface)
-    const scriptOutput = runScript({
+    const scriptOutput = await runScript({
+      api: opts.api,
       runner,
       script: scriptPath,
       stdin: prompt,

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

@@ -78,7 +78,8 @@ export class KlingVideo implements MediaDriver {
     // The official skill is a Node.js script (not Python)
     const runner = 'node';
 
-    const scriptOutput = runScript({
+    const scriptOutput = await runScript({
+      api: opts.api,
       runner,
       script: scriptPath,
       args: [

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

@@ -26,7 +26,8 @@ export class LumaVideo implements MediaDriver {
     const runner = await findVenvPython(skillDir);
 
     // Execute the script with stdin input
-    const scriptOutput = runScript({
+    const scriptOutput = await runScript({
+      api: opts.api,
       runner,
       script: scriptPath,
       stdin: prompt,
@@ -42,7 +43,7 @@ export class LumaVideo implements MediaDriver {
 
     // Parse the MEDIA: output
     const filePath = parseMediaOutput(scriptOutput);
-    
+
     if (!filePath) {
       throw new Error(`No MEDIA: path found in script output. Output: ${scriptOutput}`);
     }

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

@@ -39,7 +39,8 @@ export class NanoBananaPro implements MediaDriver {
     const resolution = maxDim >= 3840 ? '4K' : maxDim >= 1792 ? '2K' : '1K';
 
     // Execute the script with argparse CLI interface
-    const scriptOutput = runScript({
+    const scriptOutput = await runScript({
+      api: opts.api,
       runner,
       script: scriptPath,
       args: ['--prompt', prompt, '--filename', filename, '--resolution', resolution],

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

@@ -28,7 +28,8 @@ export class OpenAIImageGen implements MediaDriver {
     const size = String(config?.size ?? '1024x1024');
 
     // Execute the script with stdin input
-    const scriptOutput = runScript({
+    const scriptOutput = await runScript({
+      api: opts.api,
       runner,
       script: scriptPath,
       stdin: prompt,

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

@@ -26,7 +26,8 @@ export class RunwayVideo implements MediaDriver {
     const runner = await findVenvPython(skillDir);
 
     // Execute the script with stdin input
-    const scriptOutput = runScript({
+    const scriptOutput = await runScript({
+      api: opts.api,
       runner,
       script: scriptPath,
       stdin: prompt,
@@ -42,7 +43,7 @@ export class RunwayVideo implements MediaDriver {
 
     // Parse the MEDIA: output
     const filePath = parseMediaOutput(scriptOutput);
-    
+
     if (!filePath) {
       throw new Error(`No MEDIA: path found in script output. Output: ${scriptOutput}`);
     }

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

@@ -1,4 +1,7 @@
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+
 export interface MediaDriverInvokeOpts {
+  api: OpenClawPluginApi;
   prompt: string;
   outputDir: string;
   env: Record<string, string>;

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

@@ -1,6 +1,6 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
-import { execFileSync } from 'child_process';
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
 
 /**
  * Find a skill directory by searching common skill roots
@@ -33,7 +33,7 @@ export async function findSkillDir(slug: string): Promise<string | null> {
  */
 export async function findVenvPython(skillDir: string): Promise<string> {
   const venvPython = path.join(skillDir, '.venv', 'bin', 'python');
-  
+
   try {
     await fs.access(venvPython);
     return venvPython;
@@ -48,7 +48,7 @@ export async function findVenvPython(skillDir: string): Promise<string> {
 export async function loadConfigEnv(): Promise<Record<string, string>> {
   const homedir = process.env.HOME || '/home/control';
   const configPath = path.join(homedir, '.openclaw', 'openclaw.json');
-  
+
   try {
     const cfgRaw = await fs.readFile(configPath, 'utf8');
     const cfgParsed = JSON.parse(cfgRaw);
@@ -82,9 +82,12 @@ export function parseMediaOutput(stdout: string): string {
 }
 
 /**
- * Execute a script with proper error handling and output capture
+ * Execute a script via the OpenClaw exec tool so this plugin package does not
+ * directly import child_process. We still pass argv as discrete args and feed
+ * prompt text via stdin through a small Python wrapper script.
  */
 export interface RunScriptOpts {
+  api: OpenClawPluginApi;
   runner: string;
   script: string;
   args?: string[];
@@ -94,26 +97,75 @@ export interface RunScriptOpts {
   timeout: number;
 }
 
-export function runScript(opts: RunScriptOpts): string {
+function buildPythonExecSnippet(opts: RunScriptOpts): string {
   const { runner, script, args = [], stdin, env, cwd, timeout } = opts;
+  const mergedEnv = {
+    ...env,
+    MEDIA_OUTPUT_DIR: cwd,
+  };
+
+  const payload = {
+    runner,
+    script,
+    args,
+    stdin: stdin ?? '',
+    env: mergedEnv,
+    cwd,
+    timeoutMs: timeout,
+  };
+
+  // Base64-encode the payload to avoid shell injection and heredoc delimiter collisions.
+  const payloadB64 = Buffer.from(JSON.stringify(payload)).toString('base64');
+
+  return [
+    `python3 -c '`,
+    `import base64, json, os, subprocess, sys;`,
+    `payload = json.loads(base64.b64decode("${payloadB64}").decode());`,
+    `env = os.environ.copy();`,
+    `env.update({k: str(v) for k, v in payload["env"].items()});`,
+    `res = subprocess.run(`,
+    `  [payload["runner"], payload["script"], *payload.get("args", [])],`,
+    `  input=payload.get("stdin", ""),`,
+    `  text=True,`,
+    `  capture_output=True,`,
+    `  cwd=payload["cwd"],`,
+    `  env=env,`,
+    `  timeout=max(1, int(payload.get("timeoutMs", 1000) / 1000))`,
+    `);`,
+    `sys.stdout.write(res.stdout);`,
+    `sys.stderr.write(res.stderr);`,
+    `raise SystemExit(res.returncode)`,
+    `'`,
+  ].join('\n');
+}
+
+export async function runScript(opts: RunScriptOpts): Promise<string> {
+  const { api, timeout } = opts;
+  const timeoutMs = Math.max(1000, timeout + 5000);
+  const command = buildPythonExecSnippet(opts);
 
   try {
-    return execFileSync(runner, [script, ...args], {
-      cwd,
-      timeout,
-      encoding: 'utf8',
-      input: stdin,
-      env: {
-        ...process.env,
-        ...env,
-        MEDIA_OUTPUT_DIR: cwd,
-      },
-    }).trim();
+    // Use the plugin SDK's runtime exec — available to all plugins without
+    // gateway tool permissions (unlike toolsInvoke('exec') which is session-gated).
+    const result = await api.runtime.system.runCommandWithTimeout(
+      ['bash', '-c', command],
+      { timeoutMs, cwd: opts.cwd },
+    );
+
+    if (result.code !== 0) {
+      const msg = [
+        `Script execution failed with exit code ${result.code}`,
+        result.stdout ? `\n--- stdout ---\n${result.stdout.trim()}` : '',
+        result.stderr ? `\n--- stderr ---\n${result.stderr.trim()}` : '',
+      ].filter(Boolean).join('');
+      throw new Error(msg);
+    }
+
+    return (result.stdout || '').trim();
   } catch (err) {
-    // Surface stderr/stdout to make debugging skill scripts possible
-    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 e = err as Error & { stdout?: string; stderr?: string };
+    const stdout = e?.stdout ?? '';
+    const stderr = e?.stderr ?? '';
     const msg = [
       e?.message ? String(e.message) : 'Script execution failed',
       stdout ? `\n--- stdout ---\n${stdout.trim()}` : '',
@@ -128,7 +180,7 @@ export function runScript(opts: RunScriptOpts): string {
  */
 export async function findScriptInSkill(skillDir: string, scriptCandidates: string[]): Promise<string | null> {
   const searchDirs = [skillDir, path.join(skillDir, 'scripts')];
-  
+
   for (const dir of searchDirs) {
     for (const candidate of scriptCandidates) {
       const scriptPath = path.join(dir, candidate);
@@ -140,6 +192,6 @@ export async function findScriptInSkill(skillDir: string, scriptCandidates: stri
       }
     }
   }
-  
+
   return null;
-}
+}

package/src/lib/workflows/workflow-error-classify.ts

@@ -0,0 +1,69 @@
+import { ToolsInvokeError } from '../../toolsInvoke.js';
+
+export type ErrorCategory = 'funding' | 'rate-limit' | 'auth' | 'timeout' | 'unknown';
+
+const FUNDING_PATTERNS = [
+  /insufficient.*(credits?|funds?|balance)/i,
+  /billing/i,
+  /payment\s+required/i,
+  /quota\s+exceeded/i,
+  /out\s+of\s+credits/i,
+  /budget\s+(exceeded|limit)/i,
+  /no\s+(active\s+)?subscription/i,
+  /plan\s+(limit|exceeded)/i,
+];
+
+const RATE_LIMIT_PATTERNS = [
+  /rate\s+limit/i,
+  /too\s+many\s+requests/i,
+  /throttl/i,
+];
+
+const AUTH_PATTERNS = [
+  /unauthorized/i,
+  /invalid.*api.?key/i,
+  /forbidden/i,
+  /authentication\s+failed/i,
+  /access\s+denied/i,
+];
+
+function classifyByHttpStatus(status: number): ErrorCategory | null {
+  if (status === 402) return 'funding';
+  if (status === 429) return 'rate-limit';
+  if (status === 401 || status === 403) return 'auth';
+  if (status === 408 || status === 504) return 'timeout';
+  return null;
+}
+
+function classifyByMessage(message: string, error: unknown): ErrorCategory | null {
+  if (FUNDING_PATTERNS.some((p) => p.test(message))) return 'funding';
+  if (RATE_LIMIT_PATTERNS.some((p) => p.test(message))) return 'rate-limit';
+  if (AUTH_PATTERNS.some((p) => p.test(message))) return 'auth';
+  if (error instanceof Error && error.name === 'AbortError') return 'timeout';
+  if (/timed?\s*out/i.test(message)) return 'timeout';
+  return null;
+}
+
+/**
+ * Classify an error into a category based on HTTP status and message content.
+ * Returns 'unknown' if the error doesn't match any known pattern.
+ */
+export function classifyError(error: unknown): ErrorCategory {
+  const httpStatus = error instanceof ToolsInvokeError ? error.httpStatus : 0;
+  const message = error instanceof Error ? error.message : String(error ?? '');
+
+  return classifyByHttpStatus(httpStatus) ?? classifyByMessage(message, error) ?? 'unknown';
+}
+
+const CATEGORY_LABELS: Record<ErrorCategory, string> = {
+  'funding': 'Funding issue — the model provider may be out of credits or require payment',
+  'rate-limit': 'Rate limit — the model provider is throttling requests',
+  'auth': 'Authentication failure — the API key may be invalid or expired',
+  'timeout': 'Timeout — the request took too long to complete',
+  'unknown': 'Unknown error',
+};
+
+/** Human-readable label for an error category. */
+export function errorCategoryLabel(category: ErrorCategory): string {
+  return CATEGORY_LABELS[category] ?? CATEGORY_LABELS['unknown'];
+}

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

@@ -4,6 +4,7 @@ import crypto from 'node:crypto';
 import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
 import type { ToolTextResult } from '../../toolsInvoke';
 import { toolsInvoke } from '../../toolsInvoke';
+import { classifyError, errorCategoryLabel } from './workflow-error-classify';
 import { resolveTeamDir } from '../workspace';
 import { getDriver } from './media-drivers/registry';
 import { GenericDriver } from './media-drivers/generic.driver';
@@ -911,6 +912,7 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
         text = JSON.stringify(payload, null, 2);
       } catch (e) {
         const eRec = asRecord(e);
+        const errorCategory = classifyError(e);
         const errorDetails = {
           message: e instanceof Error ? e.message : String(e),
           name: e instanceof Error ? e.name : undefined,
@@ -919,6 +921,8 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
           details: eRec['details'],
           data: eRec['data'],
           cause: e instanceof Error && 'cause' in e ? (e as Error & { cause?: unknown }).cause : undefined,
+          errorCategory,
+          errorCategoryLabel: errorCategory !== 'unknown' ? errorCategoryLabel(errorCategory) : undefined,
         };
         const errMsg = `LLM execution failed for node ${nodeLabel(node)}: ${errorDetails.message}`;
         const errorTs = new Date().toISOString();
@@ -928,18 +932,18 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
           updatedAt: errorTs,
           nodeStates: {
             ...(cur.nodeStates ?? {}),
-            [node.id]: { status: 'error', ts: errorTs, error: errMsg, details: errorDetails },
+            [node.id]: { status: 'error', ts: errorTs, error: errMsg, details: errorDetails, errorCategory },
           },
           events: [
             ...cur.events,
-            { ts: errorTs, type: 'node.error', nodeId: node.id, kind: node.kind, message: errMsg, details: errorDetails },
+            { ts: errorTs, type: 'node.error', nodeId: node.id, kind: node.kind, message: errMsg, details: errorDetails, errorCategory },
           ],
           nodeResults: [
             ...(cur.nodeResults ?? []),
-            { nodeId: node.id, kind: node.kind, agentId: agentIdExec, error: errMsg, details: errorDetails },
+            { nodeId: node.id, kind: node.kind, agentId: agentIdExec, error: errMsg, details: errorDetails, errorCategory },
           ],
         }));
-        results.push({ taskId: task.id, runId: task.runId, nodeId: task.nodeId, status: 'error' });
+        results.push({ taskId: task.id, runId: task.runId, nodeId: task.nodeId, status: 'error', errorCategory });
         continue;
       }
 
@@ -1356,16 +1360,17 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
           nodeResults: [...(cur.nodeResults ?? []), { nodeId: node.id, kind: node.kind, tool: toolName, artifactPath: path.relative(teamDir, artifactPath), nodeOutputPath: path.relative(teamDir, nodeOutputAbs) }],
         }));
       } catch (e) {
-        await fs.writeFile(artifactPath, JSON.stringify({ ok: false, tool: toolName, error: (e as Error).message }, null, 2) + '\n', 'utf8');
+        const errorCategory = classifyError(e);
+        await fs.writeFile(artifactPath, JSON.stringify({ ok: false, tool: toolName, error: (e as Error).message, errorCategory }, null, 2) + '\n', 'utf8');
         const errorTs = new Date().toISOString();
         await appendRunLog(runPath, (cur) => ({
           ...cur,
           status: 'error',
-          nodeStates: { ...(cur.nodeStates ?? {}), [node.id]: { status: 'error', ts: errorTs } },
-          events: [...cur.events, { ts: errorTs, type: 'node.error', nodeId: node.id, kind: node.kind, tool: toolName, message: (e as Error).message, artifactPath: path.relative(teamDir, artifactPath) }],
-          nodeResults: [...(cur.nodeResults ?? []), { nodeId: node.id, kind: node.kind, tool: toolName, error: (e as Error).message, artifactPath: path.relative(teamDir, artifactPath) }],
+          nodeStates: { ...(cur.nodeStates ?? {}), [node.id]: { status: 'error', ts: errorTs, errorCategory } },
+          events: [...cur.events, { ts: errorTs, type: 'node.error', nodeId: node.id, kind: node.kind, tool: toolName, message: (e as Error).message, artifactPath: path.relative(teamDir, artifactPath), errorCategory }],
+          nodeResults: [...(cur.nodeResults ?? []), { nodeId: node.id, kind: node.kind, tool: toolName, error: (e as Error).message, artifactPath: path.relative(teamDir, artifactPath), errorCategory }],
         }));
-        results.push({ taskId: task.id, runId: task.runId, nodeId: task.nodeId, status: 'error', error: (e as Error).message });
+        results.push({ taskId: task.id, runId: task.runId, nodeId: task.nodeId, status: 'error', error: (e as Error).message, errorCategory });
         continue;
       }
     } else if (kind === 'media-image' || kind === 'media-video' || kind === 'media-audio') {
@@ -1477,6 +1482,7 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
         let payload: Record<string, unknown>;
         if (driver) {
           const result = await driver.invoke({
+            api,
             prompt: refinedPrompt,
             outputDir: mediaDir,
             env: mergedEnv,
@@ -1503,6 +1509,7 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
         }
         text = JSON.stringify(payload, null, 2);
       } catch (e) {
+        const errorCategory = classifyError(e);
         const errDetails = e instanceof Error
           ? { message: e.message, name: e.name, stack: e.stack?.split('\n').slice(0, 5).join(' | ') }
           : { message: String(e) };
@@ -1512,11 +1519,11 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
           ...cur,
           status: 'error',
           updatedAt: errorTs,
-          nodeStates: { ...(cur.nodeStates ?? {}), [node.id]: { status: 'error', ts: errorTs, error: errMsg } },
-          events: [...cur.events, { ts: errorTs, type: 'node.error', nodeId: node.id, kind: node.kind, message: errMsg }],
-          nodeResults: [...(cur.nodeResults ?? []), { nodeId: node.id, kind: node.kind, agentId: agentIdMedia || agentId, error: errMsg }],
+          nodeStates: { ...(cur.nodeStates ?? {}), [node.id]: { status: 'error', ts: errorTs, error: errMsg, errorCategory } },
+          events: [...cur.events, { ts: errorTs, type: 'node.error', nodeId: node.id, kind: node.kind, message: errMsg, errorCategory }],
+          nodeResults: [...(cur.nodeResults ?? []), { nodeId: node.id, kind: node.kind, agentId: agentIdMedia || agentId, error: errMsg, errorCategory }],
         }));
-        results.push({ taskId: task.id, runId: task.runId, nodeId: task.nodeId, status: 'error' });
+        results.push({ taskId: task.id, runId: task.runId, nodeId: task.nodeId, status: 'error', errorCategory });
         continue;
       }
 

package/src/toolsInvoke.ts

@@ -6,6 +6,19 @@ export const TOOLS_INVOKE_TIMEOUT_MS = 120_000;
 export const RETRY_DELAY_BASE_MS = 150;
 export const GATEWAY_DEFAULT_PORT = 18789;
 
+/**
+ * Custom error class that preserves HTTP status from gateway responses.
+ * Used downstream to classify errors (e.g. 402 → funding, 429 → rate-limit).
+ */
+export class ToolsInvokeError extends Error {
+  httpStatus: number;
+  constructor(message: string, httpStatus: number) {
+    super(message);
+    this.name = 'ToolsInvokeError';
+    this.httpStatus = httpStatus;
+  }
+}
+
 export type ToolTextResult = { content?: Array<{ type: string; text?: string }> };
 
 export type ToolsInvokeRequest = {
@@ -43,7 +56,7 @@ async function doSingleToolsInvoke<T>(url: string, token: string, req: ToolsInvo
   }).finally(() => clearTimeout(t));
 
   const json = (await res.json()) as ToolsInvokeResponse;
-  if (!res.ok || !json.ok) throw new Error(parseToolsInvokeError(json, res.status));
+  if (!res.ok || !json.ok) throw new ToolsInvokeError(parseToolsInvokeError(json, res.status), res.status);
   return json.result as T;
 }