@d34dman/flowdrop 0.0.56 → 0.0.57

package/dist/adapters/agentspec/AgentSpecAdapter.js

@@ -0,0 +1,658 @@
+/**
+ * Agent Spec Adapter — Bidirectional conversion between FlowDrop and Agent Spec
+ *
+ * Converts between FlowDrop's StandardWorkflow format and Oracle's Open Agent Spec
+ * JSON format. Handles the key structural differences:
+ * - Unified edges (FlowDrop) ↔ control-flow + data-flow edges (Agent Spec)
+ * - Node IDs (FlowDrop) ↔ node names (Agent Spec)
+ * - Visual positions (FlowDrop) ↔ no positions (Agent Spec)
+ *
+ * @see https://github.com/oracle/agent-spec
+ */
+import { getAgentSpecNodeMetadata, createAgentSpecNodeMetadata, extractComponentType, AGENTSPEC_NAMESPACE } from './nodeTypeRegistry.js';
+import { computeAutoLayout } from './autoLayout.js';
+import { v4 as uuidv4 } from 'uuid';
+// ============================================================================
+// Handle ID Helpers
+// ============================================================================
+/**
+ * Build a FlowDrop handle ID from node ID, direction, and port ID.
+ * Format: `${nodeId}-${direction}-${portId}`
+ */
+function buildHandleId(nodeId, direction, portId) {
+    return `${nodeId}-${direction}-${portId}`;
+}
+/**
+ * Extract port ID from a FlowDrop handle ID.
+ * Handles format: `${nodeId}-output-${portId}` or `${nodeId}-input-${portId}`
+ */
+function extractPortId(handleId) {
+    if (!handleId)
+        return null;
+    const outputMatch = handleId.lastIndexOf('-output-');
+    if (outputMatch !== -1) {
+        return handleId.substring(outputMatch + '-output-'.length);
+    }
+    const inputMatch = handleId.lastIndexOf('-input-');
+    if (inputMatch !== -1) {
+        return handleId.substring(inputMatch + '-input-'.length);
+    }
+    // Short format: the handleId IS the port ID
+    return handleId;
+}
+/**
+ * Extract direction from a FlowDrop handle ID.
+ */
+function extractDirection(handleId) {
+    if (!handleId)
+        return null;
+    if (handleId.lastIndexOf('-output-') !== -1)
+        return 'output';
+    if (handleId.lastIndexOf('-input-') !== -1)
+        return 'input';
+    return null;
+}
+// ============================================================================
+// Property ↔ Port Conversion
+// ============================================================================
+/**
+ * Convert an Agent Spec Property to a FlowDrop NodePort.
+ */
+function agentSpecPropertyToNodePort(prop, portType) {
+    // Map JSON Schema types to FlowDrop data types
+    let dataType;
+    switch (prop.type) {
+        case 'string':
+            dataType = 'string';
+            break;
+        case 'number':
+        case 'float':
+            dataType = 'number';
+            break;
+        case 'integer':
+            dataType = 'number';
+            break;
+        case 'boolean':
+            dataType = 'boolean';
+            break;
+        case 'array':
+            dataType = 'array';
+            break;
+        case 'object':
+            dataType = 'json';
+            break;
+        default:
+            dataType = 'mixed';
+    }
+    return {
+        id: prop.title,
+        name: prop.title,
+        type: portType,
+        dataType,
+        required: false,
+        description: prop.description
+    };
+}
+/**
+ * Convert a FlowDrop NodePort to an Agent Spec Property.
+ */
+function nodePortToAgentSpecProperty(port) {
+    // Map FlowDrop data types to JSON Schema types
+    let type;
+    switch (port.dataType) {
+        case 'string':
+            type = 'string';
+            break;
+        case 'number':
+        case 'float':
+            type = 'number';
+            break;
+        case 'integer':
+            type = 'integer';
+            break;
+        case 'boolean':
+            type = 'boolean';
+            break;
+        case 'array':
+            type = 'array';
+            break;
+        case 'json':
+        case 'object':
+            type = 'object';
+            break;
+        default:
+            type = 'string';
+    }
+    const prop = {
+        title: port.id,
+        type
+    };
+    if (port.description)
+        prop.description = port.description;
+    if (port.defaultValue !== undefined)
+        prop.default = port.defaultValue;
+    return prop;
+}
+// ============================================================================
+// AgentSpecAdapter
+// ============================================================================
+export class AgentSpecAdapter {
+    // ========================================================================
+    // FlowDrop → Agent Spec (Export)
+    // ========================================================================
+    /**
+     * Convert a FlowDrop StandardWorkflow to an Agent Spec Flow.
+     *
+     * Handles:
+     * - Node conversion with config → node attributes
+     * - Edge splitting into control-flow and data-flow
+     * - Position preservation in metadata
+     * - Gateway branch → from_branch mapping
+     */
+    toAgentSpec(workflow) {
+        // Build node ID → name mapping
+        // Agent Spec uses node names as references; FlowDrop uses structured IDs
+        const nodeIdToName = new Map();
+        for (const node of workflow.nodes) {
+            const name = this.resolveNodeName(node);
+            nodeIdToName.set(node.id, name);
+        }
+        // Convert nodes
+        const agentSpecNodes = workflow.nodes.map((node) => this.convertNodeToAgentSpec(node, nodeIdToName));
+        // Split edges into control-flow and data-flow
+        const controlFlowEdges = [];
+        const dataFlowEdges = [];
+        for (const edge of workflow.edges) {
+            const sourceNode = workflow.nodes.find((n) => n.id === edge.source);
+            if (!sourceNode)
+                continue;
+            const sourcePortId = extractPortId(edge.sourceHandle);
+            const sourcePortDataType = this.getSourcePortDataType(sourceNode, sourcePortId);
+            if (sourcePortDataType === 'trigger') {
+                controlFlowEdges.push(this.convertToControlFlowEdge(edge, sourceNode, nodeIdToName));
+            }
+            else {
+                dataFlowEdges.push(this.convertToDataFlowEdge(edge, nodeIdToName));
+            }
+        }
+        // Find start node
+        const startNodeName = this.findStartNodeName(agentSpecNodes, nodeIdToName);
+        return {
+            component_type: 'flow',
+            name: workflow.name,
+            description: workflow.description,
+            start_node: startNodeName,
+            nodes: agentSpecNodes,
+            control_flow_connections: controlFlowEdges,
+            data_flow_connections: dataFlowEdges.length > 0 ? dataFlowEdges : null,
+            metadata: {
+                'flowdrop:workflow_id': workflow.id,
+                'flowdrop:version': workflow.metadata?.version,
+                ...(workflow.metadata?.author ? { 'flowdrop:author': workflow.metadata.author } : {}),
+                ...(workflow.metadata?.tags ? { 'flowdrop:tags': workflow.metadata.tags } : {})
+            }
+        };
+    }
+    /**
+     * Export a FlowDrop StandardWorkflow as Agent Spec JSON string.
+     */
+    exportJSON(workflow) {
+        return JSON.stringify(this.toAgentSpec(workflow), null, 2);
+    }
+    // ========================================================================
+    // Agent Spec → FlowDrop (Import)
+    // ========================================================================
+    /**
+     * Convert an Agent Spec Flow to a FlowDrop StandardWorkflow.
+     *
+     * Handles:
+     * - Auto-layout (Agent Spec has no positions)
+     * - Edge merging (control-flow + data-flow → unified edges)
+     * - Node type mapping via registry
+     * - Component type preservation in extensions
+     */
+    fromAgentSpec(agentSpecFlow) {
+        // Compute positions for nodes
+        const positions = computeAutoLayout(agentSpecFlow);
+        // Build name → FlowDrop node ID mapping
+        const nameToNodeId = new Map();
+        const nodeCountByType = new Map();
+        for (const asNode of agentSpecFlow.nodes) {
+            const typeId = `${AGENTSPEC_NAMESPACE}.${asNode.component_type}`;
+            const count = (nodeCountByType.get(typeId) || 0) + 1;
+            nodeCountByType.set(typeId, count);
+            const nodeId = `${typeId}.${count}`;
+            nameToNodeId.set(asNode.name, nodeId);
+        }
+        // Convert nodes
+        const nodes = agentSpecFlow.nodes.map((asNode) => {
+            const nodeId = nameToNodeId.get(asNode.name);
+            const position = positions.get(asNode.name) || { x: 0, y: 0 };
+            return this.convertNodeFromAgentSpec(asNode, nodeId, position);
+        });
+        // Convert edges (merge control-flow + data-flow into unified edges)
+        const edges = [];
+        // Control-flow edges → trigger port connections
+        for (const cfEdge of agentSpecFlow.control_flow_connections) {
+            const edge = this.convertFromControlFlowEdge(cfEdge, nameToNodeId, nodes);
+            if (edge)
+                edges.push(edge);
+        }
+        // Data-flow edges → data port connections
+        if (agentSpecFlow.data_flow_connections) {
+            for (const dfEdge of agentSpecFlow.data_flow_connections) {
+                const edge = this.convertFromDataFlowEdge(dfEdge, nameToNodeId);
+                if (edge)
+                    edges.push(edge);
+            }
+        }
+        return {
+            id: agentSpecFlow.metadata?.['flowdrop:workflow_id'] || uuidv4(),
+            name: agentSpecFlow.name,
+            description: agentSpecFlow.description,
+            nodes,
+            edges,
+            metadata: {
+                version: agentSpecFlow.metadata?.['flowdrop:version'] || '1.0.0',
+                createdAt: new Date().toISOString(),
+                updatedAt: new Date().toISOString(),
+                author: agentSpecFlow.metadata?.['flowdrop:author'],
+                tags: agentSpecFlow.metadata?.['flowdrop:tags']
+            }
+        };
+    }
+    /**
+     * Import an Agent Spec flow from a JSON string.
+     */
+    importJSON(json) {
+        const parsed = JSON.parse(json);
+        return this.fromAgentSpec(parsed);
+    }
+    // ========================================================================
+    // Node Conversion (Private)
+    // ========================================================================
+    /**
+     * Resolve a stable name for a FlowDrop node in Agent Spec.
+     * Uses the node's config instanceTitle, label, or falls back to ID.
+     */
+    resolveNodeName(node) {
+        const instanceTitle = node.data.config?.instanceTitle;
+        if (instanceTitle)
+            return instanceTitle;
+        return node.data.label || node.id;
+    }
+    /**
+     * Convert a FlowDrop StandardNode to an Agent Spec node.
+     */
+    convertNodeToAgentSpec(node, nodeIdToName) {
+        const componentType = this.resolveComponentType(node);
+        const name = nodeIdToName.get(node.id) || node.id;
+        // Convert data ports (skip trigger/tool ports — those are handled as edges)
+        const dataInputs = node.data.metadata.inputs
+            .filter((p) => p.dataType !== 'trigger' && p.dataType !== 'tool')
+            .map((p) => nodePortToAgentSpecProperty(p));
+        const dataOutputs = node.data.metadata.outputs
+            .filter((p) => p.dataType !== 'trigger' && p.dataType !== 'tool')
+            .map((p) => nodePortToAgentSpecProperty(p));
+        // Build base node
+        const base = {
+            component_type: componentType,
+            name,
+            description: node.data.metadata.description || undefined,
+            inputs: dataInputs.length > 0 ? dataInputs : undefined,
+            outputs: dataOutputs.length > 0 ? dataOutputs : undefined,
+            metadata: {
+                'flowdrop:position': node.position,
+                'flowdrop:node_id': node.id,
+                'flowdrop:node_type_id': node.data.metadata.id
+            }
+        };
+        // Add type-specific attributes from config
+        return this.addNodeSpecificAttributes(base, node);
+    }
+    /**
+     * Add Agent Spec type-specific attributes from FlowDrop config.
+     */
+    addNodeSpecificAttributes(asNode, fdNode) {
+        const config = fdNode.data.config || {};
+        switch (asNode.component_type) {
+            case 'llm_node': {
+                const llmNode = asNode;
+                if (config.prompt_template)
+                    llmNode.prompt_template = config.prompt_template;
+                if (config.system_prompt)
+                    llmNode.system_prompt = config.system_prompt;
+                if (config.llm_config_ref)
+                    llmNode.llm_config = config.llm_config_ref;
+                return llmNode;
+            }
+            case 'branching_node': {
+                const branchNode = asNode;
+                const branches = config.branches;
+                branchNode.branches = branches
+                    ? branches.map((b) => ({
+                        name: b.name,
+                        condition: b.condition || undefined,
+                        description: b.description || undefined
+                    }))
+                    : [];
+                return branchNode;
+            }
+            case 'api_node': {
+                const apiNode = asNode;
+                if (config.endpoint)
+                    apiNode.endpoint = config.endpoint;
+                if (config.method)
+                    apiNode.method = config.method;
+                if (config.headers) {
+                    try {
+                        apiNode.headers =
+                            typeof config.headers === 'string'
+                                ? JSON.parse(config.headers)
+                                : config.headers;
+                    }
+                    catch {
+                        // Ignore parse errors
+                    }
+                }
+                return apiNode;
+            }
+            case 'agent_node': {
+                const agentNode = asNode;
+                if (config.agent_ref)
+                    agentNode.agent = config.agent_ref;
+                return agentNode;
+            }
+            case 'flow_node': {
+                const flowNode = asNode;
+                if (config.flow_ref)
+                    flowNode.flow = config.flow_ref;
+                return flowNode;
+            }
+            case 'map_node': {
+                const mapNode = asNode;
+                if (config.input_collection)
+                    mapNode.input_collection = config.input_collection;
+                if (config.output_collection)
+                    mapNode.output_collection = config.output_collection;
+                if (config.map_flow_ref)
+                    mapNode.map_flow = config.map_flow_ref;
+                return mapNode;
+            }
+            case 'tool_node': {
+                const toolNode = asNode;
+                if (config.tool_ref)
+                    toolNode.tool = config.tool_ref;
+                return toolNode;
+            }
+            default:
+                return asNode;
+        }
+    }
+    /**
+     * Resolve Agent Spec component type from a FlowDrop node.
+     */
+    resolveComponentType(node) {
+        // Check extensions first (round-trip preservation)
+        const ext = node.data.metadata.extensions?.['agentspec:component_type'];
+        if (ext && typeof ext === 'string') {
+            return ext;
+        }
+        // Infer from FlowDrop node type ID
+        const fromId = extractComponentType(node.data.metadata.id);
+        if (fromId)
+            return fromId;
+        // Infer from FlowDrop visual type + category
+        const nodeType = node.data.metadata.type;
+        const category = node.data.metadata.category;
+        if (nodeType === 'terminal' && category === 'triggers')
+            return 'start_node';
+        if (nodeType === 'terminal' && category === 'outputs')
+            return 'end_node';
+        if (nodeType === 'gateway')
+            return 'branching_node';
+        if (nodeType === 'tool')
+            return 'tool_node';
+        if (category === 'ai' || category === 'models')
+            return 'llm_node';
+        if (category === 'agents')
+            return 'agent_node';
+        if (category === 'data')
+            return 'api_node';
+        // Default fallback
+        return 'llm_node';
+    }
+    /**
+     * Convert an Agent Spec node to a FlowDrop StandardNode.
+     */
+    convertNodeFromAgentSpec(asNode, nodeId, position) {
+        // Restore position from metadata if available (round-trip)
+        const savedPosition = asNode.metadata?.['flowdrop:position'];
+        const finalPosition = savedPosition || position;
+        // Convert inputs/outputs to FlowDrop ports
+        const dataInputs = (asNode.inputs || []).map((p) => agentSpecPropertyToNodePort(p, 'input'));
+        const dataOutputs = (asNode.outputs || []).map((p) => agentSpecPropertyToNodePort(p, 'output'));
+        // Get base metadata from registry and merge with actual ports
+        const metadata = createAgentSpecNodeMetadata(asNode.component_type, undefined, // Let the method build from base
+        undefined);
+        if (!metadata) {
+            throw new Error(`Unknown Agent Spec component type: ${asNode.component_type}`);
+        }
+        // Merge data ports with the base trigger/tool ports from registry
+        const triggerInputs = metadata.inputs.filter((p) => p.dataType === 'trigger' || p.dataType === 'tool');
+        const triggerOutputs = metadata.outputs.filter((p) => p.dataType === 'trigger' || p.dataType === 'tool');
+        const finalMetadata = {
+            ...metadata,
+            description: asNode.description || metadata.description,
+            inputs: [...triggerInputs, ...dataInputs],
+            outputs: [...triggerOutputs, ...dataOutputs],
+            extensions: {
+                ...metadata.extensions,
+                'agentspec:component_type': asNode.component_type,
+                'agentspec:original_name': asNode.name
+            }
+        };
+        // Build config from Agent Spec node-specific attributes
+        const config = this.extractConfigFromAgentSpec(asNode);
+        return {
+            id: nodeId,
+            type: asNode.metadata?.['flowdrop:node_type_id'] || metadata.id,
+            position: finalPosition,
+            data: {
+                label: asNode.name,
+                config,
+                metadata: finalMetadata
+            }
+        };
+    }
+    /**
+     * Extract FlowDrop config values from Agent Spec node-specific attributes.
+     */
+    extractConfigFromAgentSpec(asNode) {
+        const config = {};
+        switch (asNode.component_type) {
+            case 'llm_node': {
+                const llm = asNode;
+                if (llm.prompt_template)
+                    config.prompt_template = llm.prompt_template;
+                if (llm.system_prompt)
+                    config.system_prompt = llm.system_prompt;
+                if (llm.llm_config) {
+                    config.llm_config_ref =
+                        typeof llm.llm_config === 'string' ? llm.llm_config : llm.llm_config.name;
+                }
+                break;
+            }
+            case 'branching_node': {
+                const branch = asNode;
+                config.branches = branch.branches.map((b) => ({
+                    name: b.name,
+                    label: b.name,
+                    condition: b.condition || '',
+                    isDefault: !b.condition
+                }));
+                break;
+            }
+            case 'api_node': {
+                const api = asNode;
+                if (api.endpoint)
+                    config.endpoint = api.endpoint;
+                if (api.method)
+                    config.method = api.method;
+                if (api.headers)
+                    config.headers = JSON.stringify(api.headers, null, 2);
+                break;
+            }
+            case 'agent_node': {
+                const agent = asNode;
+                if (agent.agent) {
+                    config.agent_ref =
+                        typeof agent.agent === 'string' ? agent.agent : agent.agent.name;
+                }
+                break;
+            }
+            case 'flow_node': {
+                const flow = asNode;
+                if (flow.flow) {
+                    config.flow_ref = typeof flow.flow === 'string' ? flow.flow : flow.flow.name;
+                }
+                break;
+            }
+            case 'map_node': {
+                const map = asNode;
+                if (map.input_collection)
+                    config.input_collection = map.input_collection;
+                if (map.output_collection)
+                    config.output_collection = map.output_collection;
+                if (map.map_flow) {
+                    config.map_flow_ref =
+                        typeof map.map_flow === 'string' ? map.map_flow : map.map_flow.name;
+                }
+                break;
+            }
+            case 'tool_node': {
+                const tool = asNode;
+                if (tool.tool) {
+                    config.tool_ref = typeof tool.tool === 'string' ? tool.tool : tool.tool.name;
+                }
+                break;
+            }
+        }
+        return config;
+    }
+    // ========================================================================
+    // Edge Conversion (Private)
+    // ========================================================================
+    /**
+     * Get the data type of a source port from a FlowDrop node.
+     */
+    getSourcePortDataType(node, portId) {
+        if (!portId)
+            return null;
+        // Check static output ports
+        const port = node.data.metadata.outputs.find((p) => p.id === portId);
+        if (port)
+            return port.dataType;
+        // Check if it's a gateway branch (always trigger)
+        if (node.data.metadata.type === 'gateway') {
+            const branches = node.data.config?.branches;
+            if (branches?.some((b) => b.name === portId)) {
+                return 'trigger';
+            }
+        }
+        // Check dynamic outputs
+        const dynamicOutputs = node.data.config?.dynamicOutputs;
+        if (dynamicOutputs) {
+            const dp = dynamicOutputs.find((p) => p.name === portId);
+            if (dp)
+                return dp.dataType;
+        }
+        return null;
+    }
+    /**
+     * Convert a FlowDrop trigger edge to an Agent Spec ControlFlowEdge.
+     */
+    convertToControlFlowEdge(edge, sourceNode, nodeIdToName) {
+        const fromNode = nodeIdToName.get(edge.source) || edge.source;
+        const toNode = nodeIdToName.get(edge.target) || edge.target;
+        const sourcePortId = extractPortId(edge.sourceHandle);
+        // Determine from_branch for gateway nodes
+        let fromBranch;
+        if (sourceNode.data.metadata.type === 'gateway' && sourcePortId) {
+            const branches = sourceNode.data.config?.branches;
+            if (branches?.some((b) => b.name === sourcePortId)) {
+                fromBranch = sourcePortId;
+            }
+        }
+        return {
+            name: `${fromNode}_to_${toNode}${fromBranch ? `_${fromBranch}` : ''}`,
+            from_node: fromNode,
+            to_node: toNode,
+            from_branch: fromBranch
+        };
+    }
+    /**
+     * Convert a FlowDrop data edge to an Agent Spec DataFlowEdge.
+     */
+    convertToDataFlowEdge(edge, nodeIdToName) {
+        const sourceNode = nodeIdToName.get(edge.source) || edge.source;
+        const destNode = nodeIdToName.get(edge.target) || edge.target;
+        const sourceOutput = extractPortId(edge.sourceHandle) || 'output';
+        const destInput = extractPortId(edge.targetHandle) || 'input';
+        return {
+            name: `${sourceNode}_${sourceOutput}_to_${destNode}_${destInput}`,
+            source_node: sourceNode,
+            source_output: sourceOutput,
+            destination_node: destNode,
+            destination_input: destInput
+        };
+    }
+    /**
+     * Convert an Agent Spec ControlFlowEdge to a FlowDrop edge.
+     */
+    convertFromControlFlowEdge(cfEdge, nameToNodeId, nodes) {
+        const sourceId = nameToNodeId.get(cfEdge.from_node);
+        const targetId = nameToNodeId.get(cfEdge.to_node);
+        if (!sourceId || !targetId)
+            return null;
+        // Determine source handle
+        let sourcePortId = 'trigger'; // default for non-branch control flow
+        if (cfEdge.from_branch) {
+            sourcePortId = cfEdge.from_branch;
+        }
+        return {
+            id: uuidv4(),
+            source: sourceId,
+            target: targetId,
+            sourceHandle: buildHandleId(sourceId, 'output', sourcePortId),
+            targetHandle: buildHandleId(targetId, 'input', 'trigger')
+        };
+    }
+    /**
+     * Convert an Agent Spec DataFlowEdge to a FlowDrop edge.
+     */
+    convertFromDataFlowEdge(dfEdge, nameToNodeId) {
+        const sourceId = nameToNodeId.get(dfEdge.source_node);
+        const targetId = nameToNodeId.get(dfEdge.destination_node);
+        if (!sourceId || !targetId)
+            return null;
+        return {
+            id: uuidv4(),
+            source: sourceId,
+            target: targetId,
+            sourceHandle: buildHandleId(sourceId, 'output', dfEdge.source_output),
+            targetHandle: buildHandleId(targetId, 'input', dfEdge.destination_input)
+        };
+    }
+    /**
+     * Find the start node name from converted Agent Spec nodes.
+     */
+    findStartNodeName(nodes, nodeIdToName) {
+        // Look for an explicit start_node
+        const startNode = nodes.find((n) => n.component_type === 'start_node');
+        if (startNode)
+            return startNode.name;
+        // Fall back to the first node
+        return nodes.length > 0 ? nodes[0].name : 'start';
+    }
+}