@d34dman/flowdrop 0.0.56 → 0.0.58

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/componentTypeDefaults.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Agent Spec Component Type Defaults
+ *
+ * Internal adapter infrastructure for import/export.
+ * Provides lightweight defaults per component_type (trigger ports, visual styling)
+ * WITHOUT prescribing full node type definitions (data ports, config schemas).
+ *
+ * Full node type definitions are user-provided via getDefaultAgentSpecNodeTypes()
+ * or custom node arrays passed to mountFlowDropApp().
+ */
+import type { NodePort } from '../../types/index.js';
+/** Namespace prefix for Agent Spec node type IDs */
+export declare const AGENTSPEC_NAMESPACE = "agentspec";
+/** Standard trigger input port — control flow into a node */
+export declare const TRIGGER_INPUT: NodePort;
+/** Standard trigger output port — control flow out of a node */
+export declare const TRIGGER_OUTPUT: NodePort;
+/**
+ * Lightweight defaults for a component_type.
+ * Used during import to construct minimal NodeMetadata from Agent Spec JSON.
+ * These are NOT full node type definitions — they only contain what the
+ * adapter needs to create valid FlowDrop nodes.
+ */
+export interface ComponentTypeDefaults {
+    /** FlowDrop visual node type (terminal, gateway, default, tool, simple) */
+    visualType: string;
+    /** Node category for sidebar grouping */
+    category: string;
+    /** Default display color */
+    color: string;
+    /** Default icon (MDI format) */
+    icon: string;
+    /** Badge text for node header */
+    badge: string;
+    /** Default node name when no name provided */
+    defaultName: string;
+    /** Default description */
+    defaultDescription: string;
+    /** Trigger/tool ports to prepend to data inputs during import */
+    triggerInputs: NodePort[];
+    /** Trigger/tool ports to prepend to data outputs during import */
+    triggerOutputs: NodePort[];
+}
+/**
+ * Get adapter defaults for a component type.
+ * Returns sensible fallbacks for unrecognized types (never throws).
+ *
+ * @param componentType - The Agent Spec component_type value
+ * @returns ComponentTypeDefaults for the type, or fallback for unknown types
+ */
+export declare function getComponentTypeDefaults(componentType: string): ComponentTypeDefaults;
+/**
+ * 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 component_type string from a FlowDrop node type ID.
+ * Does not validate against any registry — any string after the namespace prefix is returned.
+ *
+ * @example
+ * ```typescript
+ * extractComponentType('agentspec.llm_node') // 'llm_node'
+ * extractComponentType('agentspec.my_custom') // 'my_custom'
+ * extractComponentType('calculator') // undefined
+ * ```
+ */
+export declare function extractComponentType(nodeTypeId: string): string | undefined;

package/dist/adapters/agentspec/componentTypeDefaults.js

@@ -0,0 +1,238 @@
+/**
+ * Agent Spec Component Type Defaults
+ *
+ * Internal adapter infrastructure for import/export.
+ * Provides lightweight defaults per component_type (trigger ports, visual styling)
+ * WITHOUT prescribing full node type definitions (data ports, config schemas).
+ *
+ * Full node type definitions are user-provided via getDefaultAgentSpecNodeTypes()
+ * or custom node arrays passed to mountFlowDropApp().
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+/** Namespace prefix for Agent Spec node type IDs */
+export const AGENTSPEC_NAMESPACE = 'agentspec';
+// ============================================================================
+// Standard ports (adapter infrastructure)
+// ============================================================================
+/** Standard trigger input port — control flow into a node */
+export const TRIGGER_INPUT = {
+    id: 'trigger',
+    name: 'Trigger',
+    type: 'input',
+    dataType: 'trigger',
+    required: false,
+    description: 'Control flow input'
+};
+/** Standard trigger output port — control flow out of a node */
+export const TRIGGER_OUTPUT = {
+    id: 'trigger',
+    name: 'Trigger',
+    type: 'output',
+    dataType: 'trigger',
+    required: false,
+    description: 'Control flow output'
+};
+/** Tool input port for tool_node */
+const TOOL_INPUT = {
+    id: 'tool',
+    name: 'Tool',
+    type: 'input',
+    dataType: 'tool',
+    required: false,
+    description: 'Tool connection'
+};
+/** Tool output port for tool_node */
+const TOOL_OUTPUT = {
+    id: 'tool',
+    name: 'Tool',
+    type: 'output',
+    dataType: 'tool',
+    description: 'Tool passthrough'
+};
+// ============================================================================
+// Defaults mapping
+// ============================================================================
+const COMPONENT_TYPE_DEFAULTS = new Map([
+    [
+        'start_node',
+        {
+            visualType: 'terminal',
+            category: 'triggers',
+            color: '#22c55e',
+            icon: 'mdi:play-circle',
+            badge: 'START',
+            defaultName: 'Start',
+            defaultDescription: 'Flow entry point. Defines the initial inputs for the flow.',
+            triggerInputs: [],
+            triggerOutputs: [TRIGGER_OUTPUT]
+        }
+    ],
+    [
+        'end_node',
+        {
+            visualType: 'terminal',
+            category: 'outputs',
+            color: '#ef4444',
+            icon: 'mdi:stop-circle',
+            badge: 'END',
+            defaultName: 'End',
+            defaultDescription: 'Flow exit point. Defines the final outputs of the flow.',
+            triggerInputs: [TRIGGER_INPUT],
+            triggerOutputs: []
+        }
+    ],
+    [
+        'llm_node',
+        {
+            visualType: 'default',
+            category: 'ai',
+            color: '#8b5cf6',
+            icon: 'mdi:brain',
+            badge: 'LLM',
+            defaultName: 'LLM',
+            defaultDescription: 'Generate text using a large language model with configurable prompts.',
+            triggerInputs: [TRIGGER_INPUT],
+            triggerOutputs: [TRIGGER_OUTPUT]
+        }
+    ],
+    [
+        'branching_node',
+        {
+            visualType: 'gateway',
+            category: 'logic',
+            color: '#f59e0b',
+            icon: 'mdi:source-branch',
+            badge: 'BRANCH',
+            defaultName: 'Branch',
+            defaultDescription: 'Route execution to different paths based on conditions.',
+            triggerInputs: [TRIGGER_INPUT],
+            triggerOutputs: []
+        }
+    ],
+    [
+        'tool_node',
+        {
+            visualType: 'tool',
+            category: 'tools',
+            color: '#06b6d4',
+            icon: 'mdi:wrench',
+            badge: 'TOOL',
+            defaultName: 'Tool',
+            defaultDescription: 'Execute a tool function with inputs and receive outputs.',
+            triggerInputs: [TRIGGER_INPUT, TOOL_INPUT],
+            triggerOutputs: [TRIGGER_OUTPUT, TOOL_OUTPUT]
+        }
+    ],
+    [
+        'api_node',
+        {
+            visualType: 'default',
+            category: 'data',
+            color: '#3b82f6',
+            icon: 'mdi:api',
+            badge: 'API',
+            defaultName: 'API Call',
+            defaultDescription: 'Make an HTTP API call with configurable endpoint, method, and headers.',
+            triggerInputs: [TRIGGER_INPUT],
+            triggerOutputs: [TRIGGER_OUTPUT]
+        }
+    ],
+    [
+        'agent_node',
+        {
+            visualType: 'default',
+            category: 'agents',
+            color: '#ec4899',
+            icon: 'mdi:robot',
+            badge: 'AGENT',
+            defaultName: 'Agent',
+            defaultDescription: 'Run a multi-round agent conversation within the flow.',
+            triggerInputs: [TRIGGER_INPUT],
+            triggerOutputs: [TRIGGER_OUTPUT]
+        }
+    ],
+    [
+        'flow_node',
+        {
+            visualType: 'simple',
+            category: 'processing',
+            color: '#14b8a6',
+            icon: 'mdi:sitemap',
+            badge: 'FLOW',
+            defaultName: 'Sub-Flow',
+            defaultDescription: 'Execute another flow as a sub-routine within this flow.',
+            triggerInputs: [TRIGGER_INPUT],
+            triggerOutputs: [TRIGGER_OUTPUT]
+        }
+    ],
+    [
+        'map_node',
+        {
+            visualType: 'default',
+            category: 'processing',
+            color: '#f97316',
+            icon: 'mdi:map-marker-path',
+            badge: 'MAP',
+            defaultName: 'Map',
+            defaultDescription: 'Apply a flow or operation to each item in a collection (map-reduce).',
+            triggerInputs: [TRIGGER_INPUT],
+            triggerOutputs: [TRIGGER_OUTPUT]
+        }
+    ]
+]);
+/** Fallback defaults for unrecognized component types */
+const UNKNOWN_DEFAULTS = {
+    visualType: 'default',
+    category: 'processing',
+    color: '#6b7280',
+    icon: 'mdi:puzzle',
+    badge: '',
+    defaultName: 'Unknown',
+    defaultDescription: 'Agent Spec node',
+    triggerInputs: [TRIGGER_INPUT],
+    triggerOutputs: [TRIGGER_OUTPUT]
+};
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Get adapter defaults for a component type.
+ * Returns sensible fallbacks for unrecognized types (never throws).
+ *
+ * @param componentType - The Agent Spec component_type value
+ * @returns ComponentTypeDefaults for the type, or fallback for unknown types
+ */
+export function getComponentTypeDefaults(componentType) {
+    return COMPONENT_TYPE_DEFAULTS.get(componentType) ?? UNKNOWN_DEFAULTS;
+}
+/**
+ * Check if a FlowDrop node ID belongs to an Agent Spec node type.
+ *
+ * @example
+ * ```typescript
+ * isAgentSpecNodeId('agentspec.llm_node') // true
+ * isAgentSpecNodeId('calculator') // false
+ * ```
+ */
+export function isAgentSpecNodeId(nodeId) {
+    return nodeId.startsWith(`${AGENTSPEC_NAMESPACE}.`);
+}
+/**
+ * Extract the component_type string from a FlowDrop node type ID.
+ * Does not validate against any registry — any string after the namespace prefix is returned.
+ *
+ * @example
+ * ```typescript
+ * extractComponentType('agentspec.llm_node') // 'llm_node'
+ * extractComponentType('agentspec.my_custom') // 'my_custom'
+ * extractComponentType('calculator') // undefined
+ * ```
+ */
+export function extractComponentType(nodeTypeId) {
+    if (!isAgentSpecNodeId(nodeTypeId))
+        return undefined;
+    const componentType = nodeTypeId.slice(AGENTSPEC_NAMESPACE.length + 1);
+    return componentType || undefined;
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Agent Spec Default Node Types
+ *
+ * Provides optional starter node type definitions for the Agent Spec format.
+ * These are full NodeMetadata objects with visual type, category, default ports,
+ * config schema, and icon — suitable for populating the sidebar.
+ *
+ * These definitions are NOT required by the adapter — the adapter uses
+ * componentTypeDefaults.ts for import/export infrastructure.
+ * Users can provide their own node definitions instead.
+ *
+ * @example
+ * ```typescript
+ * import { getDefaultAgentSpecNodeTypes } from '@d34dman/flowdrop/core';
+ *
+ * mountFlowDropApp(container, {
+ *   nodes: getDefaultAgentSpecNodeTypes(), // or your own definitions
+ * });
+ * ```
+ */
+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 default Agent Spec node types as FlowDrop NodeMetadata.
+ * These are starter templates — users can provide their own node types instead.
+ *
+ * @returns Array of NodeMetadata for all 9 default Agent Spec node types
+ */
+export declare function getDefaultAgentSpecNodeTypes(): 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;