@d34dman/flowdrop 0.0.56 → 0.0.57

package/dist/services/agentSpecExecutionService.js

@@ -0,0 +1,333 @@
+/**
+ * Agent Spec Execution Service
+ *
+ * Connects FlowDrop to Agent Spec runtimes (WayFlow/PyAgentSpec) for
+ * workflow execution, status tracking, and result retrieval.
+ *
+ * Follows the same singleton pattern as NodeExecutionService.
+ */
+import { buildAgentSpecUrl, getAgentSpecAuthHeaders } from '../config/agentSpecEndpoints.js';
+import { AgentSpecAdapter } from '../adapters/agentspec/AgentSpecAdapter.js';
+/**
+ * Service for executing FlowDrop workflows on Agent Spec runtimes.
+ *
+ * @example
+ * ```typescript
+ * const service = AgentSpecExecutionService.getInstance();
+ * service.configure(myRuntimeConfig);
+ *
+ * // Check runtime availability
+ * const healthy = await service.checkHealth();
+ *
+ * // Execute a workflow
+ * const handle = await service.executeWorkflow(workflow, inputs, {
+ *   onNodeUpdate: (nodeId, info) => updateNodeVisual(nodeId, info),
+ *   onComplete: (results) => showResults(results),
+ *   onError: (error) => showError(error)
+ * });
+ *
+ * // Cancel if needed
+ * await service.cancelExecution(handle.executionId);
+ * ```
+ */
+export class AgentSpecExecutionService {
+    static instance;
+    config = null;
+    adapter;
+    activeExecutions = new Map();
+    constructor() {
+        this.adapter = new AgentSpecAdapter();
+    }
+    static getInstance() {
+        if (!AgentSpecExecutionService.instance) {
+            AgentSpecExecutionService.instance = new AgentSpecExecutionService();
+        }
+        return AgentSpecExecutionService.instance;
+    }
+    /**
+     * Configure the runtime connection.
+     */
+    configure(config) {
+        this.config = config;
+    }
+    /**
+     * Check if the service has been configured with a runtime.
+     */
+    isConfigured() {
+        return this.config !== null;
+    }
+    /**
+     * Check runtime health.
+     */
+    async checkHealth() {
+        if (!this.config)
+            return false;
+        try {
+            const url = buildAgentSpecUrl(this.config, this.config.endpoints.health);
+            const response = await fetch(url, {
+                headers: getAgentSpecAuthHeaders(this.config),
+                signal: AbortSignal.timeout(5000)
+            });
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Execute a FlowDrop workflow on the Agent Spec runtime.
+     *
+     * 1. Converts StandardWorkflow → AgentSpecFlow using the adapter
+     * 2. POSTs the flow JSON to the runtime
+     * 3. Starts polling for execution status
+     * 4. Maps runtime node statuses to FlowDrop's NodeExecutionInfo
+     */
+    async executeWorkflow(workflow, inputs, callbacks, pollingIntervalMs = 2000) {
+        this.ensureConfigured();
+        // Convert to Agent Spec format
+        const agentSpecFlow = this.adapter.toAgentSpec(workflow);
+        // POST to runtime
+        const url = buildAgentSpecUrl(this.getConfig(), this.getConfig().endpoints.execute);
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: getAgentSpecAuthHeaders(this.getConfig()),
+            body: JSON.stringify({
+                flow: agentSpecFlow,
+                inputs: inputs || {}
+            }),
+            signal: AbortSignal.timeout(this.getConfig().timeout || 60000)
+        });
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => 'Unknown error');
+            throw new Error(`Agent Spec runtime error (${response.status}): ${errorText}`);
+        }
+        const result = await response.json();
+        const executionId = result.execution_id || result.id;
+        if (!executionId) {
+            throw new Error('Runtime did not return an execution ID');
+        }
+        // Track execution
+        const state = {
+            id: executionId,
+            status: 'running',
+            startedAt: new Date().toISOString(),
+            nodeStatuses: {}
+        };
+        this.activeExecutions.set(executionId, state);
+        // Build node name → FlowDrop node ID mapping for status updates
+        const nameToNodeId = new Map();
+        for (const node of workflow.nodes) {
+            const label = node.data.label || node.id;
+            nameToNodeId.set(label, node.id);
+        }
+        // Start polling
+        const stop = () => this.stopPolling(executionId);
+        if (callbacks) {
+            this.startPolling(executionId, nameToNodeId, callbacks.onNodeUpdate, callbacks.onComplete, callbacks.onError, pollingIntervalMs);
+        }
+        return { executionId, stop };
+    }
+    /**
+     * Get current execution status.
+     */
+    async getExecutionStatus(executionId) {
+        this.ensureConfigured();
+        try {
+            const url = buildAgentSpecUrl(this.getConfig(), this.getConfig().endpoints.status, {
+                id: executionId
+            });
+            const response = await fetch(url, {
+                headers: getAgentSpecAuthHeaders(this.getConfig())
+            });
+            if (!response.ok)
+                return null;
+            const data = await response.json();
+            return this.mapRuntimeStatusToNodeInfo(data);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Cancel a running execution.
+     */
+    async cancelExecution(executionId) {
+        this.ensureConfigured();
+        this.stopPolling(executionId);
+        const url = buildAgentSpecUrl(this.getConfig(), this.getConfig().endpoints.cancel, {
+            id: executionId
+        });
+        await fetch(url, {
+            method: 'POST',
+            headers: getAgentSpecAuthHeaders(this.getConfig())
+        });
+        const state = this.activeExecutions.get(executionId);
+        if (state) {
+            state.status = 'cancelled';
+        }
+    }
+    /**
+     * Get execution results.
+     */
+    async getResults(executionId) {
+        this.ensureConfigured();
+        try {
+            const url = buildAgentSpecUrl(this.getConfig(), this.getConfig().endpoints.results, {
+                id: executionId
+            });
+            const response = await fetch(url, {
+                headers: getAgentSpecAuthHeaders(this.getConfig())
+            });
+            if (!response.ok)
+                return null;
+            return await response.json();
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Validate a workflow against the runtime.
+     */
+    async validateOnRuntime(workflow) {
+        this.ensureConfigured();
+        const agentSpecFlow = this.adapter.toAgentSpec(workflow);
+        const url = buildAgentSpecUrl(this.getConfig(), this.getConfig().endpoints.validate);
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: getAgentSpecAuthHeaders(this.getConfig()),
+            body: JSON.stringify(agentSpecFlow)
+        });
+        if (!response.ok) {
+            return { valid: false, errors: [`Runtime validation failed: ${response.status}`] };
+        }
+        return await response.json();
+    }
+    /**
+     * Clean up all active executions.
+     */
+    destroy() {
+        for (const [id] of this.activeExecutions) {
+            this.stopPolling(id);
+        }
+        this.activeExecutions.clear();
+    }
+    // ========================================================================
+    // Private
+    // ========================================================================
+    ensureConfigured() {
+        if (!this.config) {
+            throw new Error('AgentSpecExecutionService not configured. Call configure() with runtime endpoint config first.');
+        }
+    }
+    /** Get the config, throwing if not configured */
+    getConfig() {
+        this.ensureConfigured();
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        return this.config;
+    }
+    startPolling(executionId, nameToNodeId, onNodeUpdate, onComplete, onError, intervalMs = 2000) {
+        const state = this.activeExecutions.get(executionId);
+        if (!state)
+            return;
+        const poll = async () => {
+            try {
+                const url = buildAgentSpecUrl(this.getConfig(), this.getConfig().endpoints.status, {
+                    id: executionId
+                });
+                const response = await fetch(url, {
+                    headers: getAgentSpecAuthHeaders(this.getConfig())
+                });
+                if (!response.ok) {
+                    throw new Error(`Status check failed: ${response.status}`);
+                }
+                const data = await response.json();
+                const executionStatus = data.status || data.execution_status;
+                // Map node statuses
+                const nodeStatuses = data.node_statuses || data.nodes || {};
+                for (const [nodeName, status] of Object.entries(nodeStatuses)) {
+                    const nodeId = nameToNodeId.get(nodeName) || nodeName;
+                    const info = this.mapSingleNodeStatus(status);
+                    state.nodeStatuses[nodeId] = info;
+                    onNodeUpdate?.(nodeId, info);
+                }
+                // Check if execution is done
+                if (executionStatus === 'completed' || executionStatus === 'success') {
+                    state.status = 'completed';
+                    this.stopPolling(executionId);
+                    const results = await this.getResults(executionId);
+                    onComplete?.(results || {});
+                }
+                else if (executionStatus === 'failed' || executionStatus === 'error') {
+                    state.status = 'failed';
+                    this.stopPolling(executionId);
+                    const errorMsg = data.error || data.message || 'Execution failed';
+                    onError?.(new Error(errorMsg));
+                }
+                else if (executionStatus === 'cancelled') {
+                    state.status = 'cancelled';
+                    this.stopPolling(executionId);
+                }
+            }
+            catch (error) {
+                // Don't stop polling on transient errors — let it retry
+                console.error('[AgentSpecExecution] Polling error:', error);
+            }
+        };
+        // Initial poll immediately, then at interval
+        poll();
+        state.pollingInterval = setInterval(poll, intervalMs);
+    }
+    stopPolling(executionId) {
+        const state = this.activeExecutions.get(executionId);
+        if (state?.pollingInterval) {
+            clearInterval(state.pollingInterval);
+            state.pollingInterval = undefined;
+        }
+    }
+    mapRuntimeStatusToNodeInfo(data) {
+        const result = {};
+        const nodeStatuses = (data.node_statuses || data.nodes || {});
+        for (const [nodeName, status] of Object.entries(nodeStatuses)) {
+            result[nodeName] = this.mapSingleNodeStatus(status);
+        }
+        return result;
+    }
+    mapSingleNodeStatus(status) {
+        const runtimeStatus = (status.status || status.state || 'idle');
+        return {
+            status: this.mapToFlowDropStatus(runtimeStatus),
+            executionCount: status.execution_count || 0,
+            isExecuting: runtimeStatus === 'running' || runtimeStatus === 'executing',
+            lastExecuted: status.started_at,
+            lastExecutionDuration: status.duration_ms,
+            lastError: status.error
+        };
+    }
+    mapToFlowDropStatus(runtimeStatus) {
+        switch (runtimeStatus) {
+            case 'running':
+            case 'executing':
+                return 'running';
+            case 'completed':
+            case 'success':
+            case 'done':
+                return 'completed';
+            case 'failed':
+            case 'error':
+                return 'failed';
+            case 'cancelled':
+            case 'canceled':
+                return 'cancelled';
+            case 'pending':
+            case 'queued':
+                return 'pending';
+            case 'skipped':
+                return 'skipped';
+            default:
+                return 'idle';
+        }
+    }
+}
+/** Singleton instance */
+export const agentSpecExecutionService = AgentSpecExecutionService.getInstance();

package/dist/types/agentspec.d.ts

@@ -0,0 +1,318 @@
+/**
+ * Open Agent Specification (Agent Spec) TypeScript Types
+ *
+ * Type definitions mirroring Oracle's Open Agent Spec format.
+ * Used for bidirectional conversion between FlowDrop and Agent Spec.
+ *
+ * @see https://github.com/oracle/agent-spec
+ * @see https://oracle.github.io/agent-spec/
+ */
+/** Agent Spec node component_type discriminator values */
+export type AgentSpecNodeComponentType = 'start_node' | 'end_node' | 'llm_node' | 'api_node' | 'agent_node' | 'flow_node' | 'map_node' | 'branching_node' | 'tool_node';
+/** Agent Spec tool component_type discriminator values */
+export type AgentSpecToolComponentType = 'server_tool' | 'client_tool' | 'remote_tool';
+/** All Agent Spec component_type values */
+export type AgentSpecComponentType = 'agent' | 'flow' | AgentSpecNodeComponentType | AgentSpecToolComponentType | 'llm_config';
+/**
+ * Agent Spec Property — JSON Schema-based input/output definition.
+ *
+ * Uses JSON Schema types and structure for describing data shape.
+ * Placeholder syntax `{{variable_name}}` generates implicit input properties.
+ */
+export interface AgentSpecProperty {
+    /** Property name (used as identifier in edges and templates) */
+    title: string;
+    /** JSON Schema type */
+    type: string;
+    /** Human-readable description */
+    description?: string;
+    /** Default value */
+    default?: unknown;
+    /** Allowed values (JSON Schema enum) */
+    enum?: unknown[];
+    /** Array item schema */
+    items?: AgentSpecProperty;
+    /** Object property schemas */
+    properties?: Record<string, AgentSpecProperty>;
+    /** Required properties (for object types) */
+    required?: string[];
+    /** Additional JSON Schema fields */
+    [key: string]: unknown;
+}
+/** Base interface for all Agent Spec nodes */
+export interface AgentSpecNodeBase {
+    /** Discriminator for node type */
+    component_type: AgentSpecNodeComponentType;
+    /** Node name (used as identifier in edges) */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Input properties */
+    inputs?: AgentSpecProperty[];
+    /** Output properties */
+    outputs?: AgentSpecProperty[];
+    /** Extension metadata (includes FlowDrop-specific data for round-trip) */
+    metadata?: Record<string, unknown>;
+}
+/** Graph entry point */
+export interface AgentSpecStartNode extends AgentSpecNodeBase {
+    component_type: 'start_node';
+}
+/** Graph exit point */
+export interface AgentSpecEndNode extends AgentSpecNodeBase {
+    component_type: 'end_node';
+}
+/** LLM text generation node */
+export interface AgentSpecLLMNode extends AgentSpecNodeBase {
+    component_type: 'llm_node';
+    /** LLM configuration (inline or $component_ref string) */
+    llm_config?: AgentSpecLLMConfig | string;
+    /** System prompt template (supports {{variable}} syntax) */
+    system_prompt?: string;
+    /** User prompt template (supports {{variable}} syntax) */
+    prompt_template?: string;
+    /** Output JSON Schema for structured output */
+    output_schema?: Record<string, unknown>;
+}
+/** API call node */
+export interface AgentSpecAPINode extends AgentSpecNodeBase {
+    component_type: 'api_node';
+    /** API endpoint URL */
+    endpoint?: string;
+    /** HTTP method */
+    method?: string;
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Request body template */
+    body?: Record<string, unknown>;
+}
+/** Multi-round agent conversation node */
+export interface AgentSpecAgentNode extends AgentSpecNodeBase {
+    component_type: 'agent_node';
+    /** Agent reference ($component_ref or inline) */
+    agent?: AgentSpecAgent | string;
+}
+/** Nested flow execution node */
+export interface AgentSpecFlowNode extends AgentSpecNodeBase {
+    component_type: 'flow_node';
+    /** Flow reference ($component_ref or inline) */
+    flow?: AgentSpecFlow | string;
+}
+/** Map-reduce operation node */
+export interface AgentSpecMapNode extends AgentSpecNodeBase {
+    component_type: 'map_node';
+    /** Input collection property name */
+    input_collection?: string;
+    /** Output collection property name */
+    output_collection?: string;
+    /** Flow or node to execute per item ($component_ref or inline) */
+    map_flow?: AgentSpecFlow | string;
+}
+/** Conditional routing node */
+export interface AgentSpecBranchingNode extends AgentSpecNodeBase {
+    component_type: 'branching_node';
+    /** Branch definitions with conditions */
+    branches: AgentSpecBranch[];
+}
+/** Tool execution node */
+export interface AgentSpecToolNode extends AgentSpecNodeBase {
+    component_type: 'tool_node';
+    /** Tool reference ($component_ref or inline) */
+    tool?: AgentSpecTool | string;
+}
+/** Union of all Agent Spec node types */
+export type AgentSpecNode = AgentSpecStartNode | AgentSpecEndNode | AgentSpecLLMNode | AgentSpecAPINode | AgentSpecAgentNode | AgentSpecFlowNode | AgentSpecMapNode | AgentSpecBranchingNode | AgentSpecToolNode;
+/** Branch definition for BranchingNode */
+export interface AgentSpecBranch {
+    /** Branch name (used as from_branch in ControlFlowEdge) */
+    name: string;
+    /** Condition expression for this branch */
+    condition?: string;
+    /** Human-readable description */
+    description?: string;
+}
+/**
+ * Control Flow Edge — defines execution order between nodes.
+ *
+ * Multiple control flow connections from the same branch are prohibited.
+ */
+export interface AgentSpecControlFlowEdge {
+    /** Edge name (identifier) */
+    name: string;
+    /** Source node name */
+    from_node: string;
+    /** Target node name */
+    to_node: string;
+    /** Source branch name (null/undefined = default "next" branch) */
+    from_branch?: string | null;
+}
+/**
+ * Data Flow Edge — routes data between node outputs and inputs.
+ *
+ * Maps a specific output property of a source node to a specific
+ * input property of a destination node.
+ */
+export interface AgentSpecDataFlowEdge {
+    /** Edge name (identifier) */
+    name: string;
+    /** Source node name */
+    source_node: string;
+    /** Source output property title */
+    source_output: string;
+    /** Destination node name */
+    destination_node: string;
+    /** Destination input property title */
+    destination_input: string;
+}
+/**
+ * Agent Spec Flow — a directed, potentially cyclic graph of nodes.
+ *
+ * Flows function as "subroutines" encapsulating repeatable processes.
+ * They separate control-flow (execution order) from data-flow (data routing).
+ */
+export interface AgentSpecFlow {
+    component_type: 'flow';
+    /** Flow name */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Reference to the StartNode name */
+    start_node: string;
+    /** All nodes in the flow */
+    nodes: AgentSpecNode[];
+    /** Execution order edges */
+    control_flow_connections: AgentSpecControlFlowEdge[];
+    /**
+     * Data routing edges.
+     * When null, data flows by matching input/output property names
+     * across connected nodes (name-based variable access).
+     */
+    data_flow_connections?: AgentSpecDataFlowEdge[] | null;
+    /** Extension metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Base interface for Agent Spec tools */
+export interface AgentSpecToolBase {
+    component_type: AgentSpecToolComponentType;
+    /** Tool name */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Input parameters */
+    inputs?: AgentSpecProperty[];
+    /** Output parameters */
+    outputs?: AgentSpecProperty[];
+    /** Extension metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Tool executed in the same runtime environment */
+export interface AgentSpecServerTool extends AgentSpecToolBase {
+    component_type: 'server_tool';
+    /** Function name or module path */
+    function_name?: string;
+}
+/** Tool executed by the client, results returned to runtime */
+export interface AgentSpecClientTool extends AgentSpecToolBase {
+    component_type: 'client_tool';
+}
+/** Tool triggered via RPC/REST calls */
+export interface AgentSpecRemoteTool extends AgentSpecToolBase {
+    component_type: 'remote_tool';
+    /** Remote endpoint URL */
+    endpoint?: string;
+    /** HTTP method */
+    method?: string;
+    /** Request headers */
+    headers?: Record<string, string>;
+}
+/** Union of all Agent Spec tool types */
+export type AgentSpecTool = AgentSpecServerTool | AgentSpecClientTool | AgentSpecRemoteTool;
+/** LLM model configuration */
+export interface AgentSpecLLMConfig {
+    component_type: 'llm_config';
+    /** Configuration name */
+    name: string;
+    /** Model identifier (e.g., "gpt-4o", "claude-sonnet-4-5-20250929") */
+    model_id: string;
+    /** Provider name (e.g., "openai", "anthropic") */
+    provider?: string;
+    /** API endpoint URL */
+    url?: string;
+    /** Generation parameters (temperature, max_tokens, etc.) */
+    parameters?: Record<string, unknown>;
+    /** Extension metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Agent Spec Agent — top-level conversational AI system.
+ *
+ * Serves as the entry point and holds shared resources like
+ * tools, memory, and LLM configuration.
+ */
+export interface AgentSpecAgent {
+    component_type: 'agent';
+    /** Agent name */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Agent inputs */
+    inputs?: AgentSpecProperty[];
+    /** Agent outputs */
+    outputs?: AgentSpecProperty[];
+    /** Available tools (inline or $component_ref strings) */
+    tools?: (AgentSpecTool | string)[];
+    /** LLM configuration (inline or $component_ref string) */
+    llm_config?: AgentSpecLLMConfig | string;
+    /** System prompt template */
+    system_prompt?: string;
+    /** Extension metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Top-level Agent Spec document.
+ *
+ * Contains a flow and/or agent definition along with shared
+ * tool and LLM configuration declarations.
+ */
+export interface AgentSpecDocument {
+    /** Agent definition */
+    agent?: AgentSpecAgent;
+    /** Flow definition */
+    flow?: AgentSpecFlow;
+    /** Shared tool declarations */
+    tools?: AgentSpecTool[];
+    /** Shared LLM configurations */
+    llm_configs?: AgentSpecLLMConfig[];
+    /** Document-level metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Prefix for component references in Agent Spec */
+export declare const COMPONENT_REF_PREFIX = "$component_ref:";
+/**
+ * Check if a value is a component reference string.
+ *
+ * @example
+ * ```typescript
+ * isComponentRef("$component_ref:my_tool") // true
+ * isComponentRef("just a string") // false
+ * ```
+ */
+export declare function isComponentRef(value: unknown): value is string;
+/**
+ * Extract the component ID from a component reference string.
+ *
+ * @example
+ * ```typescript
+ * extractComponentRefId("$component_ref:my_tool") // "my_tool"
+ * ```
+ */
+export declare function extractComponentRefId(ref: string): string;
+/**
+ * Create a component reference string.
+ *
+ * @example
+ * ```typescript
+ * createComponentRef("my_tool") // "$component_ref:my_tool"
+ * ```
+ */
+export declare function createComponentRef(componentId: string): string;

package/dist/types/agentspec.js

@@ -0,0 +1,48 @@
+/**
+ * Open Agent Specification (Agent Spec) TypeScript Types
+ *
+ * Type definitions mirroring Oracle's Open Agent Spec format.
+ * Used for bidirectional conversion between FlowDrop and Agent Spec.
+ *
+ * @see https://github.com/oracle/agent-spec
+ * @see https://oracle.github.io/agent-spec/
+ */
+// ============================================================================
+// Component Reference
+// ============================================================================
+/** Prefix for component references in Agent Spec */
+export const COMPONENT_REF_PREFIX = '$component_ref:';
+/**
+ * Check if a value is a component reference string.
+ *
+ * @example
+ * ```typescript
+ * isComponentRef("$component_ref:my_tool") // true
+ * isComponentRef("just a string") // false
+ * ```
+ */
+export function isComponentRef(value) {
+    return typeof value === 'string' && value.startsWith(COMPONENT_REF_PREFIX);
+}
+/**
+ * Extract the component ID from a component reference string.
+ *
+ * @example
+ * ```typescript
+ * extractComponentRefId("$component_ref:my_tool") // "my_tool"
+ * ```
+ */
+export function extractComponentRefId(ref) {
+    return ref.slice(COMPONENT_REF_PREFIX.length);
+}
+/**
+ * Create a component reference string.
+ *
+ * @example
+ * ```typescript
+ * createComponentRef("my_tool") // "$component_ref:my_tool"
+ * ```
+ */
+export function createComponentRef(componentId) {
+    return `${COMPONENT_REF_PREFIX}${componentId}`;
+}