@d34dman/flowdrop 0.0.55 → 0.0.57

package/dist/adapters/agentspec/agentAdapter.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Agent-Level Adapter
+ *
+ * Handles conversion between FlowDrop workflows and full Agent Spec Documents
+ * (which wrap a Flow with Agent metadata like tools, LLM config, etc.)
+ */
+import type { AgentSpecDocument, AgentSpecTool, AgentSpecLLMConfig } from '../../types/agentspec.js';
+import type { StandardWorkflow } from '../WorkflowAdapter.js';
+/**
+ * Agent-level configuration that wraps a workflow.
+ * Contains the Agent Spec agent metadata that lives outside the flow.
+ */
+export interface AgentConfig {
+    /** Agent name */
+    name: string;
+    /** Agent description */
+    description?: string;
+    /** System prompt for the agent */
+    systemPrompt?: string;
+    /** Tools available to the agent */
+    tools?: AgentSpecTool[];
+    /** LLM configuration */
+    llmConfig?: AgentSpecLLMConfig;
+}
+/**
+ * Result of importing an Agent Spec Document.
+ */
+export interface AgentSpecImportResult {
+    /** The FlowDrop workflow (from the flow) */
+    workflow: StandardWorkflow;
+    /** Agent metadata (from the agent, if present) */
+    agentConfig?: AgentConfig;
+    /** Shared tools declared at document level */
+    tools?: AgentSpecTool[];
+    /** Shared LLM configurations declared at document level */
+    llmConfigs?: AgentSpecLLMConfig[];
+}
+export declare class AgentSpecAgentAdapter {
+    private flowAdapter;
+    constructor();
+    /**
+     * Convert a FlowDrop workflow + agent config into a full AgentSpecDocument.
+     *
+     * The document wraps the flow with agent metadata (tools, LLM config, system prompt).
+     */
+    toAgentSpecDocument(workflow: StandardWorkflow, agentConfig?: AgentConfig, tools?: AgentSpecTool[], llmConfigs?: AgentSpecLLMConfig[]): AgentSpecDocument;
+    /**
+     * Import a full AgentSpecDocument, extracting the flow and agent metadata.
+     */
+    fromAgentSpecDocument(doc: AgentSpecDocument): AgentSpecImportResult;
+    /**
+     * Export a full AgentSpecDocument as JSON string.
+     */
+    exportJSON(workflow: StandardWorkflow, agentConfig?: AgentConfig, tools?: AgentSpecTool[], llmConfigs?: AgentSpecLLMConfig[]): string;
+    /**
+     * Import from JSON string containing an AgentSpecDocument.
+     */
+    importJSON(json: string): AgentSpecImportResult;
+}

package/dist/adapters/agentspec/agentAdapter.js

@@ -0,0 +1,91 @@
+/**
+ * Agent-Level Adapter
+ *
+ * Handles conversion between FlowDrop workflows and full Agent Spec Documents
+ * (which wrap a Flow with Agent metadata like tools, LLM config, etc.)
+ */
+import { AgentSpecAdapter } from './AgentSpecAdapter.js';
+export class AgentSpecAgentAdapter {
+    flowAdapter;
+    constructor() {
+        this.flowAdapter = new AgentSpecAdapter();
+    }
+    /**
+     * Convert a FlowDrop workflow + agent config into a full AgentSpecDocument.
+     *
+     * The document wraps the flow with agent metadata (tools, LLM config, system prompt).
+     */
+    toAgentSpecDocument(workflow, agentConfig, tools, llmConfigs) {
+        const flow = this.flowAdapter.toAgentSpec(workflow);
+        const doc = {
+            flow,
+            metadata: {
+                'flowdrop:exported_at': new Date().toISOString()
+            }
+        };
+        // Add agent definition if config provided
+        if (agentConfig) {
+            const agent = {
+                component_type: 'agent',
+                name: agentConfig.name,
+                description: agentConfig.description,
+                system_prompt: agentConfig.systemPrompt,
+                tools: agentConfig.tools,
+                llm_config: agentConfig.llmConfig
+            };
+            doc.agent = agent;
+        }
+        // Add shared tools
+        if (tools && tools.length > 0) {
+            doc.tools = tools;
+        }
+        // Add shared LLM configs
+        if (llmConfigs && llmConfigs.length > 0) {
+            doc.llm_configs = llmConfigs;
+        }
+        return doc;
+    }
+    /**
+     * Import a full AgentSpecDocument, extracting the flow and agent metadata.
+     */
+    fromAgentSpecDocument(doc) {
+        if (!doc.flow) {
+            throw new Error('AgentSpecDocument has no flow definition');
+        }
+        const workflow = this.flowAdapter.fromAgentSpec(doc.flow);
+        const result = {
+            workflow
+        };
+        // Extract agent config
+        if (doc.agent) {
+            result.agentConfig = {
+                name: doc.agent.name,
+                description: doc.agent.description,
+                systemPrompt: doc.agent.system_prompt,
+                tools: doc.agent.tools?.filter((t) => typeof t !== 'string'),
+                llmConfig: doc.agent.llm_config && typeof doc.agent.llm_config !== 'string'
+                    ? doc.agent.llm_config
+                    : undefined
+            };
+        }
+        // Extract shared declarations
+        if (doc.tools)
+            result.tools = doc.tools;
+        if (doc.llm_configs)
+            result.llmConfigs = doc.llm_configs;
+        return result;
+    }
+    /**
+     * Export a full AgentSpecDocument as JSON string.
+     */
+    exportJSON(workflow, agentConfig, tools, llmConfigs) {
+        return JSON.stringify(this.toAgentSpecDocument(workflow, agentConfig, tools, llmConfigs), null, 2);
+    }
+    /**
+     * Import from JSON string containing an AgentSpecDocument.
+     */
+    importJSON(json) {
+        const doc = JSON.parse(json);
+        return this.fromAgentSpecDocument(doc);
+    }
+}

package/dist/adapters/agentspec/autoLayout.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Auto-Layout for Agent Spec Flows
+ *
+ * Agent Spec has no visual position information. This module assigns
+ * positions to imported nodes using a layered layout algorithm:
+ *
+ * 1. Topological sort from StartNode using control-flow edges
+ * 2. Assign layers based on longest path from StartNode
+ * 3. Position nodes with configurable spacing
+ * 4. Fan out branches vertically from BranchingNode
+ */
+import type { AgentSpecFlow } from '../../types/agentspec.js';
+/** Layout configuration */
+export interface AutoLayoutConfig {
+    /** Horizontal spacing between layers (px) */
+    horizontalSpacing: number;
+    /** Vertical spacing between nodes in the same layer (px) */
+    verticalSpacing: number;
+    /** Starting X position */
+    startX: number;
+    /** Starting Y position */
+    startY: number;
+}
+/**
+ * Compute node positions for an Agent Spec flow using layered layout.
+ *
+ * @param flow - The Agent Spec flow to layout
+ * @param config - Optional layout configuration
+ * @returns Map of node name to {x, y} position
+ */
+export declare function computeAutoLayout(flow: AgentSpecFlow, config?: Partial<AutoLayoutConfig>): Map<string, {
+    x: number;
+    y: number;
+}>;

package/dist/adapters/agentspec/autoLayout.js

@@ -0,0 +1,127 @@
+/**
+ * Auto-Layout for Agent Spec Flows
+ *
+ * Agent Spec has no visual position information. This module assigns
+ * positions to imported nodes using a layered layout algorithm:
+ *
+ * 1. Topological sort from StartNode using control-flow edges
+ * 2. Assign layers based on longest path from StartNode
+ * 3. Position nodes with configurable spacing
+ * 4. Fan out branches vertically from BranchingNode
+ */
+const DEFAULT_CONFIG = {
+    horizontalSpacing: 300,
+    verticalSpacing: 150,
+    startX: 100,
+    startY: 100
+};
+/**
+ * Compute node positions for an Agent Spec flow using layered layout.
+ *
+ * @param flow - The Agent Spec flow to layout
+ * @param config - Optional layout configuration
+ * @returns Map of node name to {x, y} position
+ */
+export function computeAutoLayout(flow, config = {}) {
+    const cfg = { ...DEFAULT_CONFIG, ...config };
+    const positions = new Map();
+    if (flow.nodes.length === 0)
+        return positions;
+    // Build adjacency list from control-flow edges
+    const adjacency = new Map();
+    const inDegree = new Map();
+    for (const node of flow.nodes) {
+        adjacency.set(node.name, []);
+        inDegree.set(node.name, 0);
+    }
+    for (const edge of flow.control_flow_connections) {
+        const neighbors = adjacency.get(edge.from_node);
+        if (neighbors) {
+            neighbors.push(edge.to_node);
+        }
+        inDegree.set(edge.to_node, (inDegree.get(edge.to_node) || 0) + 1);
+    }
+    // Also consider data-flow edges for connectivity (but don't affect layering priority)
+    if (flow.data_flow_connections) {
+        for (const edge of flow.data_flow_connections) {
+            if (!adjacency.get(edge.source_node)?.includes(edge.destination_node)) {
+                adjacency.get(edge.source_node)?.push(edge.destination_node);
+            }
+        }
+    }
+    // Assign layers using longest path from start node (BFS with level tracking)
+    const layers = assignLayers(flow.start_node, adjacency, flow.nodes.length);
+    // Group nodes by layer
+    const layerGroups = new Map();
+    for (const [nodeName, layer] of layers) {
+        if (!layerGroups.has(layer)) {
+            layerGroups.set(layer, []);
+        }
+        layerGroups.get(layer).push(nodeName);
+    }
+    // Handle any disconnected nodes (not reachable from start)
+    const assignedNodes = new Set(layers.keys());
+    const disconnected = [];
+    for (const node of flow.nodes) {
+        if (!assignedNodes.has(node.name)) {
+            disconnected.push(node.name);
+        }
+    }
+    // Place disconnected nodes in a final layer
+    if (disconnected.length > 0) {
+        const maxLayer = layerGroups.size > 0 ? Math.max(...layerGroups.keys()) + 1 : 0;
+        layerGroups.set(maxLayer, disconnected);
+    }
+    // Sort layers and assign positions
+    const sortedLayers = Array.from(layerGroups.keys()).sort((a, b) => a - b);
+    for (const layerIndex of sortedLayers) {
+        const nodesInLayer = layerGroups.get(layerIndex);
+        const x = cfg.startX + layerIndex * cfg.horizontalSpacing;
+        // Center nodes vertically
+        const totalHeight = (nodesInLayer.length - 1) * cfg.verticalSpacing;
+        const startY = cfg.startY - totalHeight / 2;
+        for (let i = 0; i < nodesInLayer.length; i++) {
+            positions.set(nodesInLayer[i], {
+                x,
+                y: startY + i * cfg.verticalSpacing
+            });
+        }
+    }
+    return positions;
+}
+/**
+ * Assign layers using longest path from the start node (modified BFS).
+ * This ensures branching nodes fan out properly and convergence points
+ * are placed at the correct depth.
+ */
+function assignLayers(startNode, adjacency, nodeCount) {
+    const layers = new Map();
+    layers.set(startNode, 0);
+    // Use BFS but take the maximum layer for each node
+    // (longest path ensures proper branching layout)
+    const queue = [startNode];
+    const visited = new Set();
+    let iterations = 0;
+    const maxIterations = nodeCount * nodeCount + 100; // Safety limit for cycles
+    while (queue.length > 0 && iterations < maxIterations) {
+        iterations++;
+        const current = queue.shift();
+        if (visited.has(current))
+            continue;
+        visited.add(current);
+        const currentLayer = layers.get(current) || 0;
+        const neighbors = adjacency.get(current) || [];
+        for (const neighbor of neighbors) {
+            const existingLayer = layers.get(neighbor);
+            const newLayer = currentLayer + 1;
+            // Take the max layer (longest path)
+            if (existingLayer === undefined || newLayer > existingLayer) {
+                layers.set(neighbor, newLayer);
+            }
+            if (!visited.has(neighbor)) {
+                queue.push(neighbor);
+            }
+        }
+    }
+    return layers;
+}

package/dist/adapters/agentspec/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Agent Spec Adapter — Barrel Exports
+ *
+ * Provides bidirectional conversion between FlowDrop and Oracle's Open Agent Spec.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   AgentSpecAdapter,
+ *   AgentSpecAgentAdapter,
+ *   getAgentSpecNodeMetadata,
+ *   validateForAgentSpecExport,
+ *   validateAgentSpecFlow
+ * } from '@d34dman/flowdrop/core';
+ *
+ * // Export a FlowDrop workflow as Agent Spec JSON
+ * const adapter = new AgentSpecAdapter();
+ * const agentSpecJson = adapter.exportJSON(workflow);
+ *
+ * // Import an Agent Spec flow into FlowDrop
+ * const flowDropWorkflow = adapter.importJSON(agentSpecJson);
+ *
+ * // Validate before export
+ * const result = validateForAgentSpecExport(workflow);
+ * if (!result.valid) console.error(result.errors);
+ * ```
+ */
+export { AgentSpecAdapter } from './AgentSpecAdapter.js';
+export { AgentSpecAgentAdapter } from './agentAdapter.js';
+export type { AgentConfig, AgentSpecImportResult } from './agentAdapter.js';
+export { getAgentSpecNodeMetadata, getAllAgentSpecNodeTypes, createAgentSpecNodeMetadata, isAgentSpecNodeId, extractComponentType, AGENTSPEC_NAMESPACE } from './nodeTypeRegistry.js';
+export { validateForAgentSpecExport, validateAgentSpecFlow } from './validator.js';
+export type { AgentSpecValidationResult } from './validator.js';
+export { computeAutoLayout } from './autoLayout.js';
+export type { AutoLayoutConfig } from './autoLayout.js';

package/dist/adapters/agentspec/index.js

@@ -0,0 +1,37 @@
+/**
+ * Agent Spec Adapter — Barrel Exports
+ *
+ * Provides bidirectional conversion between FlowDrop and Oracle's Open Agent Spec.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   AgentSpecAdapter,
+ *   AgentSpecAgentAdapter,
+ *   getAgentSpecNodeMetadata,
+ *   validateForAgentSpecExport,
+ *   validateAgentSpecFlow
+ * } from '@d34dman/flowdrop/core';
+ *
+ * // Export a FlowDrop workflow as Agent Spec JSON
+ * const adapter = new AgentSpecAdapter();
+ * const agentSpecJson = adapter.exportJSON(workflow);
+ *
+ * // Import an Agent Spec flow into FlowDrop
+ * const flowDropWorkflow = adapter.importJSON(agentSpecJson);
+ *
+ * // Validate before export
+ * const result = validateForAgentSpecExport(workflow);
+ * if (!result.valid) console.error(result.errors);
+ * ```
+ */
+// Core adapter
+export { AgentSpecAdapter } from './AgentSpecAdapter.js';
+// Agent-level adapter (wraps flow with agent/tools/LLM config)
+export { AgentSpecAgentAdapter } from './agentAdapter.js';
+// Node type registry
+export { getAgentSpecNodeMetadata, getAllAgentSpecNodeTypes, createAgentSpecNodeMetadata, isAgentSpecNodeId, extractComponentType, AGENTSPEC_NAMESPACE } from './nodeTypeRegistry.js';
+// Validation
+export { validateForAgentSpecExport, validateAgentSpecFlow } from './validator.js';
+// Auto-layout
+export { computeAutoLayout } from './autoLayout.js';

package/dist/adapters/agentspec/nodeTypeRegistry.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Agent Spec Node Type Registry
+ *
+ * Maps Agent Spec component types to FlowDrop NodeMetadata definitions.
+ * Each Agent Spec node type gets a full NodeMetadata with visual type,
+ * category, default ports, config schema, and icon.
+ */
+import type { NodeMetadata, NodePort } from '../../types/index.js';
+import type { AgentSpecNodeComponentType } from '../../types/agentspec.js';
+/**
+ * Get FlowDrop NodeMetadata for an Agent Spec component type.
+ *
+ * @param componentType - The Agent Spec component_type value
+ * @returns NodeMetadata for the component type, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const metadata = getAgentSpecNodeMetadata('llm_node');
+ * // Returns NodeMetadata with id='agentspec.llm_node', type='default', category='ai', etc.
+ * ```
+ */
+export declare function getAgentSpecNodeMetadata(componentType: AgentSpecNodeComponentType): NodeMetadata | undefined;
+/**
+ * Get all Agent Spec node types as FlowDrop NodeMetadata.
+ * Useful for populating the node sidebar with Agent Spec node types.
+ *
+ * @returns Array of NodeMetadata for all 9 Agent Spec node types
+ */
+export declare function getAllAgentSpecNodeTypes(): NodeMetadata[];
+/**
+ * Get a copy of the NodeMetadata for a component type with custom inputs/outputs.
+ * Used during import to create node metadata that matches the Agent Spec definition's
+ * actual ports rather than the defaults.
+ *
+ * @param componentType - The Agent Spec component_type value
+ * @param inputs - Custom input ports
+ * @param outputs - Custom output ports
+ * @returns A new NodeMetadata with the custom ports merged in
+ */
+export declare function createAgentSpecNodeMetadata(componentType: AgentSpecNodeComponentType, inputs?: NodePort[], outputs?: NodePort[]): NodeMetadata | undefined;
+/**
+ * Check if a FlowDrop node ID belongs to an Agent Spec node type.
+ *
+ * @example
+ * ```typescript
+ * isAgentSpecNodeId('agentspec.llm_node') // true
+ * isAgentSpecNodeId('calculator') // false
+ * ```
+ */
+export declare function isAgentSpecNodeId(nodeId: string): boolean;
+/**
+ * Extract the Agent Spec component_type from a FlowDrop node type ID.
+ *
+ * @example
+ * ```typescript
+ * extractComponentType('agentspec.llm_node') // 'llm_node'
+ * extractComponentType('calculator') // undefined
+ * ```
+ */
+export declare function extractComponentType(nodeTypeId: string): AgentSpecNodeComponentType | undefined;
+/** The namespace prefix used for Agent Spec node type IDs */
+export declare const AGENTSPEC_NAMESPACE = "agentspec";