@jiggai/recipes 0.4.40 → 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.40",
+  "version": "0.4.41",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jiggai/recipes",
-  "version": "0.4.40",
+  "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/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

@@ -669,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 (
@@ -749,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 ?? '');
@@ -1258,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 ?? '');
@@ -1329,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');
         }