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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jiggai/recipes",
-  "version": "0.4.38",
+  "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-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,13 +1,15 @@
 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';
+import { classifyError, errorCategoryLabel } from './workflow-error-classify';
 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 +18,7 @@ import {
   asRecord, asString, isRecord,
   normalizeWorkflow,
   assertLane, ensureDir, fileExists,
+  isoCompact, nextTicketNumber, laneToStatus,
   moveRunTicket, appendRunLog, writeRunFile, loadRunFile,
   runFilePathFor, nodeLabel,
   loadNodeStatesFromRun, pickNextRunnableNodeIndex,
@@ -129,6 +132,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 +186,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 +532,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;
@@ -565,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,
@@ -573,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();
@@ -582,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;
       }
 
@@ -1010,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') {
@@ -1131,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,
@@ -1157,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) };
@@ -1166,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;
       }
 
@@ -1198,6 +1551,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 +1749,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.

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;
 }