@synergenius/flow-weaver 0.27.5 → 0.29.0

package/dist/cli/flow-weaver.mjs

@@ -5987,7 +5987,7 @@ var VERSION;
 var init_generated_version = __esm({
   "src/generated-version.ts"() {
     "use strict";
-    VERSION = "0.27.5";
+    VERSION = "0.29.0";
   }
 });
 
@@ -6645,18 +6645,28 @@ function generateScopeFunctionClosure(scopeName, parentNodeId, parentNodeType, w
       }
       const safeChildId = toValidIdentifier(child.id);
       const awaitPrefix = isAsync2 ? "await " : "";
+      const emitDebugHooks = !production;
+      let childIndent = "    ";
       lines.push(``);
       lines.push(`    // Execute: ${child.id} (${child.nodeType})`);
-      lines.push(`    scopedCtx.checkAborted('${child.id}');`);
-      lines.push(`    const ${safeChildId}Idx = scopedCtx.addExecution('${child.id}');`);
-      lines.push(`    if (typeof globalThis !== 'undefined') (globalThis as unknown as { __fw_current_node_id__?: string }).__fw_current_node_id__ = '${child.id}';`);
-      lines.push(`    ${awaitPrefix}scopedCtx.sendStatusChangedEvent({`);
-      lines.push(`      nodeTypeName: '${child.nodeType}',`);
-      lines.push(`      id: '${child.id}',`);
-      lines.push(`      executionIndex: ${safeChildId}Idx,`);
-      lines.push(`      status: 'RUNNING',`);
-      lines.push(`    });`);
-      lines.push(`    try {`);
+      if (emitDebugHooks) {
+        const awaitHook = isAsync2 ? "await " : "";
+        lines.push(`    let ${safeChildId}Idx: number = -1;`);
+        lines.push(`    if (${awaitHook}__ctrl__.beforeNode('${child.id}', scopedCtx)) {`);
+        childIndent = "      ";
+      }
+      lines.push(`${childIndent}scopedCtx.checkAborted('${child.id}');`);
+      const idxDecl = emitDebugHooks ? "" : "const ";
+      lines.push(`${childIndent}${idxDecl}${safeChildId}Idx = scopedCtx.addExecution('${child.id}');`);
+      lines.push(`${childIndent}if (typeof globalThis !== 'undefined') (globalThis as unknown as { __fw_current_node_id__?: string }).__fw_current_node_id__ = '${child.id}';`);
+      lines.push(`${childIndent}${awaitPrefix}scopedCtx.sendStatusChangedEvent({`);
+      lines.push(`${childIndent}  nodeTypeName: '${child.nodeType}',`);
+      lines.push(`${childIndent}  id: '${child.id}',`);
+      lines.push(`${childIndent}  executionIndex: ${safeChildId}Idx,`);
+      lines.push(`${childIndent}  status: 'RUNNING',`);
+      lines.push(`${childIndent}});`);
+      lines.push(`${childIndent}try {`);
+      const tryIndent = `${childIndent}  `;
       const argLines = [];
       const getCall = isAsync2 ? "await scopedCtx.getVariable" : "scopedCtx.getVariable";
       const childSetCall = isAsync2 ? `await scopedCtx.setVariable` : `scopedCtx.setVariable`;
@@ -6673,10 +6683,10 @@ function generateScopeFunctionClosure(scopeName, parentNodeId, parentNodeType, w
           const targetPortDef = childNodeType.inputs[targetPort];
           const portType = targetPortDef ? mapToTypeScript(targetPortDef.dataType, targetPortDef.tsType) : "unknown";
           argLines.push(
-            `      const ${varName} = ${getCall}({ id: '${parentNodeId}', portName: '${conn.from.port}', executionIndex: ${scopeParamIdxVar} }) as ${portType};`
+            `${tryIndent}const ${varName} = ${getCall}({ id: '${parentNodeId}', portName: '${conn.from.port}', executionIndex: ${scopeParamIdxVar} }) as ${portType};`
           );
           argLines.push(
-            `      ${childSetCall}({ id: '${child.id}', portName: '${targetPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, ${varName});`
+            `${tryIndent}${childSetCall}({ id: '${child.id}', portName: '${targetPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, ${varName});`
           );
           preHandledPorts.add(targetPort);
         }
@@ -6686,7 +6696,7 @@ function generateScopeFunctionClosure(scopeName, parentNodeId, parentNodeType, w
         workflow: scopeWorkflow,
         id: child.id,
         lines: argLines,
-        indent: `      `,
+        indent: tryIndent,
         getCall,
         isAsync: isAsync2,
         instanceParent: child.parent ? `${child.parent.id}.${child.parent.scope}` : void 0,
@@ -6699,11 +6709,11 @@ function generateScopeFunctionClosure(scopeName, parentNodeId, parentNodeType, w
       argLines.forEach((line) => lines.push(line));
       if (childNodeType.expression) {
         lines.push(
-          `      const ${safeChildId}Result = ${awaitPrefix}${child.nodeType}(${args.join(", ")});`
+          `${tryIndent}const ${safeChildId}Result = ${awaitPrefix}${child.nodeType}(${args.join(", ")});`
         );
       } else {
         lines.push(
-          `      const ${safeChildId}Result = ${awaitPrefix}${child.nodeType}(${args.join(", ")});`
+          `${tryIndent}const ${safeChildId}Result = ${awaitPrefix}${child.nodeType}(${args.join(", ")});`
         );
       }
       if (childNodeType.expression) {
@@ -6711,49 +6721,56 @@ function generateScopeFunctionClosure(scopeName, parentNodeId, parentNodeType, w
           const portDef = childNodeType.outputs[outPort];
           if (portDef.failure || isFailurePort(outPort)) {
             lines.push(
-              `      ${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, false);`
+              `${tryIndent}${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, false);`
             );
           } else if (portDef.isControlFlow || isSuccessPort(outPort)) {
             lines.push(
-              `      ${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, true);`
+              `${tryIndent}${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, true);`
             );
           } else {
             lines.push(
-              `      ${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, ${safeChildId}Result.${outPort});`
+              `${tryIndent}${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, ${safeChildId}Result.${outPort});`
             );
           }
         });
       } else {
         Object.keys(childNodeType.outputs || {}).forEach((outPort) => {
           lines.push(
-            `      ${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, ${safeChildId}Result.${outPort});`
+            `${tryIndent}${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, ${safeChildId}Result.${outPort});`
           );
         });
       }
-      lines.push(`      ${awaitPrefix}scopedCtx.sendStatusChangedEvent({`);
-      lines.push(`        nodeTypeName: '${child.nodeType}',`);
-      lines.push(`        id: '${child.id}',`);
-      lines.push(`        executionIndex: ${safeChildId}Idx,`);
-      lines.push(`        status: 'SUCCEEDED',`);
-      lines.push(`      });`);
-      lines.push(`    } catch (error: unknown) {`);
-      lines.push(`      const isCancellation = CancellationError.isCancellationError(error);`);
-      lines.push(`      ${awaitPrefix}scopedCtx.sendStatusChangedEvent({`);
-      lines.push(`        nodeTypeName: '${child.nodeType}',`);
-      lines.push(`        id: '${child.id}',`);
-      lines.push(`        executionIndex: ${safeChildId}Idx,`);
-      lines.push(`        status: isCancellation ? 'CANCELLED' : 'FAILED',`);
-      lines.push(`      });`);
-      lines.push(`      if (!isCancellation) {`);
-      lines.push(`        scopedCtx.sendLogErrorEvent({`);
-      lines.push(`          nodeTypeName: '${child.nodeType}',`);
-      lines.push(`          id: '${child.id}',`);
-      lines.push(`          executionIndex: ${safeChildId}Idx,`);
-      lines.push(`          error: error instanceof Error ? error.message : String(error),`);
-      lines.push(`        });`);
-      lines.push(`      }`);
-      lines.push(`      throw error;`);
-      lines.push(`    }`);
+      lines.push(`${tryIndent}${awaitPrefix}scopedCtx.sendStatusChangedEvent({`);
+      lines.push(`${tryIndent}  nodeTypeName: '${child.nodeType}',`);
+      lines.push(`${tryIndent}  id: '${child.id}',`);
+      lines.push(`${tryIndent}  executionIndex: ${safeChildId}Idx,`);
+      lines.push(`${tryIndent}  status: 'SUCCEEDED',`);
+      lines.push(`${tryIndent}});`);
+      if (emitDebugHooks) {
+        const awaitHook = isAsync2 ? "await " : "";
+        lines.push(`${tryIndent}${awaitHook}__ctrl__.afterNode('${child.id}', scopedCtx);`);
+      }
+      lines.push(`${childIndent}} catch (error: unknown) {`);
+      lines.push(`${tryIndent}const isCancellation = CancellationError.isCancellationError(error);`);
+      lines.push(`${tryIndent}${awaitPrefix}scopedCtx.sendStatusChangedEvent({`);
+      lines.push(`${tryIndent}  nodeTypeName: '${child.nodeType}',`);
+      lines.push(`${tryIndent}  id: '${child.id}',`);
+      lines.push(`${tryIndent}  executionIndex: ${safeChildId}Idx,`);
+      lines.push(`${tryIndent}  status: isCancellation ? 'CANCELLED' : 'FAILED',`);
+      lines.push(`${tryIndent}});`);
+      lines.push(`${tryIndent}if (!isCancellation) {`);
+      lines.push(`${tryIndent}  scopedCtx.sendLogErrorEvent({`);
+      lines.push(`${tryIndent}    nodeTypeName: '${child.nodeType}',`);
+      lines.push(`${tryIndent}    id: '${child.id}',`);
+      lines.push(`${tryIndent}    executionIndex: ${safeChildId}Idx,`);
+      lines.push(`${tryIndent}    error: error instanceof Error ? error.message : String(error),`);
+      lines.push(`${tryIndent}  });`);
+      lines.push(`${tryIndent}}`);
+      lines.push(`${tryIndent}throw error;`);
+      lines.push(`${childIndent}}`);
+      if (emitDebugHooks) {
+        lines.push(`    }`);
+      }
     });
     lines.push(``);
   }
@@ -14022,8 +14039,9 @@ function generateCode(ast, options) {
     }
   }
   const npmPackageNodes = ast.nodeTypes.filter((n7) => n7.importSource);
+  const referencedNodeTypes = new Set(ast.instances.map((i) => i.nodeType));
   const localNodes = ast.nodeTypes.filter(
-    (n7) => !n7.importSource && n7.sourceLocation?.file === ast.sourceFile
+    (n7) => !n7.importSource && (n7.sourceLocation?.file === ast.sourceFile || !n7.sourceLocation && n7.functionText && n7.helperText != null && referencedNodeTypes.has(n7.name))
   );
   const importedNodes = ast.nodeTypes.filter(
     (n7) => !n7.importSource && n7.sourceLocation?.file !== ast.sourceFile
@@ -14134,9 +14152,21 @@ function generateCode(ast, options) {
     if (inlineFunctions.length > 0) {
       lines.push("");
       addLine();
+      const emittedHelpers = /* @__PURE__ */ new Set();
+      inlineFunctions.forEach((node) => {
+        if (node.importSource) return;
+        const helperText = production ? node.helperTextProduction ?? null : node.helperText ?? null;
+        if (helperText && !emittedHelpers.has(helperText)) {
+          emittedHelpers.add(helperText);
+          lines.push(helperText);
+          helperText.split("\n").forEach(() => addLine());
+          lines.push("");
+          addLine();
+        }
+      });
       inlineFunctions.forEach((node) => {
         if (node.importSource) return;
-        const functionText = node.functionText;
+        const functionText = production && node.functionTextProduction != null ? node.functionTextProduction : node.functionText;
         if (functionText) {
           const functionWithoutDecorators = removeDecorators(functionText);
           if (node.sourceLocation) {
@@ -15258,12 +15288,62 @@ function generateInPlace(sourceCode, ast, options = {}) {
     if (nodeType.sourceLocation?.file && path2.resolve(nodeType.sourceLocation.file) !== path2.resolve(ast.sourceFile)) {
       continue;
     }
+    if (!nodeType.sourceLocation && nodeType.helperText != null) {
+      continue;
+    }
     const nodeTypeResult = replaceNodeTypeJSDoc(result, nodeType);
     if (nodeTypeResult.changed) {
       result = nodeTypeResult.code;
       hasChanges = true;
     }
   }
+  const usedNodeTypes = new Set(ast.instances.map((i) => i.nodeType));
+  const builtInNodes = ast.nodeTypes.filter(
+    (nt2) => !nt2.sourceLocation && nt2.functionText && nt2.helperText != null && usedNodeTypes.has(nt2.name)
+  );
+  if (builtInNodes.length > 0) {
+    const workflowFnPattern = new RegExp(
+      `(/\\*\\*[\\s\\S]*?@flowWeaver\\s+workflow[\\s\\S]*?\\*/)\\s*\\n\\s*(?:export\\s+)?(?:async\\s+)?function\\s+${ast.functionName}\\b`
+    );
+    const match = result.match(workflowFnPattern);
+    if (match && match.index !== void 0) {
+      const insertionLines = [];
+      const emittedHelpers = /* @__PURE__ */ new Set();
+      for (const node of builtInNodes) {
+        const helperText = production ? node.helperTextProduction ?? null : node.helperText ?? null;
+        if (helperText && !emittedHelpers.has(helperText)) {
+          emittedHelpers.add(helperText);
+          insertionLines.push(helperText);
+          insertionLines.push("");
+        }
+      }
+      for (const node of builtInNodes) {
+        const funcText = production && node.functionTextProduction != null ? node.functionTextProduction : node.functionText;
+        if (funcText) {
+          const portAnnotations = [];
+          portAnnotations.push("/**");
+          portAnnotations.push(` * @flowWeaver nodeType`);
+          for (const [name, port] of Object.entries(node.inputs)) {
+            if (name === "execute") continue;
+            const optPrefix = port.optional ? "[" : "";
+            const optSuffix = port.optional ? "]" : "";
+            portAnnotations.push(` * @input ${optPrefix}${name}${optSuffix} - ${port.label || name}`);
+          }
+          for (const [name, port] of Object.entries(node.outputs)) {
+            if (name === "onSuccess" || name === "onFailure") continue;
+            portAnnotations.push(` * @output ${name} - ${port.label || name}`);
+          }
+          portAnnotations.push(" */");
+          insertionLines.push(portAnnotations.join("\n"));
+          insertionLines.push(funcText);
+          insertionLines.push("");
+        }
+      }
+      const insertionCode = insertionLines.join("\n");
+      result = result.slice(0, match.index) + insertionCode + "\n" + result.slice(match.index);
+      hasChanges = true;
+    }
+  }
   const cleanupResult = removeOrphanedNodeTypeFunctions(result, ast, allWorkflows);
   if (cleanupResult.changed) {
     result = cleanupResult.code;
@@ -27243,6 +27323,306 @@ var init_coercion_types = __esm({
   }
 });
 
+// src/built-in-nodes/generated-registry.ts
+var BUILT_IN_NODE_TYPES;
+var init_generated_registry = __esm({
+  "src/built-in-nodes/generated-registry.ts"() {
+    "use strict";
+    BUILT_IN_NODE_TYPES = [
+      {
+        type: "NodeType",
+        name: "delay",
+        functionName: "delay",
+        isAsync: true,
+        hasSuccessPort: true,
+        hasFailurePort: true,
+        executeWhen: "CONJUNCTION",
+        variant: "FUNCTION",
+        inputs: {
+          execute: { dataType: "STEP", label: "Execute" },
+          duration: { dataType: "STRING", label: 'Duration to sleep (e.g. "30s", "5m", "1h", "2d")', tsType: "string" }
+        },
+        outputs: {
+          onSuccess: { dataType: "STEP", label: "On Success", isControlFlow: true },
+          onFailure: { dataType: "STEP", label: "On Failure", isControlFlow: true, failure: true },
+          elapsed: { dataType: "BOOLEAN", label: "Always true after sleep completes", tsType: "boolean" }
+        },
+        helperText: `
+function __fw_getMockConfig() {
+    return globalThis.__fw_mocks__;
+}
+
+function __fw_lookupMock(section, key) {
+    if (!section)
+        return undefined;
+    const nodeId = globalThis.__fw_current_node_id__;
+    if (nodeId) {
+        const qualified = section[\`\${nodeId}:\${key}\`];
+        if (qualified !== undefined)
+            return qualified;
+    }
+    return section[key];
+}
+`.trim(),
+        helperTextProduction: void 0,
+        functionText: `
+async function delay(execute, duration) {
+    if (!execute)
+        return { onSuccess: false, onFailure: false, elapsed: false };
+    const mocks = __fw_getMockConfig();
+    if (mocks?.fast) {
+        await new Promise((resolve) => setTimeout(resolve, 1));
+    }
+    else {
+        const ms = __fw_parseDuration(duration);
+        await new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    return { onSuccess: true, onFailure: false, elapsed: true };
+}
+function __fw_parseDuration(duration) {
+    const match = duration.match(/^(\\d+)(ms|s|m|h|d)$/);
+    if (!match)
+        return 0;
+    const [, value, unit] = match;
+    const multipliers = { ms: 1, s: 1000, m: 60000, h: 3600000, d: 86400000 };
+    return parseInt(value) * (multipliers[unit] || 0);
+}
+`.trim(),
+        functionTextProduction: `
+async function delay(execute, duration) {
+    if (!execute)
+        return { onSuccess: false, onFailure: false, elapsed: false };
+    const ms = __fw_parseDuration(duration);
+    await new Promise((resolve) => setTimeout(resolve, ms));
+    return { onSuccess: true, onFailure: false, elapsed: true };
+}
+function __fw_parseDuration(duration) {
+    const match = duration.match(/^(\\d+)(ms|s|m|h|d)$/);
+    if (!match)
+        return 0;
+    const [, value, unit] = match;
+    const multipliers = { ms: 1, s: 1000, m: 60000, h: 3600000, d: 86400000 };
+    return parseInt(value) * (multipliers[unit] || 0);
+}
+`.trim()
+      },
+      {
+        type: "NodeType",
+        name: "waitForEvent",
+        functionName: "waitForEvent",
+        isAsync: true,
+        hasSuccessPort: true,
+        hasFailurePort: true,
+        executeWhen: "CONJUNCTION",
+        variant: "FUNCTION",
+        inputs: {
+          execute: { dataType: "STEP", label: "Execute" },
+          eventName: { dataType: "STRING", label: 'Event name to wait for (e.g. "app/approval.received")', tsType: "string" },
+          match: { dataType: "STRING", label: 'Field to match between trigger and waited event (e.g. "data.requestId")', tsType: "string", optional: true },
+          timeout: { dataType: "STRING", label: 'Max wait time (e.g. "24h", "7d"). Empty = no timeout', tsType: "string", optional: true }
+        },
+        outputs: {
+          onSuccess: { dataType: "STEP", label: "On Success", isControlFlow: true },
+          onFailure: { dataType: "STEP", label: "On Failure", isControlFlow: true, failure: true },
+          eventData: { dataType: "OBJECT", label: "The received event's data payload", tsType: "object" }
+        },
+        helperText: `
+function __fw_getMockConfig() {
+    return globalThis.__fw_mocks__;
+}
+
+function __fw_lookupMock(section, key) {
+    if (!section)
+        return undefined;
+    const nodeId = globalThis.__fw_current_node_id__;
+    if (nodeId) {
+        const qualified = section[\`\${nodeId}:\${key}\`];
+        if (qualified !== undefined)
+            return qualified;
+    }
+    return section[key];
+}
+`.trim(),
+        helperTextProduction: void 0,
+        functionText: `
+async function waitForEvent(execute, eventName, match, timeout) {
+    if (!execute)
+        return { onSuccess: false, onFailure: false, eventData: {} };
+    const mocks = __fw_getMockConfig();
+    if (mocks) {
+        const mockData = __fw_lookupMock(mocks.events, eventName);
+        if (mockData !== undefined) {
+            return { onSuccess: true, onFailure: false, eventData: mockData };
+        }
+        return { onSuccess: false, onFailure: true, eventData: {} };
+    }
+    return { onSuccess: true, onFailure: false, eventData: {} };
+}
+`.trim(),
+        functionTextProduction: `
+async function waitForEvent(execute, eventName, match, timeout) {
+    if (!execute)
+        return { onSuccess: false, onFailure: false, eventData: {} };
+    return { onSuccess: true, onFailure: false, eventData: {} };
+}
+`.trim()
+      },
+      {
+        type: "NodeType",
+        name: "invokeWorkflow",
+        functionName: "invokeWorkflow",
+        isAsync: true,
+        hasSuccessPort: true,
+        hasFailurePort: true,
+        executeWhen: "CONJUNCTION",
+        variant: "FUNCTION",
+        inputs: {
+          execute: { dataType: "STEP", label: "Execute" },
+          functionId: { dataType: "STRING", label: 'Function ID of the workflow to invoke (e.g. "my-service/sub-workflow")', tsType: "string" },
+          payload: { dataType: "OBJECT", label: "Data to pass as event.data to the invoked function", tsType: "object" },
+          timeout: { dataType: "STRING", label: 'Max wait time (e.g. "1h")', tsType: "string", optional: true }
+        },
+        outputs: {
+          onSuccess: { dataType: "STEP", label: "On Success", isControlFlow: true },
+          onFailure: { dataType: "STEP", label: "On Failure", isControlFlow: true, failure: true },
+          result: { dataType: "OBJECT", label: "Return value from the invoked function", tsType: "object" }
+        },
+        helperText: `
+function __fw_getMockConfig() {
+    return globalThis.__fw_mocks__;
+}
+
+function __fw_lookupMock(section, key) {
+    if (!section)
+        return undefined;
+    const nodeId = globalThis.__fw_current_node_id__;
+    if (nodeId) {
+        const qualified = section[\`\${nodeId}:\${key}\`];
+        if (qualified !== undefined)
+            return qualified;
+    }
+    return section[key];
+}
+`.trim(),
+        helperTextProduction: void 0,
+        functionText: `
+async function invokeWorkflow(execute, functionId, payload, timeout) {
+    if (!execute)
+        return { onSuccess: false, onFailure: false, result: {} };
+    const mocks = __fw_getMockConfig();
+    if (mocks) {
+        const mockResult = __fw_lookupMock(mocks.invocations, functionId);
+        if (mockResult !== undefined) {
+            return { onSuccess: true, onFailure: false, result: mockResult };
+        }
+        return { onSuccess: false, onFailure: true, result: {} };
+    }
+    const registry = globalThis.__fw_workflow_registry__;
+    if (registry?.[functionId]) {
+        try {
+            const result = await registry[functionId](true, payload);
+            return { onSuccess: true, onFailure: false, result: result ?? {} };
+        }
+        catch {
+            return { onSuccess: false, onFailure: true, result: {} };
+        }
+    }
+    return { onSuccess: true, onFailure: false, result: {} };
+}
+`.trim(),
+        functionTextProduction: `
+async function invokeWorkflow(execute, functionId, payload, timeout) {
+    if (!execute)
+        return { onSuccess: false, onFailure: false, result: {} };
+    const registry = globalThis.__fw_workflow_registry__;
+    if (registry?.[functionId]) {
+        try {
+            const result = await registry[functionId](true, payload);
+            return { onSuccess: true, onFailure: false, result: result ?? {} };
+        }
+        catch {
+            return { onSuccess: false, onFailure: true, result: {} };
+        }
+    }
+    return { onSuccess: true, onFailure: false, result: {} };
+}
+`.trim()
+      },
+      {
+        type: "NodeType",
+        name: "waitForAgent",
+        functionName: "waitForAgent",
+        isAsync: true,
+        hasSuccessPort: true,
+        hasFailurePort: true,
+        executeWhen: "CONJUNCTION",
+        variant: "FUNCTION",
+        inputs: {
+          execute: { dataType: "STEP", label: "Execute" },
+          agentId: { dataType: "STRING", label: "Agent/task identifier", tsType: "string" },
+          context: { dataType: "OBJECT", label: "Context data to send to the agent", tsType: "object" },
+          prompt: { dataType: "STRING", label: "Message to display when requesting input", tsType: "string", optional: true }
+        },
+        outputs: {
+          onSuccess: { dataType: "STEP", label: "On Success", isControlFlow: true },
+          onFailure: { dataType: "STEP", label: "On Failure", isControlFlow: true, failure: true },
+          agentResult: { dataType: "OBJECT", label: "Result returned by the agent", tsType: "object" }
+        },
+        helperText: `
+function __fw_getMockConfig() {
+    return globalThis.__fw_mocks__;
+}
+
+function __fw_lookupMock(section, key) {
+    if (!section)
+        return undefined;
+    const nodeId = globalThis.__fw_current_node_id__;
+    if (nodeId) {
+        const qualified = section[\`\${nodeId}:\${key}\`];
+        if (qualified !== undefined)
+            return qualified;
+    }
+    return section[key];
+}
+`.trim(),
+        helperTextProduction: void 0,
+        functionText: `
+async function waitForAgent(execute, agentId, context, prompt) {
+    if (!execute)
+        return { onSuccess: false, onFailure: false, agentResult: {} };
+    const mocks = __fw_getMockConfig();
+    const mockResult = __fw_lookupMock(mocks?.agents, agentId);
+    if (mockResult !== undefined) {
+        return { onSuccess: true, onFailure: false, agentResult: mockResult };
+    }
+    if (mocks?.agents) {
+        return { onSuccess: false, onFailure: true, agentResult: {} };
+    }
+    const channel = globalThis.__fw_agent_channel__;
+    if (channel) {
+        const result = await channel.request({ agentId, context, prompt });
+        return { onSuccess: true, onFailure: false, agentResult: result };
+    }
+    return { onSuccess: true, onFailure: false, agentResult: {} };
+}
+`.trim(),
+        functionTextProduction: `
+async function waitForAgent(execute, agentId, context, prompt) {
+    if (!execute)
+        return { onSuccess: false, onFailure: false, agentResult: {} };
+    const channel = globalThis.__fw_agent_channel__;
+    if (channel) {
+        const result = await channel.request({ agentId, context, prompt });
+        return { onSuccess: true, onFailure: false, agentResult: result };
+    }
+    return { onSuccess: true, onFailure: false, agentResult: {} };
+}
+`.trim()
+      }
+    ];
+  }
+});
+
 // src/parser/tag-registry.ts
 var TagHandlerRegistry, tagHandlerRegistry;
 var init_tag_registry = __esm({
@@ -27571,6 +27951,7 @@ var init_parser2 = __esm({
     init_shared_project();
     init_lru_cache();
     init_coercion_types();
+    init_generated_registry();
     init_tag_registry();
     AnnotationParser = class {
       project;
@@ -27714,7 +28095,7 @@ var init_parser2 = __esm({
             }
           }
         }
-        const inferredNodeTypes = this.inferNodeTypesFromUnannotated(sourceFile, nodeTypes);
+        const inferredNodeTypes = this.inferNodeTypesFromUnannotated(sourceFile, nodeTypes, localNodeTypes, warnings);
         nodeTypes.push(...inferredNodeTypes);
         const workflows = this.extractWorkflows(sourceFile, nodeTypes, filePath, errors2, warnings);
         const patterns = this.extractPatterns(sourceFile, nodeTypes, filePath, errors2, warnings);
@@ -27754,7 +28135,7 @@ var init_parser2 = __esm({
         const workflowSignatures = this.extractWorkflowSignatures(sourceFile, virtualPath, warnings);
         const sameFileWorkflowNodeTypes = workflowSignatures.map((wf) => this.workflowToNodeType(wf));
         const nodeTypes = [...localNodeTypes, ...sameFileWorkflowNodeTypes];
-        const inferredNodeTypes = this.inferNodeTypesFromUnannotated(sourceFile, nodeTypes);
+        const inferredNodeTypes = this.inferNodeTypesFromUnannotated(sourceFile, nodeTypes, localNodeTypes, warnings);
         nodeTypes.push(...inferredNodeTypes);
         const workflows = this.extractWorkflows(sourceFile, nodeTypes, virtualPath, errors2, warnings);
         const patterns = this.extractPatterns(sourceFile, nodeTypes, virtualPath, errors2, warnings);
@@ -27986,7 +28367,7 @@ var init_parser2 = __esm({
         if (imp.importSource.startsWith(".")) {
           return this.resolveLocalImportAnnotation(imp, currentDir, warnings);
         } else {
-          return this.resolveNpmImportAnnotation(imp, currentDir);
+          return this.resolveNpmImportAnnotation(imp, currentDir, warnings);
         }
       }
       /**
@@ -28031,7 +28412,7 @@ var init_parser2 = __esm({
       /**
        * Resolve an npm package @fwImport to a node type by reading .d.ts declarations.
        */
-      resolveNpmImportAnnotation(imp, currentDir) {
+      resolveNpmImportAnnotation(imp, currentDir, warnings) {
         const cacheKey = `npm:${imp.importSource}`;
         if (this.importCache.has(cacheKey)) {
           const cached2 = this.importCache.get(cacheKey);
@@ -28055,6 +28436,9 @@ var init_parser2 = __esm({
         }
         const dtsPath = resolvePackageTypesPath(imp.importSource, currentDir);
         if (!dtsPath) {
+          warnings.push(
+            `@fwImport: Package "${imp.importSource}" has no type declarations (.d.ts). Install @types/${imp.importSource} or add a local wrapper with @flowWeaver nodeType annotations.`
+          );
           return this.createImportStub(imp);
         }
         try {
@@ -28084,7 +28468,13 @@ var init_parser2 = __esm({
           if (found) {
             return { ...found, name: imp.name, importSource: imp.importSource };
           }
-        } catch {
+          warnings.push(
+            `@fwImport: Function "${imp.functionName}" not found in type declarations for "${imp.importSource}". Available exports: ${allNodeTypes.map((nt2) => nt2.functionName).join(", ") || "(none)"}.`
+          );
+        } catch (err) {
+          warnings.push(
+            `@fwImport: Failed to parse type declarations for "${imp.importSource}": ${err.message}. Node "${imp.name}" will use a generic stub.`
+          );
         }
         return this.createImportStub(imp);
       }
@@ -28383,6 +28773,18 @@ ${fn.getText()}` : fn.getText();
           const importedNpmNodeTypes = (config2.imports || []).map(
             (imp) => this.resolveImportAnnotation(imp, filePath, warnings)
           );
+          for (const nt2 of importedNpmNodeTypes) {
+            const dataInputs = Object.keys(nt2.inputs).filter((p) => p !== "execute");
+            const nonControlOutputs = Object.keys(nt2.outputs).filter(
+              (p) => p !== "onSuccess" && p !== "onFailure"
+            );
+            const isStubOnly = nonControlOutputs.length === 1 && nonControlOutputs[0] === "result" && nt2.outputs.result?.dataType === "ANY";
+            if (dataInputs.length === 0 && isStubOnly) {
+              warnings.push(
+                `Could not infer ports for "${nt2.functionName}" from "${nt2.importSource}". Wrap it in a local function with @flowWeaver nodeType annotations instead.`
+              );
+            }
+          }
           const allAvailableNodeTypes = [...availableNodeTypes, ...importedNpmNodeTypes];
           const instances = (config2.instances || []).map((inst) => {
             const nodeTypeExists = allAvailableNodeTypes.some(
@@ -28733,7 +29135,7 @@ ${fn.getText()}` : fn.getText();
        * nodeType annotation, we infer an expression node type from its TypeScript
        * signature. Phase 1: same-file functions only.
        */
-      inferNodeTypesFromUnannotated(sourceFile, existingNodeTypes) {
+      inferNodeTypesFromUnannotated(sourceFile, existingNodeTypes, localNodeTypes, warnings) {
         const allFunctions = extractFunctionLikes(sourceFile);
         const referencedTypes = /* @__PURE__ */ new Set();
         for (const fn of allFunctions) {
@@ -28757,8 +29159,24 @@ ${fn.getText()}` : fn.getText();
         if (unresolvedTypes.size === 0) return [];
         const inferredNodeTypes = [];
         const alreadyInferred = /* @__PURE__ */ new Set();
+        const builtInByName = new Map(BUILT_IN_NODE_TYPES.map((nt2) => [nt2.name, nt2]));
+        const annotatedNames = new Set(localNodeTypes.map((nt2) => nt2.functionName));
         for (const unresolvedType of unresolvedTypes) {
           if (alreadyInferred.has(unresolvedType)) continue;
+          const builtIn = builtInByName.get(unresolvedType);
+          if (builtIn) {
+            inferredNodeTypes.push(builtIn);
+            alreadyInferred.add(unresolvedType);
+            if (!annotatedNames.has(unresolvedType)) {
+              const shadowFn = allFunctions.find((fn) => fn.getName() === unresolvedType && !this.hasFlowWeaverAnnotation(fn));
+              if (shadowFn) {
+                warnings.push(
+                  `Function '${unresolvedType}' exists in this file but is not annotated with @flowWeaver nodeType. The built-in '${unresolvedType}' will be used instead. Add @flowWeaver nodeType to use your version.`
+                );
+              }
+            }
+            continue;
+          }
           const matchedFn = allFunctions.find((fn) => {
             if (fn.getName() !== unresolvedType) return false;
             return !this.hasFlowWeaverAnnotation(fn);
@@ -29005,6 +29423,10 @@ ${fn.getText()}` : fn.getText();
             const nextInputs = getInputPorts(nextId);
             for (const [inputName] of Object.entries(nextInputs)) {
               if (isControlFlowPort(inputName)) continue;
+              const alreadyConnected = connections.some(
+                (c) => c.to.node === nextId && c.to.port === inputName
+              );
+              if (alreadyConnected) continue;
               for (let j2 = i; j2 >= 0; j2--) {
                 const ancestorId = steps[j2].node;
                 const ancestorOutputs = getOutputPorts(ancestorId);
@@ -37919,7 +38341,7 @@ function getDependents(ast, nodeId) {
   });
   return Array.from(dependents);
 }
-function getTopologicalOrder(ast) {
+function getTopologicalOrder(ast, options) {
   const mainInstances = getMainFlowInstances(ast);
   const mainConnections = getMainFlowConnections(ast);
   const inDegree = /* @__PURE__ */ new Map();
@@ -37958,6 +38380,30 @@ function getTopologicalOrder(ast) {
   if (result.length !== mainInstances.length) {
     throw new Error("Cannot compute topological order: workflow contains cycles");
   }
+  if (options?.includeScopedChildren) {
+    const scopedChildren = ast.instances.filter(
+      (inst) => isPerPortScopedChild(inst, ast, ast.nodeTypes)
+    );
+    const expanded = [];
+    const scopedByParent = /* @__PURE__ */ new Map();
+    for (const child of scopedChildren) {
+      if (child.parent) {
+        const parentId = child.parent.id;
+        if (!scopedByParent.has(parentId)) {
+          scopedByParent.set(parentId, []);
+        }
+        scopedByParent.get(parentId).push(child.id);
+      }
+    }
+    for (const nodeId of result) {
+      expanded.push(nodeId);
+      const children = scopedByParent.get(nodeId);
+      if (children) {
+        expanded.push(...children);
+      }
+    }
+    return expanded;
+  }
   return result;
 }
 function findIsolatedNodes(ast) {
@@ -58608,9 +59054,9 @@ function printNocodeGuidance(_projectName) {
   logger.newline();
   logger.log(`  ${logger.bold("Useful commands")}`);
   logger.newline();
-  logger.log(`    fw run src/*.ts         ${logger.dim("Run your workflow")}`);
-  logger.log(`    fw diagram src/*.ts     ${logger.dim("See a visual diagram")}`);
-  logger.log(`    fw mcp-setup            ${logger.dim("Connect more AI editors")}`);
+  logger.log(`    npx fw run src/*.ts         ${logger.dim("Run your workflow")}`);
+  logger.log(`    npx fw diagram src/*.ts     ${logger.dim("See a visual diagram")}`);
+  logger.log(`    npx fw mcp-setup            ${logger.dim("Connect more AI editors")}`);
 }
 function printVibecoderGuidance() {
   logger.newline();
@@ -58628,17 +59074,17 @@ function printLowcodeGuidance() {
   logger.newline();
   logger.log(`  ${logger.bold("Explore and customize")}`);
   logger.newline();
-  logger.log(`    fw templates            ${logger.dim("List all 16 workflow templates")}`);
-  logger.log(`    fw describe src/*.ts     ${logger.dim("See the workflow structure")}`);
-  logger.log(`    fw docs annotations     ${logger.dim("Annotation reference")}`);
+  logger.log(`    npx fw templates            ${logger.dim("List all 16 workflow templates")}`);
+  logger.log(`    npx fw describe src/*.ts     ${logger.dim("See the workflow structure")}`);
+  logger.log(`    npx fw docs annotations     ${logger.dim("Annotation reference")}`);
   logger.newline();
   logger.log(`  Your project includes an example in ${logger.highlight("examples/")} to study.`);
   logger.log(`  With MCP connected, AI can help modify nodes and connections.`);
 }
 function printExpertGuidance() {
   logger.newline();
-  logger.log(`    fw mcp-setup            ${logger.dim("Connect AI editors (Claude, Cursor, VS Code)")}`);
-  logger.log(`    fw docs                 ${logger.dim("Browse reference docs")}`);
+  logger.log(`    npx fw mcp-setup            ${logger.dim("Connect AI editors (Claude, Cursor, VS Code)")}`);
+  logger.log(`    npx fw docs                 ${logger.dim("Browse reference docs")}`);
 }
 function pad(displayName, width) {
   const padding = Math.max(1, width - displayName.length);
@@ -59588,16 +60034,19 @@ ${workflowCode}`;
       "",
       `import { ${workflowName} } from './${workflowJsFile}';`,
       "",
-      "try {",
-      `  const result = ${workflowName}(true, { data: { message: 'hello world' } });`,
-      "  console.log(result);",
-      "} catch (e) {",
+      "async function main() {",
+      `  const result = await ${workflowName}(true, { data: { message: 'hello world' } });`,
+      "  console.log(JSON.stringify(result, null, 2));",
+      "}",
+      "",
+      "main().catch((e) => {",
       "  if (e instanceof Error && e.message.startsWith('Compile with:')) {",
       "    console.error('Workflow not compiled yet. Run: npm run dev');",
       "    process.exit(1);",
       "  }",
-      "  throw e;",
-      "}",
+      "  console.error(e);",
+      "  process.exit(1);",
+      "});",
       ""
     ].join("\n");
   } else {
@@ -59613,16 +60062,19 @@ ${workflowCode}`;
       "",
       `const { ${workflowName} } = require('./${workflowJsFile}');`,
       "",
-      "try {",
-      `  const result = ${workflowName}(true, { data: { message: 'hello world' } });`,
-      "  console.log(result);",
-      "} catch (e) {",
+      "async function main() {",
+      `  const result = await ${workflowName}(true, { data: { message: 'hello world' } });`,
+      "  console.log(JSON.stringify(result, null, 2));",
+      "}",
+      "",
+      "main().catch((e) => {",
       "  if (e instanceof Error && e.message.startsWith('Compile with:')) {",
       "    console.error('Workflow not compiled yet. Run: npm run dev');",
       "    process.exit(1);",
       "  }",
-      "  throw e;",
-      "}",
+      "  console.error(e);",
+      "  process.exit(1);",
+      "});",
       ""
     ].join("\n");
   }
@@ -84560,6 +85012,13 @@ async function runCommandInner(input, options) {
       logger.newline();
       logger.section("Result");
       logger.log(JSON.stringify(result.result, null, 2));
+      const resultObj = result.result;
+      if (resultObj?.onFailure === true && !options.params && !options.paramsFile) {
+        logger.newline();
+        logger.warn(
+          "Tip: use --params to provide input. Run `fw describe <file>` to see expected inputs."
+        );
+      }
       if (options.trace && !options.stream && result.trace && result.trace.length > 0) {
         logger.newline();
         logger.section("Trace");
@@ -88468,7 +88927,7 @@ function parseIntStrict(value) {
 // src/cli/index.ts
 init_logger();
 init_error_utils();
-var version2 = true ? "0.27.5" : "0.0.0-dev";
+var version2 = true ? "0.29.0" : "0.0.0-dev";
 var program2 = new Command();
 program2.name("fw").description("Flow Weaver Annotations - Compile and validate workflow files").option("-v, --version", "Output the current version").option("--no-color", "Disable colors").option("--color", "Force colors").on("option:version", () => {
   logger.banner(version2);