@jiggai/recipes 0.4.39 → 0.4.41

package/docs/WORKFLOW_NODES.md

@@ -116,9 +116,39 @@ Tool nodes call a tool by name with JSON args. Example:
 - `fs.append`
 - `outbound.post`
 - `message.send`
+- `exec` (shell command execution)
 
 Tool nodes support template vars inside string args.
 
+#### Exec tool nodes
+
+Nodes with `"tool": "exec"` run shell commands via the plugin runtime (not the gateway). This means **any agent** can execute them — there is no need to assign exec nodes to `main`.
+
+Config fields:
+- `args.command` (string): the shell command to run (passed to `bash -c`)
+- `args.workdir` (string, optional): working directory (defaults to the team workspace)
+- `args.timeout` (number, optional): timeout in seconds (default: 120)
+
+**Agent assignment:** Assign exec nodes to the same agent that handles the surrounding workflow — typically the team lead. Avoid assigning to `main` unless the node specifically needs the personal workspace context.
+
+```json
+{
+  "id": "run_script",
+  "type": "tool",
+  "name": "Run deploy script",
+  "config": {
+    "tool": "exec",
+    "args": {
+      "command": "bash scripts/deploy.sh --env={{run.id}}",
+      "timeout": 60
+    },
+    "agentId": "my-team-lead"
+  }
+}
+```
+
+> **Why not `main`?** Each agent has its own worker queue and cron. If you assign a node to `main` but there's no worker cron for `main` on that team, the task will sit in the queue indefinitely. Use the team's existing agents to keep things flowing.
+
 ---
 
 ### Human approval nodes

package/index.ts

@@ -1034,6 +1034,19 @@ workflows
             logScaffoldResult(res, String(options.recipe));
           });
 
+        cmd
+          .command("kitchen-manifest")
+          .description("Generate the Kitchen manifest file (pre-computed nav/shell data for ClawKitchen)")
+          .option("--output <path>", "Override output path (default: ~/.openclaw/kitchen-manifest.json)")
+          .action(async (options: { output?: string }) => {
+            const { generateKitchenManifest } = await import("./src/lib/kitchen-manifest");
+            const manifest = await generateKitchenManifest({
+              api,
+              outputPath: options.output || undefined,
+            });
+            console.log(JSON.stringify({ ok: true, generatedAt: manifest.generatedAt, teams: Object.keys(manifest.teams).length, agents: manifest.agents.length, recipes: manifest.recipes.length }));
+          });
+
       },
       { commands: ["recipes"] },
     );

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.41",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

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

package/src/handlers/team.ts

@@ -13,6 +13,7 @@ import { pickRecipeId } from "../lib/recipe-id";
 import { recipeIdTakenForTeam, validateRecipeAndSkills, writeWorkspaceRecipeFile } from "../lib/scaffold-utils";
 import { scaffoldAgentFromRecipe } from "./scaffold";
 import { renderTemplate } from "../lib/template";
+import { scheduleManifestRegeneration } from "../lib/kitchen-manifest";
 import { reconcileRecipeCronJobs } from "./cron";
 import { lintRecipe } from "../lib/recipe-lint";
 
@@ -510,6 +511,7 @@ export async function handleScaffoldTeam(
     scope: { kind: "team", teamId, recipeId: recipe.id, stateDir: teamDir },
     cronInstallation: cfg.cronInstallation,
   });
+  scheduleManifestRegeneration(api);
   return {
     ok: true as const,
     teamId,
@@ -645,6 +647,7 @@ export async function executeMigrateTeamPlan(
     await applyAgentSnippetsToOpenClawConfig(api, agentSnippets);
   }
 
+  scheduleManifestRegeneration(api);
   return { ok: true as const, migrated: plan.teamId, destTeamDir: dest.teamDir, agentIds: plan.agentIds };
 }
 
@@ -707,5 +710,6 @@ export async function handleRemoveTeam(
   });
   await writeOpenClawConfig(api, cfgObj);
   await saveCronStore(cronJobsPath, cronStore);
+  scheduleManifestRegeneration(api);
   return { ok: true as const, result };
 }

package/src/handlers/tickets.ts

@@ -7,6 +7,7 @@ import { ticketStageDir } from "../lib/lanes";
 import { computeNextTicketNumber, TICKET_FILENAME_REGEX } from "../lib/ticket-finder";
 import { resolveTeamContext } from "../lib/workspace";
 import { VALID_ROLES, VALID_STAGES } from "../lib/constants";
+import { scheduleManifestRegeneration } from "../lib/kitchen-manifest";
 
 export function patchTicketField(md: string, key: string, value: string): string {
   const lineRe = new RegExp(`^${key}:\\s.*$`, "m");
@@ -110,6 +111,7 @@ export async function handleMoveTicket(
 
   // Assignment stubs are deprecated; no archival behavior.
 
+  scheduleManifestRegeneration(api);
   return { ok: true, from: srcPath, to: destPath };
 }
 
@@ -293,6 +295,7 @@ export async function handleDispatch(
     // Dispatch still succeeds; nudgeQueued stays false so caller knows the nudge was skipped.
     nudgeQueued = false;
   }
+  scheduleManifestRegeneration(api);
   return { ok: true as const, wrote: plan.files.map((f) => f.path), nudgeQueued };
 }
 

package/src/lib/kitchen-manifest.ts

@@ -0,0 +1,222 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+
+// ── Manifest types ──────────────────────────────────────────────────────────
+
+export interface KitchenManifest {
+  version: 1;
+  generatedAt: string;
+  teams: Record<string, TeamManifestEntry>;
+  agents: AgentManifestEntry[];
+  recipes: RecipeManifestEntry[];
+}
+
+export interface TeamManifestEntry {
+  teamId: string;
+  displayName: string | null;
+  roles: string[];
+  ticketCounts: {
+    backlog: number;
+    'in-progress': number;
+    testing: number;
+    done: number;
+    total: number;
+  };
+  activeRunCount: number;
+}
+
+export interface AgentManifestEntry {
+  id: string;
+  identityName?: string;
+  workspace?: string;
+  model?: string;
+  isDefault?: boolean;
+}
+
+export interface RecipeManifestEntry {
+  id: string;
+  name: string;
+  kind: 'agent' | 'team';
+  source: 'builtin' | 'workspace';
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+const OPENCLAW_DIR = path.join(os.homedir(), '.openclaw');
+const MANIFEST_FILENAME = 'kitchen-manifest.json';
+
+export function defaultManifestPath(): string {
+  return path.join(OPENCLAW_DIR, MANIFEST_FILENAME);
+}
+
+async function countMdFiles(dir: string): Promise<number> {
+  try {
+    const entries = await fs.readdir(dir);
+    return entries.filter((e) => e.endsWith('.md')).length;
+  } catch {
+    return 0;
+  }
+}
+
+async function countActiveRuns(teamDir: string): Promise<number> {
+  const runsDir = path.join(teamDir, 'shared-context', 'workflow-runs');
+  let runDirs: string[];
+  try {
+    runDirs = await fs.readdir(runsDir);
+  } catch {
+    return 0;
+  }
+
+  let count = 0;
+  for (const d of runDirs) {
+    const runJson = path.join(runsDir, d, 'run.json');
+    try {
+      const raw = await fs.readFile(runJson, 'utf8');
+      const run = JSON.parse(raw) as { status?: string };
+      const s = run.status ?? '';
+      if (s === 'running' || s === 'waiting_workers' || s === 'waiting_for_approval') {
+        count++;
+      }
+    } catch {
+      // run.json missing or malformed — skip
+    }
+  }
+  return count;
+}
+
+async function listRoles(teamDir: string): Promise<string[]> {
+  const rolesDir = path.join(teamDir, 'roles');
+  try {
+    const entries = await fs.readdir(rolesDir, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+  } catch {
+    return [];
+  }
+}
+
+async function readTeamDisplayName(teamDir: string): Promise<string | null> {
+  const teamJsonPath = path.join(teamDir, 'shared-context', 'workflows', 'team.json');
+  try {
+    const raw = await fs.readFile(teamJsonPath, 'utf8');
+    const parsed = JSON.parse(raw) as { recipeName?: string };
+    return parsed.recipeName?.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// ── Generator ───────────────────────────────────────────────────────────────
+
+export interface GenerateManifestOptions {
+  api: OpenClawPluginApi;
+  outputPath?: string;
+}
+
+export async function generateKitchenManifest(opts: GenerateManifestOptions): Promise<KitchenManifest> {
+  const { api } = opts;
+  const outputPath = opts.outputPath ?? defaultManifestPath();
+
+  // Discover teams
+  let dirEntries: string[];
+  try {
+    dirEntries = await fs.readdir(OPENCLAW_DIR);
+  } catch {
+    dirEntries = [];
+  }
+
+  const teamDirNames = dirEntries.filter((e) => e.startsWith('workspace-'));
+  const teams: Record<string, TeamManifestEntry> = {};
+
+  for (const dirName of teamDirNames) {
+    const teamId = dirName.slice('workspace-'.length);
+    if (!teamId) continue;
+
+    const teamDir = path.join(OPENCLAW_DIR, dirName);
+    const workDir = path.join(teamDir, 'work');
+
+    const [backlog, inProgress, testing, done, activeRunCount, roles, displayName] = await Promise.all([
+      countMdFiles(path.join(workDir, 'backlog')),
+      countMdFiles(path.join(workDir, 'in-progress')),
+      countMdFiles(path.join(workDir, 'testing')),
+      countMdFiles(path.join(workDir, 'done')),
+      countActiveRuns(teamDir),
+      listRoles(teamDir),
+      readTeamDisplayName(teamDir),
+    ]);
+
+    teams[teamId] = {
+      teamId,
+      displayName,
+      roles,
+      ticketCounts: {
+        backlog,
+        'in-progress': inProgress,
+        testing,
+        done,
+        total: backlog + inProgress + testing + done,
+      },
+      activeRunCount,
+    };
+  }
+
+  // Fetch agents and recipes via CLI (reuses existing OpenClaw infrastructure)
+  let agents: AgentManifestEntry[] = [];
+  try {
+    const res = await api.runtime.system.runCommandWithTimeout(
+      ['openclaw', 'agents', 'list', '--json'],
+      { timeoutMs: 15_000 },
+    );
+    if (res.code === 0 && res.stdout) {
+      agents = JSON.parse(res.stdout) as AgentManifestEntry[];
+    }
+  } catch { /* best-effort */ }
+
+  let recipes: RecipeManifestEntry[] = [];
+  try {
+    const res = await api.runtime.system.runCommandWithTimeout(
+      ['openclaw', 'recipes', 'list'],
+      { timeoutMs: 15_000 },
+    );
+    if (res.code === 0 && res.stdout) {
+      recipes = JSON.parse(res.stdout) as RecipeManifestEntry[];
+    }
+  } catch { /* best-effort */ }
+
+  const manifest: KitchenManifest = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    teams,
+    agents,
+    recipes,
+  };
+
+  // Atomic write: tmp file + rename
+  const tmpPath = outputPath + '.tmp';
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await fs.writeFile(tmpPath, JSON.stringify(manifest, null, 2), 'utf8');
+  await fs.rename(tmpPath, outputPath);
+
+  return manifest;
+}
+
+// ── Debounced regeneration ──────────────────────────────────────────────────
+
+let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+const DEBOUNCE_MS = 500;
+
+/**
+ * Schedule a manifest regeneration. Multiple calls within DEBOUNCE_MS are
+ * coalesced into a single generation. Fire-and-forget — errors are logged
+ * but never propagated.
+ */
+export function scheduleManifestRegeneration(api: OpenClawPluginApi): void {
+  if (debounceTimer) clearTimeout(debounceTimer);
+  debounceTimer = setTimeout(() => {
+    debounceTimer = null;
+    generateKitchenManifest({ api }).catch((err) => {
+      console.error('[kitchen-manifest] regeneration failed:', err instanceof Error ? err.message : String(err));
+    });
+  }, DEBOUNCE_MS);
+}

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-utils.ts

@@ -192,7 +192,7 @@ export async function moveRunTicket(opts: {
   return { ticketPath: dest };
 }
 
-export function loadNodeStatesFromRun(run: RunLog): Record<string, { status: 'success' | 'error' | 'waiting'; ts: string }> {
+export function loadNodeStatesFromRun(run: RunLog, opts?: { workflow?: Workflow }): Record<string, { status: 'success' | 'error' | 'waiting'; ts: string }> {
   const out: Record<string, { status: 'success' | 'error' | 'waiting'; ts: string }> = {};
 
   const cur = run.nodeStates;
@@ -217,6 +217,19 @@ export function loadNodeStatesFromRun(run: RunLog): Record<string, { status: 'su
     if (type === 'node.approved') out[nodeId] = { status: 'success', ts };
   }
 
+  // Revision semantics: when a run is in needs_revision, the approval handler
+  // clears nodeStates from nextNodeIndex onward, but events are append-only.
+  // The event-based reconstruction above would re-populate states that were
+  // deliberately cleared. Remove them so the stale-task guard in the worker
+  // does not reject re-enqueued revision tasks.
+  if (run.status === 'needs_revision' && typeof run.nextNodeIndex === 'number' && opts?.workflow) {
+    const nodes = Array.isArray(opts.workflow.nodes) ? opts.workflow.nodes : [];
+    for (let i = Math.max(0, run.nextNodeIndex); i < nodes.length; i++) {
+      const id = asString(nodes[i]?.id).trim();
+      if (id) delete out[id];
+    }
+  }
+
   return out;
 }
 

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';
@@ -668,7 +669,7 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
       // cursor. Before executing a dequeued task, verify that this node is still actually runnable
       // for the current run state. Otherwise we can resurrect pre-approval work and overwrite
       // canonical node outputs for runs that already advanced.
-      const currentNodeStates = loadNodeStatesFromRun(run);
+      const currentNodeStates = loadNodeStatesFromRun(run, { workflow });
       const currentStatus = currentNodeStates[String(node.id)]?.status;
       const currentlyRunnableIdx = pickNextRunnableNodeIndex({ workflow, run });
       if (
@@ -748,9 +749,20 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
         'workflow.id': String(workflow.id ?? ''),
         'workflow.name': String(workflow.name ?? workflow.id ?? workflowFile),
       };
-      
+
       // Load node outputs and make them available as template variables
       const { run: runSnap } = await loadRunFile(teamDir, runsDir, task.runId);
+
+      // Expose triggerInput as template variables (for handoff-injected data)
+      if (runSnap.triggerInput && typeof runSnap.triggerInput === 'object') {
+        for (const [key, value] of Object.entries(runSnap.triggerInput)) {
+          if (typeof value === 'string') {
+            vars[`trigger.${key}`] = value;
+          } else if (value !== null && value !== undefined) {
+            vars[`trigger.${key}`] = JSON.stringify(value);
+          }
+        }
+      }
       for (const nr of (runSnap.nodeResults ?? [])) {
         const nid = String((nr as Record<string, unknown>).nodeId ?? '');
         const nrOutPath = String((nr as Record<string, unknown>).nodeOutputPath ?? '');
@@ -911,6 +923,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 +932,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 +943,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;
       }
 
@@ -1254,9 +1269,20 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
             'workflow.id': String(workflow.id ?? ''),
             'workflow.name': String(workflow.name ?? workflow.id ?? workflowFile),
           };
-          
+
           // Load node outputs and make them available as template variables
           const { run: runSnap } = await loadRunFile(teamDir, runsDir, task.runId);
+
+          // Expose triggerInput as template variables (for handoff-injected data)
+          if (runSnap.triggerInput && typeof runSnap.triggerInput === 'object') {
+            for (const [key, value] of Object.entries(runSnap.triggerInput)) {
+              if (typeof value === 'string') {
+                vars[`trigger.${key}`] = value;
+              } else if (value !== null && value !== undefined) {
+                vars[`trigger.${key}`] = JSON.stringify(value);
+              }
+            }
+          }
           for (const nr of (runSnap.nodeResults ?? [])) {
             const nid = String((nr as Record<string, unknown>).nodeId ?? '');
             const nrOutPath = String((nr as Record<string, unknown>).nodeOutputPath ?? '');
@@ -1325,10 +1351,28 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
             }
           }
 
-          const toolRes = await toolsInvoke<unknown>(api, {
-            tool: toolName,
-            args: processedToolArgs,
-          });
+          let toolRes: unknown;
+          if (toolName === 'exec') {
+            // Route exec tool calls through the plugin SDK runtime instead of
+            // the gateway — the gateway exec tool is session-gated and unavailable
+            // to most workflow worker sessions.
+            const command = String((processedToolArgs as Record<string, unknown>).command ?? '');
+            const workdir = String((processedToolArgs as Record<string, unknown>).workdir ?? teamDir);
+            const timeoutSec = Number((processedToolArgs as Record<string, unknown>).timeout) || 120;
+            const result = await api.runtime.system.runCommandWithTimeout(
+              ['bash', '-c', command],
+              { timeoutMs: timeoutSec * 1000, cwd: workdir },
+            );
+            if (result.code !== 0) {
+              throw new Error(`exec failed (code=${result.code}):\n${result.stderr || result.stdout}`);
+            }
+            toolRes = { stdout: result.stdout, stderr: result.stderr, code: result.code };
+          } else {
+            toolRes = await toolsInvoke<unknown>(api, {
+              tool: toolName,
+              args: processedToolArgs,
+            });
+          }
 
           await fs.writeFile(artifactPath, JSON.stringify({ ok: true, tool: toolName, args: processedToolArgs, result: toolRes }, null, 2) + '\n', 'utf8');
         }
@@ -1356,16 +1400,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 +1522,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 +1549,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 +1559,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;
 }