@synergenius/flow-weaver 0.10.8 → 0.10.10

package/dist/mcp/tools-editor.js

@@ -4,8 +4,8 @@ import { executeWorkflowFromFile } from './workflow-executor.js';
 import { AgentChannel } from './agent-channel.js';
 import { storePendingRun, getPendingRun, removePendingRun, listPendingRuns } from './run-registry.js';
 /**
- * Unwrap editor ack responses to flatten double-nested results.
- * Editor returns { requestId, success, result: { actualData } } —
+ * Unwrap Studio ack responses to flatten double-nested results.
+ * Studio returns { requestId, success, result: { actualData } },
  * we extract the `result` field to avoid double-nesting in MCP output.
  */
 function unwrapAckResult(ack) {
@@ -15,25 +15,25 @@ function unwrapAckResult(ack) {
     return ack;
 }
 export function registerEditorTools(mcp, connection, buffer) {
-    mcp.tool('fw_check_events', 'Get buffered editor events. Returns and clears the event buffer unless peek=true.', { peek: z.boolean().optional().describe('If true, read events without clearing the buffer') }, async (args) => {
+    mcp.tool('fw_check_events', 'Get buffered Studio events. Returns and clears the event buffer unless peek=true.', { peek: z.boolean().optional().describe('If true, read events without clearing the buffer') }, async (args) => {
         const events = args.peek ? buffer.peek() : buffer.drain();
         return makeToolResult(events);
     });
-    mcp.tool('fw_get_state', 'Get the current editor/workflow state from Flow Weaver.', {}, async () => {
+    mcp.tool('fw_get_state', 'Get the current Studio/workflow state from Flow Weaver.', {}, async () => {
         if (!connection.isConnected) {
-            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to the editor. Is the editor running?');
+            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to Studio. Is Studio running?');
         }
         const result = await connection.sendCommand('get-state', {});
         return makeToolResult(unwrapAckResult(result));
     });
-    mcp.tool('fw_focus_node', 'Select and center a node in the Flow Weaver editor.', { nodeId: z.string().describe('The ID of the node to focus') }, async (args) => {
+    mcp.tool('fw_focus_node', 'Select and center a node in Flow Weaver Studio.', { nodeId: z.string().describe('The ID of the node to focus') }, async (args) => {
         if (!connection.isConnected) {
-            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to the editor. Is the editor running?');
+            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to Studio. Is Studio running?');
         }
         const result = await connection.sendCommand('focus-node', { nodeId: args.nodeId });
         return makeToolResult(unwrapAckResult(result));
     });
-    mcp.tool('fw_add_node', 'Add a new node to the workflow in the Flow Weaver editor.', {
+    mcp.tool('fw_add_node', 'Add a new node to the workflow in Flow Weaver Studio.', {
         nodeTypeName: z.string().describe('The name of the node type to add'),
         nodeTypeDefinition: z
             .record(z.unknown())
@@ -41,7 +41,7 @@ export function registerEditorTools(mcp, connection, buffer) {
             .describe('Optional node type definition object'),
     }, async (args) => {
         if (!connection.isConnected) {
-            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to the editor. Is the editor running?');
+            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to Studio. Is Studio running?');
         }
         const params = { nodeTypeName: args.nodeTypeName };
         if (args.nodeTypeDefinition) {
@@ -50,19 +50,19 @@ export function registerEditorTools(mcp, connection, buffer) {
         const result = await connection.sendCommand('add-node', params);
         return makeToolResult(unwrapAckResult(result));
     });
-    mcp.tool('fw_open_workflow', 'Open a workflow file in the Flow Weaver editor.', { filePath: z.string().describe('The path to the workflow file to open') }, async (args) => {
+    mcp.tool('fw_open_workflow', 'Open a workflow file in Flow Weaver Studio.', { filePath: z.string().describe('The path to the workflow file to open') }, async (args) => {
         if (!connection.isConnected) {
-            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to the editor. Is the editor running?');
+            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to Studio. Is Studio running?');
         }
         const result = await connection.sendCommand('open-workflow', { filePath: args.filePath });
         return makeToolResult(unwrapAckResult(result));
     });
-    mcp.tool('fw_send_command', 'Send a generic command to the Flow Weaver editor.', {
+    mcp.tool('fw_send_command', 'Send a generic command to Flow Weaver Studio.', {
         action: z.string().describe('The command action name'),
         params: z.record(z.unknown()).optional().describe('Optional parameters for the command'),
     }, async (args) => {
         if (!connection.isConnected) {
-            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to the editor. Is the editor running?');
+            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to Studio. Is Studio running?');
         }
         const result = await connection.sendCommand(args.action, args.params ?? {});
         return makeToolResult(unwrapAckResult(result));
@@ -76,7 +76,7 @@ export function registerEditorTools(mcp, connection, buffer) {
             .describe('Array of commands to execute as a batch'),
     }, async (args) => {
         if (!connection.isConnected) {
-            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to the editor. Is the editor running?');
+            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to Studio. Is Studio running?');
         }
         const result = await connection.sendBatch(args.commands);
         return makeToolResult(unwrapAckResult(result));
@@ -84,7 +84,7 @@ export function registerEditorTools(mcp, connection, buffer) {
     // --- New tools ---
     mcp.tool('fw_remove_node', 'Remove a node and its connections from the workflow.', { nodeName: z.string().describe('The name/ID of the node to remove') }, async (args) => {
         if (!connection.isConnected) {
-            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to the editor. Is the editor running?');
+            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to Studio. Is Studio running?');
         }
         const result = await connection.sendCommand('remove-node', { nodeName: args.nodeName });
         return makeToolResult(unwrapAckResult(result));
@@ -101,7 +101,7 @@ export function registerEditorTools(mcp, connection, buffer) {
             .describe('Connection specification'),
     }, async (args) => {
         if (!connection.isConnected) {
-            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to the editor. Is the editor running?');
+            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to Studio. Is Studio running?');
         }
         const bridgeAction = args.action === 'add' ? 'add-connection' : 'remove-connection';
         const result = await connection.sendCommand(bridgeAction, {
@@ -111,7 +111,7 @@ export function registerEditorTools(mcp, connection, buffer) {
     });
     mcp.tool('fw_undo_redo', 'Undo or redo the last workflow change.', { action: z.enum(['undo', 'redo']).describe('Whether to undo or redo') }, async (args) => {
         if (!connection.isConnected) {
-            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to the editor. Is the editor running?');
+            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to Studio. Is Studio running?');
         }
         const result = await connection.sendCommand(args.action, {});
         return makeToolResult(unwrapAckResult(result));
@@ -123,7 +123,7 @@ export function registerEditorTools(mcp, connection, buffer) {
         filePath: z
             .string()
             .optional()
-            .describe('Path to workflow file. When provided, compiles and executes directly (no editor needed)'),
+            .describe('Path to workflow file. When provided, compiles and executes directly (no Studio needed)'),
         workflowName: z
             .string()
             .optional()
@@ -134,7 +134,7 @@ export function registerEditorTools(mcp, connection, buffer) {
             .optional()
             .describe('Include execution trace events (default: true)'),
     }, async (args, extra) => {
-        // When filePath is provided, compile and execute directly (no editor needed)
+        // When filePath is provided, compile and execute directly (no Studio needed)
         if (args.filePath) {
             try {
                 const channel = new AgentChannel();
@@ -197,9 +197,9 @@ export function registerEditorTools(mcp, connection, buffer) {
                 return makeErrorResult(code, message);
             }
         }
-        // No filePath: delegate to editor via Socket.io (existing behavior)
+        // No filePath: delegate to Studio via Socket.io (existing behavior)
         if (!connection.isConnected) {
-            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to the editor. Is the editor running?');
+            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to Studio. Is Studio running?');
         }
         const result = await connection.sendCommand('execute-workflow', args.params ?? {});
         return makeToolResult(unwrapAckResult(result));
@@ -247,7 +247,7 @@ export function registerEditorTools(mcp, connection, buffer) {
     });
     mcp.tool('fw_get_workflow_details', 'Get full workflow structure including nodes, connections, types, and positions.', {}, async () => {
         if (!connection.isConnected) {
-            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to the editor. Is the editor running?');
+            return makeErrorResult('EDITOR_NOT_CONNECTED', 'Not connected to Studio. Is Studio running?');
         }
         const result = await connection.sendCommand('get-workflow-details', {});
         return makeToolResult(unwrapAckResult(result));

package/dist/mcp/tools-query.js

@@ -21,9 +21,9 @@ export function registerQueryTools(mcp) {
     mcp.tool('fw_describe', 'Describe a workflow in LLM-friendly format (nodes, connections, graph, validation).', {
         filePath: z.string().describe('Path to the workflow .ts file'),
         format: z
-            .enum(['json', 'text', 'mermaid', 'paths'])
+            .enum(['json', 'text', 'mermaid', 'paths', 'ascii', 'ascii-compact'])
             .optional()
-            .describe('Output format (default: json)'),
+            .describe('Output format (default: json). ascii/ascii-compact produce terminal-readable diagrams.'),
         node: z.string().optional().describe('Focus on a specific node ID'),
         workflowName: z.string().optional().describe('Specific workflow if file has multiple'),
     }, async (args) => {

package/dist/mcp/types.d.ts

@@ -3,7 +3,7 @@ import type { EventBuffer } from './event-buffer.js';
 import type { EditorConnection } from './editor-connection.js';
 /** Options for initializing the MCP server. */
 export interface McpServerOptions {
-    /** WebSocket server URL for editor connection. */
+    /** WebSocket server URL for Studio connection. */
     server?: string;
     /** Whether to use stdio transport instead of SSE. */
     stdio?: boolean;
@@ -27,7 +27,7 @@ export interface RegistrationDeps {
     /** Resolve the path to the Flow Weaver CLI executable. */
     resolveCliPath: () => string;
 }
-/** Acknowledgement response returned by the editor after processing a command. */
+/** Acknowledgement response returned by Studio after processing a command. */
 export interface AckResponse {
     /** Unique identifier correlating the response to its originating request. */
     requestId: string;
@@ -47,7 +47,7 @@ export interface BufferedEvent {
     /** ISO 8601 timestamp of when the event was buffered. */
     timestamp: string;
 }
-/** Options for configuring the editor WebSocket connection. */
+/** Options for configuring the Studio WebSocket connection. */
 export interface EditorConnectionOptions {
     /** Custom socket.io factory, primarily used for injecting mocks in tests. */
     ioFactory?: typeof socketIO;

package/dist/parser.d.ts

@@ -166,6 +166,12 @@ export declare class AnnotationParser {
      * Returns a map of property names to their TypeScript type strings.
      */
     private extractTypeSchema;
+    /**
+     * Check if a type should be expanded into individual ports via getProperties().
+     * Returns true for object literals and interfaces, false for primitives, arrays,
+     * and built-in types whose properties are prototype methods (string, number, etc.).
+     */
+    private isExpandableObjectType;
     private inferPortType;
     /**
      * Check if a function has a valid @flowWeaver annotation (nodeType, workflow, or pattern).

package/dist/parser.js

@@ -1799,32 +1799,52 @@ export class AnnotationParser {
             else {
                 ports.execute = { dataType: 'STEP', tsType: 'boolean', label: 'Execute' };
             }
-            // Extract data ports from second parameter if it exists
+            // Extract data ports from parameters beyond execute
             if (params.length > 1) {
-                const dataParam = params[1];
-                const dataParamType = dataParam.getType();
-                const properties = dataParamType.getProperties();
-                properties.forEach((prop) => {
-                    const propName = prop.getName();
-                    const propType = prop.getTypeAtLocation(dataParam);
-                    const portType = this.inferPortType(propType);
-                    const propTypeText = propType.getText();
-                    // Extract schema for complex types (interfaces/objects)
-                    const tsSchema = portType === 'OBJECT' ? this.extractTypeSchema(propType) : undefined;
-                    // Check if JSDoc has explicit metadata override for this start port (from @param annotation)
-                    // Always prefer ts-morph inferred type over JSDoc regex-based inference
-                    // (JSDoc @param type inference uses regex which can fail for complex types)
-                    const startPortConfig = config?.startPorts?.[propName];
-                    ports[propName] = {
-                        dataType: portType,
-                        label: startPortConfig?.label || this.capitalize(propName),
-                        ...(startPortConfig?.metadata && { metadata: startPortConfig.metadata }),
-                        // Include original TS type for rich type display
-                        ...(propTypeText && { tsType: propTypeText }),
-                        // Include schema breakdown for complex types
-                        ...(tsSchema && Object.keys(tsSchema).length > 0 && { tsSchema }),
-                    };
-                });
+                // Filter out __abortSignal__ which is injected by generateInPlace and
+                // is not a user-visible port.
+                const dataParams = params.slice(1).filter(p => p.getName() !== '__abortSignal__');
+                // Multiple separate params: each becomes its own port
+                // Single param with object type: expand its properties into ports
+                const shouldExpandProperties = dataParams.length === 1 && this.isExpandableObjectType(dataParams[0].getType());
+                if (shouldExpandProperties) {
+                    const dataParam = dataParams[0];
+                    const dataParamType = dataParam.getType();
+                    const properties = dataParamType.getProperties();
+                    properties.forEach((prop) => {
+                        const propName = prop.getName();
+                        const propType = prop.getTypeAtLocation(dataParam);
+                        const portType = this.inferPortType(propType);
+                        const propTypeText = propType.getText();
+                        const tsSchema = portType === 'OBJECT' ? this.extractTypeSchema(propType) : undefined;
+                        const startPortConfig = config?.startPorts?.[propName];
+                        ports[propName] = {
+                            dataType: portType,
+                            label: startPortConfig?.label || this.capitalize(propName),
+                            ...(startPortConfig?.metadata && { metadata: startPortConfig.metadata }),
+                            ...(propTypeText && { tsType: propTypeText }),
+                            ...(tsSchema && Object.keys(tsSchema).length > 0 && { tsSchema }),
+                        };
+                    });
+                }
+                else {
+                    // Each parameter becomes its own port
+                    for (const param of dataParams) {
+                        const paramName = param.getName();
+                        const paramType = param.getType();
+                        const portType = this.inferPortType(paramType);
+                        const paramTypeText = paramType.getText(param);
+                        const tsSchema = portType === 'OBJECT' ? this.extractTypeSchema(paramType) : undefined;
+                        const startPortConfig = config?.startPorts?.[paramName];
+                        ports[paramName] = {
+                            dataType: portType,
+                            label: startPortConfig?.label || this.capitalize(paramName),
+                            ...(startPortConfig?.metadata && { metadata: startPortConfig.metadata }),
+                            ...(paramTypeText && { tsType: paramTypeText }),
+                            ...(tsSchema && Object.keys(tsSchema).length > 0 && { tsSchema }),
+                        };
+                    }
+                }
             }
         }
         else {
@@ -1923,6 +1943,20 @@ export class AnnotationParser {
         }
         return Object.keys(schema).length > 0 ? schema : undefined;
     }
+    /**
+     * Check if a type should be expanded into individual ports via getProperties().
+     * Returns true for object literals and interfaces, false for primitives, arrays,
+     * and built-in types whose properties are prototype methods (string, number, etc.).
+     */
+    isExpandableObjectType(tsType) {
+        const typeText = tsType.getText();
+        const primitiveTypes = new Set(['string', 'number', 'boolean', 'any', 'unknown', 'never', 'object', 'Object']);
+        if (primitiveTypes.has(typeText))
+            return false;
+        if (typeText.endsWith('[]') || typeText.startsWith('Array<'))
+            return false;
+        return tsType.isObject() && tsType.getProperties().length > 0;
+    }
     inferPortType(tsType) {
         const typeText = tsType.getText();
         // Delegate to inferDataTypeFromTS for consistent type mapping

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synergenius/flow-weaver",
-  "version": "0.10.8",
+  "version": "0.10.10",
   "description": "Deterministic workflow compiler for AI agents. Compiles to standalone TypeScript, no runtime dependencies.",
   "private": false,
   "type": "module",