@synergenius/flow-weaver 0.3.0 → 0.4.0

package/dist/mcp/workflow-executor.js

@@ -82,9 +82,21 @@ export async function executeWorkflowFromFile(filePath, params, options) {
         if (options?.mocks) {
             globalThis.__fw_mocks__ = options.mocks;
         }
+        // Set agent channel for waitForAgent pause/resume
+        if (options?.agentChannel) {
+            globalThis.__fw_agent_channel__ = options.agentChannel;
+        }
         // Dynamic import using file:// URL for cross-platform compatibility
         // (Windows paths like C:\... break with bare import() — "Received protocol 'c:'")
         const mod = await import(pathToFileURL(tmpFile).href);
+        // Register exported functions for local invokeWorkflow resolution
+        const workflowRegistry = {};
+        for (const [key, value] of Object.entries(mod)) {
+            if (typeof value === 'function' && key !== '__esModule') {
+                workflowRegistry[key] = value;
+            }
+        }
+        globalThis.__fw_workflow_registry__ = workflowRegistry;
         // Find the target exported function
         const exportedFn = findExportedFunction(mod, options?.workflowName);
         if (!exportedFn) {
@@ -99,13 +111,15 @@ export async function executeWorkflowFromFile(filePath, params, options) {
             result,
             functionName: exportedFn.name,
             executionTime,
-            ...(includeTrace && { trace }),
+            ...(includeTrace && { trace, summary: computeTraceSummary(trace) }),
         };
     }
     finally {
         // Clean up globals
         delete globalThis.__fw_debugger__;
         delete globalThis.__fw_mocks__;
+        delete globalThis.__fw_workflow_registry__;
+        delete globalThis.__fw_agent_channel__;
         // Clean up temp files
         try {
             fs.unlinkSync(tmpFile);
@@ -117,6 +131,53 @@ export async function executeWorkflowFromFile(filePath, params, options) {
         catch { /* ignore */ }
     }
 }
+/** Compute a concise summary from raw trace events. */
+export function computeTraceSummary(trace) {
+    if (trace.length === 0) {
+        return { totalNodes: 0, succeeded: 0, failed: 0, cancelled: 0, nodeTimings: [], totalDurationMs: 0 };
+    }
+    const nodeStartTimes = new Map();
+    const nodeFinalStatus = new Map();
+    const nodeTimings = [];
+    for (const event of trace) {
+        if (event.type !== 'STATUS_CHANGED' || !event.data)
+            continue;
+        const id = event.data.id;
+        const status = event.data.status;
+        if (!id || !status)
+            continue;
+        if (status === 'RUNNING') {
+            nodeStartTimes.set(id, event.timestamp);
+        }
+        if (status === 'SUCCEEDED' || status === 'FAILED' || status === 'CANCELLED') {
+            nodeFinalStatus.set(id, status);
+            const startTime = nodeStartTimes.get(id);
+            if (startTime !== undefined) {
+                nodeTimings.push({ nodeId: id, durationMs: event.timestamp - startTime });
+            }
+        }
+    }
+    let succeeded = 0;
+    let failed = 0;
+    let cancelled = 0;
+    for (const status of nodeFinalStatus.values()) {
+        if (status === 'SUCCEEDED')
+            succeeded++;
+        else if (status === 'FAILED')
+            failed++;
+        else if (status === 'CANCELLED')
+            cancelled++;
+    }
+    const totalDurationMs = trace[trace.length - 1].timestamp - trace[0].timestamp;
+    return {
+        totalNodes: nodeFinalStatus.size,
+        succeeded,
+        failed,
+        cancelled,
+        nodeTimings,
+        totalDurationMs,
+    };
+}
 function findExportedFunction(mod, preferredName) {
     // If a preferred name is specified, try it first
     if (preferredName && typeof mod[preferredName] === 'function') {

package/dist/parser.d.ts

@@ -135,6 +135,14 @@ export declare class AnnotationParser {
      * Processes all paths together for shared deduplication.
      */
     private expandPathMacros;
+    /**
+     * Expand @fanOut macros into 1-to-N connections.
+     */
+    private expandFanOutMacros;
+    /**
+     * Expand @fanIn macros into N-to-1 connections.
+     */
+    private expandFanInMacros;
     /**
      * Generate automatic connections for @autoConnect workflows.
      * Wires nodes in declaration order as a linear pipeline:

package/dist/parser.js

@@ -916,6 +916,14 @@ export class AnnotationParser {
             if (config.paths && config.paths.length > 0) {
                 this.expandPathMacros(config.paths, instances, connections, allAvailableNodeTypes, startPorts, exitPorts, macros, errors, warnings);
             }
+            // Expand @fanOut macros into 1-to-N connections
+            if (config.fanOuts && config.fanOuts.length > 0) {
+                this.expandFanOutMacros(config.fanOuts, instances, connections, startPorts, exitPorts, macros, errors);
+            }
+            // Expand @fanIn macros into N-to-1 connections
+            if (config.fanIns && config.fanIns.length > 0) {
+                this.expandFanInMacros(config.fanIns, instances, connections, startPorts, exitPorts, macros, errors);
+            }
             // Include ALL available nodeTypes in the workflow AST, plus imported npm types.
             // Previously this filtered to only nodeTypes used by instances, but that caused
             // a bug: when creating a new nodeType and then adding its first instance,
@@ -1502,6 +1510,98 @@ export class AnnotationParser {
             });
         }
     }
+    /**
+     * Expand @fanOut macros into 1-to-N connections.
+     */
+    expandFanOutMacros(fanOutConfigs, instances, connections, startPorts, exitPorts, macros, errors) {
+        const instanceIds = new Set(instances.map(i => i.id));
+        instanceIds.add('Start');
+        instanceIds.add('Exit');
+        for (const config of fanOutConfigs) {
+            const { source, targets } = config;
+            // Validate source node exists
+            if (!instanceIds.has(source.node)) {
+                errors.push(`@fanOut: source node "${source.node}" does not exist`);
+                continue;
+            }
+            let valid = true;
+            for (const target of targets) {
+                if (!instanceIds.has(target.node)) {
+                    errors.push(`@fanOut: target node "${target.node}" does not exist`);
+                    valid = false;
+                }
+            }
+            if (!valid)
+                continue;
+            // Create connections
+            for (const target of targets) {
+                const targetPort = target.port ?? source.port;
+                const conn = {
+                    type: 'Connection',
+                    from: { node: source.node, port: source.port },
+                    to: { node: target.node, port: targetPort },
+                };
+                // Deduplicate
+                const exists = connections.some(c => c.from.node === conn.from.node && c.from.port === conn.from.port &&
+                    c.to.node === conn.to.node && c.to.port === conn.to.port);
+                if (!exists) {
+                    connections.push(conn);
+                }
+            }
+            // Store macro for round-trip preservation
+            macros.push({
+                type: 'fanOut',
+                source: { node: source.node, port: source.port },
+                targets: targets.map(t => t.port ? { node: t.node, port: t.port } : { node: t.node }),
+            });
+        }
+    }
+    /**
+     * Expand @fanIn macros into N-to-1 connections.
+     */
+    expandFanInMacros(fanInConfigs, instances, connections, startPorts, exitPorts, macros, errors) {
+        const instanceIds = new Set(instances.map(i => i.id));
+        instanceIds.add('Start');
+        instanceIds.add('Exit');
+        for (const config of fanInConfigs) {
+            const { sources, target } = config;
+            // Validate target node exists
+            if (!instanceIds.has(target.node)) {
+                errors.push(`@fanIn: target node "${target.node}" does not exist`);
+                continue;
+            }
+            let valid = true;
+            for (const source of sources) {
+                if (!instanceIds.has(source.node)) {
+                    errors.push(`@fanIn: source node "${source.node}" does not exist`);
+                    valid = false;
+                }
+            }
+            if (!valid)
+                continue;
+            // Create connections
+            for (const source of sources) {
+                const sourcePort = source.port ?? target.port;
+                const conn = {
+                    type: 'Connection',
+                    from: { node: source.node, port: sourcePort },
+                    to: { node: target.node, port: target.port },
+                };
+                // Deduplicate
+                const exists = connections.some(c => c.from.node === conn.from.node && c.from.port === conn.from.port &&
+                    c.to.node === conn.to.node && c.to.port === conn.to.port);
+                if (!exists) {
+                    connections.push(conn);
+                }
+            }
+            // Store macro for round-trip preservation
+            macros.push({
+                type: 'fanIn',
+                sources: sources.map(s => s.port ? { node: s.node, port: s.port } : { node: s.node }),
+                target: { node: target.node, port: target.port },
+            });
+        }
+    }
     /**
      * Generate automatic connections for @autoConnect workflows.
      * Wires nodes in declaration order as a linear pipeline:

package/dist/runtime/ExecutionContext.d.ts

@@ -21,6 +21,8 @@ export interface VariableAddress {
     portName: string;
     executionIndex: number;
     nodeTypeName?: string | undefined;
+    scope?: string | undefined;
+    side?: 'start' | 'exit' | undefined;
 }
 export interface ExecutionInfo {
     id: string;

package/dist/runtime/ExecutionContext.js

@@ -65,6 +65,8 @@ export class GeneratedExecutionContext {
                     portName: address.portName,
                     executionIndex: address.executionIndex,
                     key: 'default',
+                    ...(address.scope !== undefined && { scope: address.scope }),
+                    ...(address.side !== undefined && { side: address.side }),
                 },
                 value: actualValue,
             });

package/dist/runtime/events.d.ts

@@ -1,4 +1,4 @@
-export type TStatusType = "RUNNING" | "SCHEDULED" | "SUCCEEDED" | "FAILED" | "CANCELLED" | "PENDING";
+export type TStatusType = "RUNNING" | "SCHEDULED" | "SUCCEEDED" | "FAILED" | "CANCELLED" | "PENDING" | "WAITING_FOR_AGENT";
 export type TVariableIdentification = {
     nodeTypeName: string;
     id: string;

package/dist/sugar-optimizer.js

@@ -69,10 +69,23 @@ export function validatePathMacro(path, connections, instances) {
  * Non-path macros are passed through unchanged.
  */
 export function filterStaleMacros(macros, connections, instances) {
+    const instanceIds = new Set(instances.map(i => i.id));
+    instanceIds.add('Start');
+    instanceIds.add('Exit');
     return macros.filter(macro => {
-        if (macro.type !== 'path')
-            return true;
-        return validatePathMacro(macro, connections, instances);
+        if (macro.type === 'path')
+            return validatePathMacro(macro, connections, instances);
+        if (macro.type === 'fanOut') {
+            if (!instanceIds.has(macro.source.node))
+                return false;
+            return macro.targets.every(t => instanceIds.has(t.node));
+        }
+        if (macro.type === 'fanIn') {
+            if (!instanceIds.has(macro.target.node))
+                return false;
+            return macro.sources.every(s => instanceIds.has(s.node));
+        }
+        return true;
     });
 }
 /**
@@ -381,6 +394,18 @@ function buildExistingMacroCoverage(macros) {
                 covered.add(step.node);
             }
         }
+        else if (macro.type === 'fanOut') {
+            covered.add(macro.source.node);
+            for (const t of macro.targets) {
+                covered.add(t.node);
+            }
+        }
+        else if (macro.type === 'fanIn') {
+            for (const s of macro.sources) {
+                covered.add(s.node);
+            }
+            covered.add(macro.target.node);
+        }
     }
     return covered;
 }

package/dist/validator.d.ts

@@ -86,6 +86,14 @@ export declare class WorkflowValidator {
      * from opposite branches (onSuccess vs onFailure) of the same branching node.
      */
     private areMutuallyExclusive;
+    /**
+     * Validate inner graph topology for nodes that have scoped ports.
+     *
+     * For each scoped node instance, checks that:
+     * 1. Inner nodes (children) have their required inputs connected within the scope
+     * 2. Scoped input ports (callback returns) have connections from inner nodes
+     */
+    private validateScopeTopology;
     private normalizeTypeString;
 }
 export declare const validator: WorkflowValidator;

package/dist/validator.js

@@ -118,6 +118,7 @@ export class WorkflowValidator {
         this.validateCycles(workflow);
         this.validateMultipleInputConnections(workflow, instanceMap);
         this.validateAnnotationSignatureConsistency(workflow);
+        this.validateScopeTopology(workflow, instanceMap);
         // Deduplicate cascading errors: if a node has UNKNOWN_NODE_TYPE,
         // suppress UNKNOWN_SOURCE_NODE, UNKNOWN_TARGET_NODE, and UNDEFINED_NODE
         // that reference the same node IDs (they're just noise).
@@ -953,6 +954,97 @@ export class WorkflowValidator {
         const branches = new Set(branchInfos.map((info) => info.branch));
         return branches.size > 1;
     }
+    /**
+     * Validate inner graph topology for nodes that have scoped ports.
+     *
+     * For each scoped node instance, checks that:
+     * 1. Inner nodes (children) have their required inputs connected within the scope
+     * 2. Scoped input ports (callback returns) have connections from inner nodes
+     */
+    validateScopeTopology(workflow, instanceMap) {
+        // Find all instances that have scoped ports
+        for (const instance of workflow.instances) {
+            const nodeType = instanceMap.get(instance.id);
+            if (!nodeType)
+                continue;
+            // Collect scoped port pairs per scope name
+            const scopeNames = new Set();
+            for (const portDef of Object.values(nodeType.outputs)) {
+                if (portDef.scope)
+                    scopeNames.add(portDef.scope);
+            }
+            for (const portDef of Object.values(nodeType.inputs)) {
+                if (portDef.scope)
+                    scopeNames.add(portDef.scope);
+            }
+            if (scopeNames.size === 0)
+                continue;
+            for (const scopeName of scopeNames) {
+                // Find children in this scope
+                const childIds = [];
+                for (const child of workflow.instances) {
+                    if (child.parent &&
+                        child.parent.id === instance.id &&
+                        child.parent.scope === scopeName) {
+                        childIds.push(child.id);
+                    }
+                }
+                if (childIds.length === 0)
+                    continue;
+                // Collect scoped connections (connections with scope tags)
+                const scopedConnections = workflow.connections.filter((conn) => (conn.from.scope === scopeName && conn.from.node === instance.id) ||
+                    (conn.to.scope === scopeName && conn.to.node === instance.id) ||
+                    (conn.from.scope === scopeName && childIds.includes(conn.from.node)) ||
+                    (conn.to.scope === scopeName && childIds.includes(conn.to.node)));
+                // Check: each child's required inputs must be satisfied within the scope
+                for (const childId of childIds) {
+                    const childType = instanceMap.get(childId);
+                    if (!childType)
+                        continue;
+                    for (const [portName, portConfig] of Object.entries(childType.inputs)) {
+                        if (isExecutePort(portName))
+                            continue;
+                        if (portConfig.scope)
+                            continue; // Skip scoped ports on children
+                        if (portConfig.optional || portConfig.default !== undefined)
+                            continue;
+                        // Check instance expression overrides
+                        const childInstance = workflow.instances.find((i) => i.id === childId);
+                        const instancePortConfig = childInstance?.config?.portConfigs?.find((pc) => pc.portName === portName && (pc.direction == null || pc.direction === 'INPUT'));
+                        if (portConfig.expression || instancePortConfig?.expression !== undefined)
+                            continue;
+                        // Check if connected by any connection (scoped, inter-child, or outer)
+                        const isConnected = workflow.connections.some((conn) => conn.to.node === childId && conn.to.port === portName);
+                        if (!isConnected) {
+                            this.errors.push({
+                                type: 'error',
+                                code: 'SCOPE_MISSING_REQUIRED_INPUT',
+                                message: `Scoped child "${childId}" has unconnected required input "${portName}" within scope "${scopeName}" of "${instance.id}".`,
+                                node: childId,
+                                location: childInstance?.sourceLocation,
+                            });
+                        }
+                    }
+                }
+                // Check: scoped INPUT ports should have connections from inner nodes
+                const scopedInputPorts = Object.entries(nodeType.inputs).filter(([_, portDef]) => portDef.scope === scopeName);
+                for (const [portName] of scopedInputPorts) {
+                    const hasConnection = scopedConnections.some((conn) => conn.to.node === instance.id &&
+                        conn.to.port === portName &&
+                        conn.to.scope === scopeName);
+                    if (!hasConnection) {
+                        this.warnings.push({
+                            type: 'warning',
+                            code: 'SCOPE_UNUSED_INPUT',
+                            message: `Scoped input port "${portName}" of "${instance.id}" (scope "${scopeName}") has no connection from inner nodes. Data will not flow back from the scope.`,
+                            node: instance.id,
+                            location: this.getInstanceLocation(workflow, instance.id),
+                        });
+                    }
+                }
+            }
+        }
+    }
     normalizeTypeString(type) {
         let n = type;
         // Remove all whitespace