@jiggai/recipes 0.4.37 → 0.4.39

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

package/package.json

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

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

@@ -3,6 +3,29 @@ import * as fs from 'fs';
 import { MediaDriver, MediaDriverInvokeOpts, MediaDriverResult, DurationConstraints, parseDuration } from './types';
 import { findSkillDir, runScript, parseMediaOutput } from './utils';
 
+/**
+ * Map aspect ratios to Kling's supported values: 16:9, 9:16, 1:1
+ */
+function mapToKlingAspectRatio(ratio: string): string {
+  const normalized = ratio.toLowerCase().trim();
+  
+  // Direct matches
+  if (normalized === '16:9' || normalized === '9:16' || normalized === '1:1') {
+    return normalized;
+  }
+  
+  // Map common ratios to closest Kling equivalent
+  const mappings: Record<string, string> = {
+    '4:3': '1:1',      // 4:3 (1.33) → 1:1 (1.00) closest square-ish
+    '3:4': '9:16',     // 3:4 (0.75) → 9:16 (0.56) closest vertical
+    '21:9': '16:9',    // 21:9 (2.33) → 16:9 (1.78) closest widescreen
+    '2:1': '16:9',     // 2:1 (2.00) → 16:9 (1.78) closest widescreen
+    '1:2': '9:16',     // 1:2 (0.50) → 9:16 (0.56) closest vertical
+  };
+  
+  return mappings[normalized] || '16:9'; // default fallback
+}
+
 /**
  * Kling AI video driver — uses official `klingai` ClawHub skill.
  *
@@ -39,6 +62,10 @@ export class KlingVideo implements MediaDriver {
     const rawDuration = Math.max(3, Math.min(15, Number(parseDuration(config))));
     const duration = String(rawDuration);
 
+    // Kling only supports 16:9, 9:16, 1:1 — map other ratios to closest match
+    const rawAspectRatio = String(config?.aspect_ratio ?? config?.size ?? '16:9');
+    const aspectRatio = mapToKlingAspectRatio(rawAspectRatio);
+
     const skillDir = await findSkillDir(this.slug);
     if (!skillDir) {
       throw new Error(
@@ -58,7 +85,7 @@ export class KlingVideo implements MediaDriver {
         '--prompt', prompt,
         '--output_dir', outputDir,
         '--duration', duration,
-        '--aspect_ratio', String(config?.aspect_ratio ?? config?.size ?? '16:9'),
+        '--aspect_ratio', aspectRatio,
         '--mode', 'pro',
       ],
       env: {

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

@@ -1,6 +1,6 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 
 /**
  * Find a skill directory by searching common skill roots
@@ -96,13 +96,9 @@ export interface RunScriptOpts {
 
 export function runScript(opts: RunScriptOpts): string {
   const { runner, script, args = [], stdin, env, cwd, timeout } = opts;
-  
-  const command = args.length > 0 
-    ? `${runner} ${JSON.stringify(script)} ${args.map(arg => JSON.stringify(arg)).join(' ')}`
-    : `${runner} ${JSON.stringify(script)}`;
 
   try {
-    return execSync(command, {
+    return execFileSync(runner, [script, ...args], {
       cwd,
       timeout,
       encoding: 'utf8',

package/src/lib/workflows/workflow-node-executor.ts

@@ -499,6 +499,12 @@ export async function executeWorkflowNodes(opts: {
       }
     }
 
+    if (kind === 'handoff') {
+      // Handoff nodes are supported in the pull-based worker (workflow-worker.ts).
+      // The synchronous executor doesn't support them yet — use `enqueue` + worker-tick instead.
+      throw new Error(`Node ${nodeLabel(node)}: handoff nodes require pull-based execution (use 'openclaw recipes workflows enqueue' + worker-tick)`);
+    }
+
     throw new Error(`Unsupported node kind: ${node.kind} (${nodeLabel(node)})`);
   }
 

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

@@ -27,6 +27,7 @@ export async function enqueueWorkflowRun(api: OpenClawPluginApi, opts: {
   teamId: string;
   workflowFile: string; // filename under shared-context/workflows/
   trigger?: { kind: string; at?: string };
+  triggerInput?: Record<string, unknown>;
 }) {
   const teamId = String(opts.teamId);
   const teamDir = resolveTeamDir(api, teamId);
@@ -94,6 +95,7 @@ export async function enqueueWorkflowRun(api: OpenClawPluginApi, opts: {
     workflow: { file: opts.workflowFile, id: workflow.id ?? null, name: workflow.name ?? null },
     ticket: { file: path.relative(teamDir, ticketPath), number: ticketNum, lane: initialLane },
     trigger,
+    ...(opts.triggerInput && Object.keys(opts.triggerInput).length > 0 ? { triggerInput: opts.triggerInput } : {}),
     status: 'queued',
     priority: 0,
     claimedBy: null,

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

@@ -1,6 +1,6 @@
 export type WorkflowLane = 'backlog' | 'in-progress' | 'testing' | 'done';
 
-export type WorkflowNodeKind = 'llm' | 'human_approval' | 'writeback' | 'tool' | 'start' | 'end' | string;
+export type WorkflowNodeKind = 'llm' | 'human_approval' | 'writeback' | 'tool' | 'handoff' | 'start' | 'end' | string;
 
 export type WorkflowEdgeOn = 'success' | 'error' | 'always';
 
@@ -85,6 +85,7 @@ export type RunLog = {
   workflow: { file: string; id: string | null; name: string | null };
   ticket: { file: string; number: string; lane: WorkflowLane };
   trigger: { kind: string; at?: string };
+  triggerInput?: Record<string, unknown>;
   status: string;
   // Scheduler/runner fields
   priority?: number;

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

@@ -1,5 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import crypto from 'node:crypto';
 import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
 import type { ToolTextResult } from '../../toolsInvoke';
 import { toolsInvoke } from '../../toolsInvoke';
@@ -7,7 +8,7 @@ import { resolveTeamDir } from '../workspace';
 import { getDriver } from './media-drivers/registry';
 import { GenericDriver } from './media-drivers/generic.driver';
 import { loadConfigEnv } from './media-drivers/utils';
-import type { WorkflowLane } from './workflow-types';
+import type { WorkflowLane, WorkflowNode, RunLog } from './workflow-types';
 import { dequeueNextTask, enqueueTask, releaseTaskClaim, compactQueue } from './workflow-queue';
 import { loadPriorLlmInput, loadProposedPostTextFromPriorNode } from './workflow-node-output-readers';
 import { readTextFile } from './workflow-runner-io';
@@ -16,6 +17,7 @@ import {
   asRecord, asString, isRecord,
   normalizeWorkflow,
   assertLane, ensureDir, fileExists,
+  isoCompact, nextTicketNumber, laneToStatus,
   moveRunTicket, appendRunLog, writeRunFile, loadRunFile,
   runFilePathFor, nodeLabel,
   loadNodeStatesFromRun, pickNextRunnableNodeIndex,
@@ -129,6 +131,18 @@ async function buildTemplateVars(
   } as Record<string, string>;
 
   const { run: runSnap } = await loadRunFile(teamDir, runsDir, 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 ?? '');
@@ -171,6 +185,330 @@ async function buildTemplateVars(
   return vars;
 }
 
+/**
+ * Enqueue a workflow run from a handoff node.
+ * This is a lightweight version of enqueueWorkflowRun that lives in the worker
+ * to avoid circular imports (workflow-runner re-exports workflow-worker).
+ */
+async function enqueueWorkflowRunForHandoff(api: OpenClawPluginApi, opts: {
+  teamId: string;
+  workflowFile: string;
+  trigger?: { kind: string; at?: string };
+  triggerInput?: Record<string, unknown>;
+}): Promise<{ runId: string; runLogPath: string }> {
+  const teamId = String(opts.teamId);
+  const teamDir = resolveTeamDir(api, teamId);
+  const sharedContextDir = path.join(teamDir, 'shared-context');
+  const workflowsDir = path.join(sharedContextDir, 'workflows');
+  const runsDir = path.join(sharedContextDir, 'workflow-runs');
+
+  const workflowPath = path.join(workflowsDir, opts.workflowFile);
+  const raw = await readTextFile(workflowPath);
+  const workflow = normalizeWorkflow(JSON.parse(raw));
+
+  if (!workflow.nodes?.length) throw new Error('Handoff target workflow has no nodes');
+
+  const firstLaneRaw = String(
+    workflow.nodes.find(n => n?.config && typeof n.config === 'object' && 'lane' in n.config)?.config?.lane ?? 'backlog'
+  );
+  assertLane(firstLaneRaw);
+  const initialLane: WorkflowLane = firstLaneRaw;
+
+  const runId = `${isoCompact()}-${crypto.randomBytes(4).toString('hex')}`;
+  await ensureDir(runsDir);
+
+  const runDir = path.join(runsDir, runId);
+  await ensureDir(runDir);
+  await Promise.all([
+    ensureDir(path.join(runDir, 'node-outputs')),
+    ensureDir(path.join(runDir, 'artifacts')),
+    ensureDir(path.join(runDir, 'approvals')),
+  ]);
+
+  const runLogPath = path.join(runDir, 'run.json');
+
+  const ticketNum = await nextTicketNumber(teamDir);
+  const slug = `workflow-run-${(workflow.id ?? path.basename(opts.workflowFile, path.extname(opts.workflowFile))).replace(/[^a-z0-9-]+/gi, '-').toLowerCase()}`;
+  const ticketFile = `${ticketNum}-${slug}.md`;
+
+  const laneDir = path.join(teamDir, 'work', initialLane);
+  await ensureDir(laneDir);
+  const ticketPath = path.join(laneDir, ticketFile);
+
+  const trigger = opts.trigger ?? { kind: 'handoff' };
+  const createdAt = new Date().toISOString();
+  const handoffMeta = opts.triggerInput?._handoff as Record<string, unknown> | undefined;
+
+  const md = [
+    `# ${ticketNum} — Workflow run: ${workflow.name ?? workflow.id ?? opts.workflowFile}\n\n`,
+    `Owner: lead`,
+    `Status: ${laneToStatus(initialLane)}`,
+    `\n## Run`,
+    `- workflow: ${path.relative(teamDir, workflowPath)}`,
+    `- run dir: ${path.relative(teamDir, runDir)}`,
+    `- run file: ${path.relative(teamDir, runLogPath)}`,
+    `- trigger: ${trigger.kind}${trigger.at ? ` @ ${trigger.at}` : ''}`,
+    `- runId: ${runId}`,
+    handoffMeta ? `- handoff from: team=${handoffMeta.sourceTeamId}, workflow=${handoffMeta.sourceWorkflowName}, run=${handoffMeta.sourceRunId}` : '',
+    `\n## Notes`,
+    `- Created by: handoff node`,
+    ``,
+  ].filter(Boolean).join('\n');
+
+  const initialLog: RunLog = {
+    runId,
+    createdAt,
+    updatedAt: createdAt,
+    teamId,
+    workflow: { file: opts.workflowFile, id: workflow.id ?? null, name: workflow.name ?? null },
+    ticket: { file: path.relative(teamDir, ticketPath), number: ticketNum, lane: initialLane },
+    trigger,
+    ...(opts.triggerInput && Object.keys(opts.triggerInput).length > 0 ? { triggerInput: opts.triggerInput } : {}),
+    status: 'queued',
+    priority: 0,
+    claimedBy: null,
+    claimExpiresAt: null,
+    nextNodeIndex: 0,
+    events: [{ ts: createdAt, type: 'run.enqueued', lane: initialLane, trigger: trigger.kind }],
+    nodeResults: [],
+  };
+
+  await Promise.all([
+    fs.writeFile(ticketPath, md, 'utf8'),
+    fs.writeFile(runLogPath, JSON.stringify(initialLog, null, 2), 'utf8'),
+  ]);
+
+  return { runId, runLogPath };
+}
+
+/**
+ * Check for waiting_handoff runs and resolve them if the target run has completed.
+ * Called at the start of each worker tick before processing the normal queue.
+ */
+async function checkWaitingHandoffs(api: OpenClawPluginApi, teamId: string, teamDir: string): Promise<Array<{ runId: string; nodeId: string; status: string }>> {
+  const results: Array<{ runId: string; nodeId: string; status: string }> = [];
+  const runsDir = path.join(teamDir, 'shared-context', 'workflow-runs');
+
+  // Scan all active runs for handoff-waits directories
+  let runDirs: string[] = [];
+  try {
+    const entries = await fs.readdir(runsDir, { withFileTypes: true });
+    runDirs = entries.filter(e => e.isDirectory()).map(e => e.name);
+  } catch { return results; }
+
+  for (const runDirName of runDirs) {
+    const runDir = path.join(runsDir, runDirName);
+    const handoffWaitDir = path.join(runDir, 'handoff-waits');
+
+    let waitFiles: string[] = [];
+    try {
+      const entries = await fs.readdir(handoffWaitDir);
+      waitFiles = entries.filter(f => f.endsWith('.json'));
+    } catch { continue; } // No handoff-waits dir
+
+    if (waitFiles.length === 0) continue;
+
+    // Load current run to verify it's still waiting_handoff
+    const runPath = path.join(runDir, 'run.json');
+    let run: RunLog;
+    try {
+      const raw = await fs.readFile(runPath, 'utf8');
+      run = JSON.parse(raw) as RunLog;
+    } catch { continue; }
+
+    if (run.status !== 'waiting_handoff') {
+      // Clean up stale wait markers
+      for (const wf of waitFiles) {
+        try { await fs.unlink(path.join(handoffWaitDir, wf)); } catch { /* ignore */ }
+      }
+      continue;
+    }
+
+    for (const waitFile of waitFiles) {
+      const waitPath = path.join(handoffWaitDir, waitFile);
+      let marker: {
+        nodeId: string; nodeIdx: number;
+        targetTeamId: string; targetWorkflowId: string; targetWorkflowFile: string;
+        targetRunId: string; startedAt: string; timeoutAt: string;
+        nodeOutputRel: string;
+      };
+      try {
+        marker = JSON.parse(await fs.readFile(waitPath, 'utf8'));
+      } catch { continue; }
+
+      // Check timeout
+      const now = Date.now();
+      if (new Date(marker.timeoutAt).getTime() <= now) {
+        // Timeout — fail the node
+        const failTs = new Date().toISOString();
+        await appendRunLog(runPath, (cur) => ({
+          ...cur,
+          status: 'error',
+          nodeStates: { ...(cur.nodeStates ?? {}), [marker.nodeId]: { status: 'error', ts: failTs, message: 'Handoff wait timed out' } },
+          events: [...cur.events, {
+            ts: failTs, type: 'node.error', nodeId: marker.nodeId, kind: 'handoff',
+            error: `Handoff wait timed out after ${Math.round((now - new Date(marker.startedAt).getTime()) / 1000)}s`,
+          }],
+        }));
+        try { await fs.unlink(waitPath); } catch { /* ignore */ }
+        results.push({ runId: run.runId, nodeId: marker.nodeId, status: 'timeout' });
+        continue;
+      }
+
+      // Check target run status
+      const targetTeamDir = resolveTeamDir(api, marker.targetTeamId);
+      const targetRunsDir = path.join(targetTeamDir, 'shared-context', 'workflow-runs');
+      let targetRun: RunLog;
+      try {
+        const loaded = await loadRunFile(targetTeamDir, targetRunsDir, marker.targetRunId);
+        targetRun = loaded.run;
+      } catch {
+        // Target run not found — may have been cleaned up; fail
+        const failTs = new Date().toISOString();
+        await appendRunLog(runPath, (cur) => ({
+          ...cur,
+          status: 'error',
+          nodeStates: { ...(cur.nodeStates ?? {}), [marker.nodeId]: { status: 'error', ts: failTs, message: 'Target run not found' } },
+          events: [...cur.events, {
+            ts: failTs, type: 'node.error', nodeId: marker.nodeId, kind: 'handoff',
+            error: `Target run ${marker.targetRunId} not found in team ${marker.targetTeamId}`,
+          }],
+        }));
+        try { await fs.unlink(waitPath); } catch { /* ignore */ }
+        results.push({ runId: run.runId, nodeId: marker.nodeId, status: 'error' });
+        continue;
+      }
+
+      if (targetRun.status === 'completed' || targetRun.status === 'done') {
+        // Target completed — resolve handoff node with target's output
+        const targetOutput: Record<string, unknown> = {};
+        if (Array.isArray(targetRun.nodeResults)) {
+          for (const nr of targetRun.nodeResults) {
+            if (nr.nodeId && typeof nr.nodeId === 'string') {
+              targetOutput[nr.nodeId as string] = nr;
+            }
+          }
+        }
+
+        const nodeOutputAbs = path.resolve(runDir, marker.nodeOutputRel);
+        await ensureDir(path.dirname(nodeOutputAbs));
+        const outputObj = {
+          runId: run.runId,
+          teamId,
+          nodeId: marker.nodeId,
+          kind: 'handoff',
+          completedAt: new Date().toISOString(),
+          text: JSON.stringify({
+            targetTeamId: marker.targetTeamId,
+            targetWorkflowId: marker.targetWorkflowId,
+            targetRunId: marker.targetRunId,
+            status: 'completed',
+            targetOutput,
+          }, null, 2),
+        };
+        await fs.writeFile(nodeOutputAbs, JSON.stringify(outputObj, null, 2) + '\n', 'utf8');
+
+        const completedTs = new Date().toISOString();
+
+        // Load workflow to find next node
+        const workflowsDir = path.join(teamDir, 'shared-context', 'workflows');
+        let workflow;
+        try {
+          const wfRaw = await fs.readFile(path.join(workflowsDir, run.workflow.file), 'utf8');
+          workflow = normalizeWorkflow(JSON.parse(wfRaw));
+        } catch { workflow = null; }
+
+        await appendRunLog(runPath, (cur) => ({
+          ...cur,
+          status: 'waiting_workers',
+          nextNodeIndex: marker.nodeIdx + 1,
+          nodeStates: { ...(cur.nodeStates ?? {}), [marker.nodeId]: { status: 'success', ts: completedTs } },
+          events: [...cur.events, {
+            ts: completedTs, type: 'node.completed', nodeId: marker.nodeId, kind: 'handoff',
+            targetTeamId: marker.targetTeamId, targetWorkflowId: marker.targetWorkflowId,
+            targetRunId: marker.targetRunId, mode: 'wait-for-completion',
+            nodeOutputPath: marker.nodeOutputRel,
+          }],
+        }));
+
+        // Enqueue next node if workflow is available
+        if (workflow) {
+          const updatedRun = (await loadRunFile(teamDir, runsDir, run.runId)).run;
+          const nextIdx = pickNextRunnableNodeIndex({ workflow, run: updatedRun });
+
+          if (nextIdx !== null && nextIdx >= 0 && nextIdx < workflow.nodes.length) {
+            const nextNode = workflow.nodes[nextIdx];
+            if (nextNode.type === 'end' || nextNode.type === 'start') {
+              // Auto-complete start/end
+              const autoTs = new Date().toISOString();
+              await appendRunLog(runPath, (cur) => ({
+                ...cur,
+                nextNodeIndex: nextIdx + 1,
+                nodeStates: { ...(cur.nodeStates ?? {}), [nextNode.id]: { status: 'success', ts: autoTs } },
+                events: [...cur.events, { ts: autoTs, type: 'node.completed', nodeId: nextNode.id, kind: nextNode.type }],
+              }));
+              // Check if run is done
+              const afterAutoRun = (await loadRunFile(teamDir, runsDir, run.runId)).run;
+              const afterNext = pickNextRunnableNodeIndex({ workflow, run: afterAutoRun });
+              if (afterNext === null) {
+                const doneTs = new Date().toISOString();
+                await appendRunLog(runPath, (cur) => ({
+                  ...cur,
+                  status: 'completed',
+                  events: [...cur.events, { ts: doneTs, type: 'run.completed' }],
+                }));
+              }
+            } else {
+              // Enqueue next real node to the appropriate agent's queue
+              const assignedAgent = String(nextNode.assignedTo ?? '').trim();
+              const targetAgent = assignedAgent || run.claimedBy || '';
+              if (targetAgent) {
+                await enqueueTask(teamDir, targetAgent, {
+                  teamId,
+                  runId: run.runId,
+                  nodeId: nextNode.id,
+                  kind: 'execute_node',
+                });
+              }
+            }
+          } else if (nextIdx === null) {
+            // All nodes done
+            const doneTs = new Date().toISOString();
+            await appendRunLog(runPath, (cur) => ({
+              ...cur,
+              status: 'completed',
+              events: [...cur.events, { ts: doneTs, type: 'run.completed' }],
+            }));
+          }
+        }
+
+        try { await fs.unlink(waitPath); } catch { /* ignore */ }
+        results.push({ runId: run.runId, nodeId: marker.nodeId, status: 'completed' });
+      } else if (targetRun.status === 'error' || targetRun.status === 'failed') {
+        // Target failed — fail the handoff node too
+        const failTs = new Date().toISOString();
+        const lastError = targetRun.events?.filter(e => e.type === 'node.error').pop();
+        await appendRunLog(runPath, (cur) => ({
+          ...cur,
+          status: 'error',
+          nodeStates: { ...(cur.nodeStates ?? {}), [marker.nodeId]: {
+            status: 'error', ts: failTs,
+            message: `Target workflow failed: ${lastError?.error ?? 'unknown error'}`,
+          } },
+          events: [...cur.events, {
+            ts: failTs, type: 'node.error', nodeId: marker.nodeId, kind: 'handoff',
+            error: `Target run ${marker.targetRunId} failed`,
+          }],
+        }));
+        try { await fs.unlink(waitPath); } catch { /* ignore */ }
+        results.push({ runId: run.runId, nodeId: marker.nodeId, status: 'error' });
+      }
+      // else: still running — do nothing, check again next tick
+    }
+  }
+  return results;
+}
+
 // eslint-disable-next-line complexity, max-lines-per-function
 export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
   teamId: string;
@@ -193,6 +531,14 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
 
   const results: Array<{ taskId: string; runId: string; nodeId: string; status: string }> = [];
 
+  // Check for waiting_handoff runs before processing normal queue
+  try {
+    const handoffResults = await checkWaitingHandoffs(api, teamId, teamDir);
+    for (const hr of handoffResults) {
+      results.push({ taskId: '', runId: hr.runId, nodeId: hr.nodeId, status: `handoff:${hr.status}` });
+    }
+  } catch { /* handoff check is best-effort */ }
+
   // Default lock TTL (used when we don't know the node config yet).
   // This must be comfortably larger than typical media generation durations.
   const DEFAULT_LOCK_TTL_MS = 30 * 60 * 1000;
@@ -1198,6 +1544,190 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
         events: [...cur.events, { ts: completedTs, type: 'node.completed', nodeId: node.id, kind: node.kind, nodeOutputPath: path.relative(teamDir, nodeOutputAbs) }],
         nodeResults: [...(cur.nodeResults ?? []), { nodeId: node.id, kind: node.kind, mediaType, agentId: agentIdMedia || agentId, nodeOutputPath: path.relative(teamDir, nodeOutputAbs), bytes: new TextEncoder().encode(text).byteLength }],
       }));
+    } else if (kind === 'handoff') {
+      // ── Handoff node: trigger a run on another workflow (optionally on a different team) ──
+      const config = asRecord((node as unknown as Record<string, unknown>)['config']);
+      const action = asRecord(node.action);
+
+      const targetTeamId = asString(config['targetTeamId'] ?? action['targetTeamId']).trim() || teamId;
+      const targetWorkflowId = asString(config['targetWorkflowId'] ?? action['targetWorkflowId']).trim();
+      if (!targetWorkflowId) throw new Error(`Node ${nodeLabel(node)} missing config.targetWorkflowId`);
+
+      // Resolve variable mapping: each key is the target's trigger input key, each value is a {{template}} expression
+      const variableMapping = asRecord(config['variableMapping'] ?? action['variableMapping']);
+
+      // Build template vars from prior node outputs
+      const vars = await buildTemplateVars(teamDir, runsDir, task.runId, workflowFile, workflow);
+      vars['node.id'] = node.id;
+
+      // Resolve mapped variables
+      const triggerInput: Record<string, unknown> = {
+        _handoff: {
+          sourceTeamId: teamId,
+          sourceWorkflowId: String(workflow.id ?? ''),
+          sourceWorkflowName: String(workflow.name ?? workflow.id ?? workflowFile),
+          sourceRunId: task.runId,
+          sourceNodeId: node.id,
+        },
+      };
+      for (const [targetKey, templateExpr] of Object.entries(variableMapping)) {
+        if (typeof templateExpr === 'string') {
+          triggerInput[targetKey] = templateReplace(templateExpr, vars);
+        }
+      }
+
+      // Find the target workflow file
+      const targetTeamDir = resolveTeamDir(api, targetTeamId);
+      const targetWorkflowsDir = path.join(targetTeamDir, 'shared-context', 'workflows');
+      let targetWorkflowFile = '';
+
+      // Try exact filename match first, then search by workflow id
+      const candidateFiles = [
+        `${targetWorkflowId}.json`,
+        `${targetWorkflowId}`,
+      ];
+      for (const candidate of candidateFiles) {
+        const candidatePath = path.join(targetWorkflowsDir, candidate);
+        if (await fileExists(candidatePath)) {
+          targetWorkflowFile = candidate;
+          break;
+        }
+      }
+
+      // If not found by filename, scan workflows for matching id
+      if (!targetWorkflowFile) {
+        try {
+          const wfFiles = await fs.readdir(targetWorkflowsDir);
+          for (const wf of wfFiles) {
+            if (!wf.endsWith('.json')) continue;
+            try {
+              const wfPath = path.join(targetWorkflowsDir, wf);
+              const wfRaw = await fs.readFile(wfPath, 'utf8');
+              const wfParsed = JSON.parse(wfRaw);
+              if (String(wfParsed.id ?? '') === targetWorkflowId || String(wfParsed.name ?? '') === targetWorkflowId) {
+                targetWorkflowFile = wf;
+                break;
+              }
+            } catch { /* skip unparseable workflows */ }
+          }
+        } catch { /* target workflows dir may not exist */ }
+      }
+
+      if (!targetWorkflowFile) {
+        throw new Error(`Handoff target workflow "${targetWorkflowId}" not found in team "${targetTeamId}"`);
+      }
+
+      // Enqueue the target workflow run with triggerInput
+      const enqueueResult = await enqueueWorkflowRunForHandoff(api, {
+        teamId: targetTeamId,
+        workflowFile: targetWorkflowFile,
+        trigger: { kind: 'handoff', at: new Date().toISOString() },
+        triggerInput,
+      });
+
+      const handoffMode = asString(config['mode'] ?? 'fire-and-forget').trim() || 'fire-and-forget';
+
+      // Save initial handoff output
+      const defaultNodeOutputRel = path.join('node-outputs', `${String(nodeIdx).padStart(3, '0')}-${node.id}.json`);
+      const nodeOutputRel = String(node?.output?.path ?? '').trim() || defaultNodeOutputRel;
+      const nodeOutputAbs = path.resolve(runDir, nodeOutputRel);
+      await ensureDir(path.dirname(nodeOutputAbs));
+
+      if (handoffMode === 'wait-for-completion') {
+        // Phase 2: Wait for target run to complete
+        const waitTimeoutMs = typeof config['waitTimeoutMs'] === 'number' ? config['waitTimeoutMs'] as number : 5 * 60 * 1000;
+
+        const outputObj = {
+          runId: task.runId,
+          teamId,
+          nodeId: node.id,
+          kind: 'handoff',
+          text: JSON.stringify({
+            targetTeamId,
+            targetWorkflowId,
+            targetWorkflowFile,
+            targetRunId: enqueueResult.runId,
+            status: 'waiting',
+            triggerInputKeys: Object.keys(triggerInput),
+          }, null, 2),
+        };
+        await fs.writeFile(nodeOutputAbs, JSON.stringify(outputObj, null, 2) + '\n', 'utf8');
+
+        // Write handoff wait marker so the polling loop can find it
+        const handoffWaitDir = path.join(runDir, 'handoff-waits');
+        await ensureDir(handoffWaitDir);
+        const waitMarker = {
+          nodeId: node.id,
+          nodeIdx,
+          targetTeamId,
+          targetWorkflowId,
+          targetWorkflowFile,
+          targetRunId: enqueueResult.runId,
+          startedAt: new Date().toISOString(),
+          timeoutAt: new Date(Date.now() + waitTimeoutMs).toISOString(),
+          nodeOutputRel,
+        };
+        await fs.writeFile(
+          path.join(handoffWaitDir, `${node.id}.json`),
+          JSON.stringify(waitMarker, null, 2) + '\n',
+          'utf8',
+        );
+
+        const waitingTs = new Date().toISOString();
+        await appendRunLog(runPath, (cur) => ({
+          ...cur,
+          status: 'waiting_handoff',
+          nodeStates: { ...(cur.nodeStates ?? {}), [node.id]: { status: 'waiting', ts: waitingTs } },
+          events: [...cur.events, {
+            ts: waitingTs, type: 'node.waiting_handoff', nodeId: node.id, kind: 'handoff',
+            targetTeamId, targetWorkflowId, targetRunId: enqueueResult.runId,
+            mode: 'wait-for-completion', timeoutAt: waitMarker.timeoutAt,
+          }],
+          nodeResults: [...(cur.nodeResults ?? []), {
+            nodeId: node.id, kind: 'handoff',
+            targetTeamId, targetWorkflowId, targetRunId: enqueueResult.runId,
+            nodeOutputPath: path.relative(teamDir, nodeOutputAbs),
+          }],
+        }));
+
+        results.push({ taskId: task.id, runId: task.runId, nodeId: task.nodeId, status: 'waiting_handoff' });
+        continue; // Skip the normal next-node enqueue logic
+      } else {
+        // Fire-and-forget: complete immediately
+        const outputObj = {
+          runId: task.runId,
+          teamId,
+          nodeId: node.id,
+          kind: 'handoff',
+          completedAt: new Date().toISOString(),
+          text: JSON.stringify({
+            targetTeamId,
+            targetWorkflowId,
+            targetWorkflowFile,
+            targetRunId: enqueueResult.runId,
+            status: 'enqueued',
+            triggerInputKeys: Object.keys(triggerInput),
+          }, null, 2),
+        };
+        await fs.writeFile(nodeOutputAbs, JSON.stringify(outputObj, null, 2) + '\n', 'utf8');
+
+        const completedTs = new Date().toISOString();
+        await appendRunLog(runPath, (cur) => ({
+          ...cur,
+          nextNodeIndex: nodeIdx + 1,
+          nodeStates: { ...(cur.nodeStates ?? {}), [node.id]: { status: 'success', ts: completedTs } },
+          events: [...cur.events, {
+            ts: completedTs, type: 'node.completed', nodeId: node.id, kind: 'handoff',
+            targetTeamId, targetWorkflowId, targetRunId: enqueueResult.runId,
+            nodeOutputPath: path.relative(teamDir, nodeOutputAbs),
+          }],
+          nodeResults: [...(cur.nodeResults ?? []), {
+            nodeId: node.id, kind: 'handoff',
+            targetTeamId, targetWorkflowId, targetRunId: enqueueResult.runId,
+            nodeOutputPath: path.relative(teamDir, nodeOutputAbs),
+          }],
+        }));
+      }
     } else {
       throw new Error(`Worker does not yet support node kind: ${kind}`);
     }
@@ -1212,6 +1742,11 @@ export async function runWorkflowWorkerTick(api: OpenClawPluginApi, opts: {
       continue;
     }
 
+    if (updated.status === 'waiting_handoff') {
+      results.push({ taskId: task.id, runId: task.runId, nodeId: task.nodeId, status: 'waiting_handoff' });
+      continue;
+    }
+
     let enqueueIdx = pickNextRunnableNodeIndex({ workflow, run: updated });
 
     // Auto-complete start/end nodes.