@ai-setting/roy-agent-core 1.0.0

package/src/env/workflow/nodes/skill-node.ts

@@ -0,0 +1,393 @@
+import { Node, NodeDefinition, NodeExecutionContext, NodeExecutionResult } from '../types';
+
+/**
+ * Skill Registry interface for looking up skills
+ */
+export interface SkillRegistry {
+  getSkill(name: string): Skill | undefined;
+  hasSkill(name: string): boolean;
+}
+
+/**
+ * Skill interface for invocation
+ */
+export interface Skill {
+  name: string;
+  invoke(input: any, context: any): Promise<any>;
+}
+
+/**
+ * SkillNode invokes a registered Skill with the provided input.
+ * 
+ * Input can contain template strings like {{nodeId.output.path}} that will be
+ * resolved from previousOutputs.
+ */
+export class SkillNode implements Node {
+  readonly type = 'skill';
+  readonly id: string;
+  
+  constructor(
+    private definition: NodeDefinition,
+    private skillRegistry: SkillRegistry
+  ) {
+    this.id = definition.id;
+  }
+  
+  async execute(context: NodeExecutionContext): Promise<NodeExecutionResult> {
+    const startTime = Date.now();
+    
+    try {
+      // 1. Get skill name from definition.config.skill
+      const skillName = this.definition.config?.skill as string | undefined;
+      
+      if (!skillName) {
+        throw new Error('Skill name is required. Please specify config.skill in the node definition.');
+      }
+      
+      // 2. Look up skill from registry
+      const skill = this.skillRegistry.getSkill(skillName);
+      
+      if (!skill) {
+        throw new Error(`Skill not found: ${skillName}`);
+      }
+      
+      // 3. Prepare input (may reference previous outputs and workflow input)
+      const input = this.definition.config?.input ?? {};
+      const resolvedInput = this.resolveTemplateReferences(input, context.previousOutputs, context.input as any);
+      
+      // 4. Prepare context for skill invocation
+      const skillContext = {
+        runId: context.runId,
+        workflowName: context.workflowName,
+        nodeId: context.nodeId,
+        debug: context.debug,
+      };
+      
+      // 5. Invoke skill
+      const output = await skill.invoke(resolvedInput, skillContext);
+      
+      // 6. Return result
+      return {
+        output,
+        error: undefined,
+        durationMs: Date.now() - startTime,
+      };
+    } catch (error) {
+      return {
+        output: undefined,
+        error: error instanceof Error ? error : new Error(String(error)),
+        durationMs: Date.now() - startTime,
+      };
+    }
+  }
+  
+  /**
+   * Resolve template references in input values.
+   * Templates can be in the format:
+   * - {{input.key}} - from workflow input
+   * - {{nodeId}} - entire previous node output
+   * - {{nodeId.path}} - nested path within previous node output
+   * - {{nodes.nodeId}} - entire previous node output (alias)
+   * - {{nodes.nodeId.path}} - nested path within previous node output
+   * 
+   * Key behavior for template strings:
+   * - If the string is a pure template reference (e.g., "{{nodes.fetch}}"), 
+   *   the resolved value is returned as-is (preserving objects/arrays)
+   * - If the string contains text + templates (e.g., "Hello {{name}}"),
+   *   returns a string with interpolated values
+   * 
+   * @param input - The input object that may contain template strings
+   * @param previousOutputs - Map of previous node outputs
+   * @param workflowInput - The workflow input parameters
+   * @returns The input with template references resolved
+   */
+  private resolveTemplateReferences(
+    input: any, 
+    previousOutputs: Map<string, any>,
+    workflowInput?: Record<string, unknown>
+  ): any {
+    if (typeof input === 'string') {
+      // Check if this is a pure template reference (no surrounding text)
+      const pureTemplate = this.extractPureTemplate(input);
+      if (pureTemplate) {
+        // Pure template reference - resolve and return value as-is (preserve objects/arrays)
+        return this.resolvePureTemplate(pureTemplate, previousOutputs, workflowInput);
+      }
+      // Mixed text + templates - return resolved string
+      return this.resolveStringTemplate(input, previousOutputs, workflowInput);
+    }
+    
+    if (Array.isArray(input)) {
+      return input.map(item => this.resolveTemplateReferences(item, previousOutputs, workflowInput));
+    }
+    
+    if (input !== null && typeof input === 'object') {
+      const resolved: Record<string, any> = {};
+      for (const [key, value] of Object.entries(input)) {
+        resolved[key] = this.resolveTemplateReferences(value, previousOutputs, workflowInput);
+      }
+      return resolved;
+    }
+    
+    // Return primitive values as-is
+    return input;
+  }
+
+  /**
+   * Check if a string is a pure template reference (starts with {{ and ends with }})
+   * @param str - String to check
+   * @returns The template content if pure, null otherwise
+   */
+  private extractPureTemplate(str: string): string | null {
+    const trimmed = str.trim();
+    if (trimmed.startsWith('{{') && trimmed.endsWith('}}') && trimmed.length > 4) {
+      // Extract content between {{ and }}
+      const content = trimmed.slice(2, -2).trim();
+      // Check there's no other text (except the template patterns themselves)
+      if (!content.includes('{{') && !content.includes('}}')) {
+        return content;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Resolve a pure template reference and return the value as-is.
+   * @param templateContent - Content between {{ and }}
+   * @param previousOutputs - Map of previous node outputs
+   * @param workflowInput - The workflow input parameters
+   * @returns The resolved value (may be object, array, or primitive), 
+   *          or the original template string if unresolved
+   */
+  private resolvePureTemplate(
+    templateContent: string,
+    previousOutputs: Map<string, any>,
+    workflowInput?: Record<string, unknown>
+  ): any {
+    const trimmed = templateContent.trim();
+    const originalTemplate = `{{${templateContent}}}`;
+    
+    // Pattern 1: {{input.key}} or {{input.key.nested}}
+    if (trimmed.startsWith('input.')) {
+      const value = this.getNestedValue(workflowInput, trimmed.slice(6));
+      return value !== undefined ? value : originalTemplate;
+    }
+    
+    // Pattern 2: {{nodes.nodeId}} or {{nodes.nodeId.output}}
+    if (trimmed.startsWith('nodes.')) {
+      const path = trimmed.slice(6);
+      const segments = path.split('.');
+      const nodeId = segments[0];
+      const restPath = segments.slice(1).join('.') || undefined;
+      const value = this.resolvePath(nodeId, restPath, previousOutputs);
+      return value !== undefined ? value : originalTemplate;
+    }
+    
+    // Pattern 3: Bare nodeId (backward compatibility)
+    if (trimmed !== 'input' && trimmed !== 'nodes') {
+      const segments = trimmed.split('.');
+      const nodeId = segments[0];
+      const restPath = segments.slice(1).join('.') || undefined;
+      const value = this.resolvePath(nodeId, restPath, previousOutputs);
+      return value !== undefined ? value : originalTemplate;
+    }
+    
+    return originalTemplate;
+  }
+  
+  /**
+   * Resolve template references in a single string (for mixed text + templates).
+   * Supports formats:
+   * - {{input.key}} - from workflow input
+   * - {{nodeId}} - entire previous node output
+   * - {{nodeId.path}} - nested path within previous node output
+   * - {{nodes.nodeId}} - entire previous node output (alias)
+   * - {{nodes.nodeId.path}} - nested path within previous node output
+   * 
+   * Note: Returns string because the input contains text around the template.
+   * For pure template references, use resolvePureTemplate instead.
+   */
+  private resolveStringTemplate(
+    template: string, 
+    previousOutputs: Map<string, any>,
+    workflowInput?: Record<string, unknown>
+  ): string {
+    let resolved = template;
+
+    // Pattern 1: {{input.key}} or {{input.key.path}}
+    resolved = resolved.replace(/\{\{input\.([^}]+)\}\}/g, (match, path) => {
+      const value = this.getNestedValue(workflowInput, path.trim());
+      return this.stringifyValue(value, match);
+    });
+
+    // Pattern 2: {{nodeId}} or {{nodeId.path}} (bare nodeId without prefix)
+    resolved = resolved.replace(/\{\{([^:.{}][^}]*?)\}\}/g, (match, path) => {
+      // Skip if it starts with 'nodes.' or 'input.'
+      if (path.trim().startsWith('nodes.') || path.trim().startsWith('input.')) {
+        return match;
+      }
+      // Split into nodeId and optional path
+      const segments = path.trim().split('.');
+      const nodeId = segments[0];
+      const restPath = segments.slice(1).join('.') || undefined;
+      const value = this.resolvePath(nodeId, restPath, previousOutputs);
+      return this.stringifyValue(value, match);
+    });
+
+    // Pattern 3: {{nodes.nodeId}} or {{nodes.nodeId.path}}
+    resolved = resolved.replace(/\{\{nodes\.([^}]+)\}\}/g, (match, path) => {
+      const segments = path.trim().split('.');
+      const nodeId = segments[0];
+      const restPath = segments.slice(1).join('.') || undefined;
+      const value = this.resolvePath(nodeId, restPath, previousOutputs);
+      return this.stringifyValue(value, match);
+    });
+
+    return resolved;
+  }
+
+  /**
+   * Resolve a value from previous outputs.
+   * @param nodeId - The node ID to look up
+   * @param path - Optional dot-notation path within the node output
+   * @param previousOutputs - Map of previous node outputs
+   */
+  private resolvePath(nodeId: string, path: string | undefined, previousOutputs: Map<string, any>): any {
+    // Try exact match first, then try normalized versions (hyphen <-> underscore)
+    let nodeOutput = previousOutputs.get(nodeId);
+    
+    if (nodeOutput === undefined) {
+      // Try normalized versions for flexibility
+      const normalizedUnderscore = nodeId.replace(/-/g, '_');
+      const normalizedHyphen = nodeId.replace(/_/g, '-');
+      
+      if (normalizedUnderscore !== nodeId) {
+        nodeOutput = previousOutputs.get(normalizedUnderscore);
+      }
+      if (nodeOutput === undefined && normalizedHyphen !== nodeId) {
+        nodeOutput = previousOutputs.get(normalizedHyphen);
+      }
+    }
+
+    if (nodeOutput === undefined) {
+      return undefined;
+    }
+
+    // Extract from wrapper formats (DecoratorNode: {success, output} and AgentNode: {result, metadata})
+    let value = this.extractFromWrapper(nodeOutput);
+
+    // If no path specified, return the extracted value
+    if (!path) {
+      return value;
+    }
+
+    // Navigate the path within the node's output
+    // Skip first segment if it's a wrapper property since extractFromWrapper already extracted it
+    // (e.g., template {{node-0.output.value}} -> path="output.value" -> skip "output")
+    let segments = path.split('.');
+    if (segments.length > 1 && 
+        (segments[0] === 'output' || segments[0] === 'result' || segments[0] === 'metadata')) {
+      segments = segments.slice(1);
+    }
+    
+    let current: any = value;
+
+    for (const segment of segments) {
+      if (current === null || current === undefined) {
+        return undefined;
+      }
+      current = current[segment];
+    }
+
+    return current;
+  }
+
+  /**
+   * Extract the actual output value from wrapper formats.
+   * 
+   * Handles:
+   * - AgentNode format: { result, metadata } -> returns result
+   * - DecoratorNode format: { success, output, ... } -> returns output
+   * - Other formats: returns value as-is
+   * 
+   * @param value - The value to extract from
+   * @returns The extracted value
+   */
+  private extractFromWrapper(value: unknown): unknown {
+    if (value === null || value === undefined) {
+      return value;
+    }
+    
+    if (typeof value !== 'object') {
+      return value;
+    }
+    
+    // Check for AgentNode wrapper: { result, metadata }
+    // This is the signature of AgentNode output
+    if ('result' in value && 'metadata' in value) {
+      return (value as { result: unknown }).result;
+    }
+    
+    // Check for DecoratorNode wrapper: { success, output, ... }
+    // This has 'output' but NOT 'result' (that's AgentNode's signature)
+    if ('output' in value) {
+      return (value as { output: unknown }).output;
+    }
+    
+    return value;
+  }
+
+  /**
+   * Get nested value from an object using dot-notation path.
+   * 
+   * Special handling: If the object has an 'input' key and we're looking for a path that doesn't
+   * exist at the top level, check inside the 'input' key.
+   * This allows {{input.city}} to work when workflowInput is wrapped as {input: {city: "..."}}
+   */
+  private getNestedValue(obj: Record<string, unknown> | undefined, path: string): unknown {
+    if (!obj) {
+      return undefined;
+    }
+    
+    // Special case: If obj has an 'input' key, we might be accessing a key inside it
+    // This happens when createExecutionContext wraps globalInput as {input: globalInput}
+    if ('input' in obj && path in (obj['input'] as Record<string, unknown>)) {
+      // Path exists inside 'input', so look there
+      return (obj['input'] as Record<string, unknown>)[path];
+    }
+    
+    // Normal case: path.split('.').reduce(...) with obj as initial value
+    // This allows {{input.city}} to work when path = "city" and obj = {input: {city: "..."}}
+    return path.split('.').reduce((current: unknown, key: string) => {
+      if (current && typeof current === 'object') {
+        return (current as Record<string, unknown>)[key];
+      }
+      return undefined;
+    }, obj as unknown);
+  }
+
+  /**
+   * Convert a value to string for template replacement.
+   * - If value is undefined, return the original template
+   * - If value is a string, return it directly
+   * - If value is null, return 'null'
+   * - If value is an object or array, serialize to JSON
+   * 
+   * @param value - The value to stringify
+   * @param originalTemplate - The original template string (returned if value is undefined)
+   * @returns String representation of the value
+   */
+  private stringifyValue(value: unknown, originalTemplate: string): string {
+    if (value === undefined) {
+      return originalTemplate;
+    }
+    if (value === null) {
+      return 'null';
+    }
+    if (typeof value === 'string') {
+      return value;
+    }
+    // For objects and arrays, serialize to JSON
+    return JSON.stringify(value);
+  }
+}

package/src/env/workflow/nodes/tool-node.test.ts

@@ -0,0 +1,251 @@
+import { describe, it, expect, beforeEach, jest } from 'vitest';
+import { ToolNode, ToolRegistry, Tool } from './tool-node';
+import type { NodeDefinition, NodeExecutionContext } from '../types';
+import type { EventBus } from '../engine/event-bus';
+
+// Mock EventBus
+const mockEventBus = {
+  emit: jest.fn(),
+  on: jest.fn(),
+  off: jest.fn(),
+} as Partial<EventBus> as EventBus;
+
+// Mock ToolRegistry
+const mockRegistry = {
+  getTool: jest.fn<(name: string) => Tool | undefined>(),
+  hasTool: jest.fn<(name: string) => boolean>(),
+} as {
+  getTool: ReturnType<typeof jest.fn>;
+  hasTool: ReturnType<typeof jest.fn>;
+};
+
+// Mock Tool
+const mockTool = {
+  name: 'test-tool',
+  execute: jest.fn<(input: any) => Promise<any>>(),
+};
+
+describe('ToolNode', () => {
+  let toolNode: ToolNode;
+  let nodeDefinition: NodeDefinition;
+  let executionContext: NodeExecutionContext;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    
+    nodeDefinition = {
+      id: 'node-1',
+      type: 'tool',
+      name: 'Test Tool Node',
+      config: {
+        tool: 'test-tool',
+        input: { message: 'hello' },
+      },
+    };
+
+    executionContext = {
+      runId: 'run-1',
+      workflowName: 'test-workflow',
+      nodeId: 'node-1',
+      input: {},
+      previousOutputs: new Map(),
+      config: nodeDefinition.config,
+      debug: false,
+      eventBus: mockEventBus,
+    };
+
+    mockRegistry.getTool = jest.fn().mockReturnValue(mockTool);
+    mockRegistry.hasTool = jest.fn().mockReturnValue(true);
+    mockTool.execute = jest.fn().mockResolvedValue({ result: 'success' });
+  });
+
+  describe('constructor', () => {
+    it('should create a ToolNode with correct type', () => {
+      toolNode = new ToolNode(nodeDefinition, mockRegistry);
+      expect(toolNode.type).toBe('tool');
+      expect(toolNode.id).toBe('node-1');
+    });
+  });
+
+  describe('execute', () => {
+    it('should execute tool successfully', async () => {
+      toolNode = new ToolNode(nodeDefinition, mockRegistry);
+      
+      const result = await toolNode.execute(executionContext);
+      
+      expect(result.output).toEqual({ result: 'success' });
+      expect(result.error).toBeUndefined();
+      expect(result.durationMs).toBeGreaterThanOrEqual(0);
+      expect(mockRegistry.getTool).toHaveBeenCalledWith('test-tool');
+      // Tool is called with (input, context)
+      expect(mockTool.execute).toHaveBeenCalledWith(
+        { message: 'hello' },
+        expect.objectContaining({
+          session_id: expect.any(String),
+        })
+      );
+    });
+
+    it('should return error when tool not found', async () => {
+      mockRegistry.getTool = jest.fn().mockReturnValue(undefined);
+      mockRegistry.hasTool = jest.fn().mockReturnValue(false);
+      
+      toolNode = new ToolNode(nodeDefinition, mockRegistry);
+      
+      const result = await toolNode.execute(executionContext);
+      
+      expect(result.output).toBeUndefined();
+      expect(result.error).toBeDefined();
+      expect(result.error.message).toContain('Tool not found: test-tool');
+    });
+
+    it('should pass input to tool', async () => {
+      const customInput = { param1: 'value1', param2: 123 };
+      nodeDefinition.config.input = customInput;
+      executionContext.config = nodeDefinition.config;
+      
+      toolNode = new ToolNode(nodeDefinition, mockRegistry);
+      
+      await toolNode.execute(executionContext);
+      
+      expect(mockTool.execute).toHaveBeenCalledWith(
+        customInput,
+        expect.objectContaining({
+          session_id: expect.any(String),
+        })
+      );
+    });
+
+    it('should handle tool execution errors', async () => {
+      const error = new Error('Tool execution failed');
+      mockTool.execute = jest.fn().mockRejectedValue(error);
+      
+      toolNode = new ToolNode(nodeDefinition, mockRegistry);
+      
+      const result = await toolNode.execute(executionContext);
+      
+      expect(result.output).toBeUndefined();
+      expect(result.error).toBeDefined();
+      expect(result.error.message).toBe('Tool execution failed');
+    });
+
+    it('should resolve template references from previous outputs', async () => {
+      // Set up previous outputs
+      executionContext.previousOutputs.set('node-0', {
+        value: 'from-node-0'
+      });
+      
+      // Input contains template reference with nodes. prefix
+      nodeDefinition.config.input = {
+        message: '{{nodes.node-0.value}}',
+      };
+      executionContext.config = nodeDefinition.config;
+      
+      toolNode = new ToolNode(nodeDefinition, mockRegistry);
+      
+      const result = await toolNode.execute(executionContext);
+      
+      expect(result.output).toEqual({ result: 'success' });
+      expect(mockTool.execute).toHaveBeenCalledWith({
+        message: 'from-node-0',
+      }, expect.any(Object));
+    });
+
+    it('should resolve nested template references', async () => {
+      executionContext.previousOutputs.set('data-node', {
+        nested: {
+          deep: {
+            value: 'nested-value',
+          }
+        }
+      });
+      
+      nodeDefinition.config.input = {
+        message: '{{nodes.data-node.nested.deep.value}}',
+      };
+      executionContext.config = nodeDefinition.config;
+      
+      toolNode = new ToolNode(nodeDefinition, mockRegistry);
+      
+      await toolNode.execute(executionContext);
+      
+      expect(mockTool.execute).toHaveBeenCalledWith(
+        { message: 'nested-value' },
+        expect.objectContaining({
+          session_id: expect.any(String),
+        })
+      );
+    });
+
+    it('should handle unresolved template references gracefully', async () => {
+      // Template references non-existent node
+      nodeDefinition.config.input = {
+        message: '{{non-existent.output.value}}',
+      };
+      executionContext.config = nodeDefinition.config;
+      
+      toolNode = new ToolNode(nodeDefinition, mockRegistry);
+      
+      const result = await toolNode.execute(executionContext);
+      
+      // Should still execute with unresolved template
+      expect(mockTool.execute).toHaveBeenCalledWith(
+        { message: '{{non-existent.output.value}}' },
+        expect.any(Object)
+      );
+    });
+
+    it('should record execution duration', async () => {
+      mockTool.execute = jest.fn().mockImplementation(async () => {
+        await new Promise(resolve => setTimeout(resolve, 10));
+        return { result: 'success' };
+      });
+      
+      toolNode = new ToolNode(nodeDefinition, mockRegistry);
+      
+      const result = await toolNode.execute(executionContext);
+      
+      expect(result.durationMs).toBeGreaterThanOrEqual(0);
+    });
+
+    it('should use tool name from config.tool', async () => {
+      nodeDefinition.config.tool = 'custom-tool';
+      executionContext.config = nodeDefinition.config;
+      
+      mockRegistry.getTool = jest.fn().mockReturnValue({
+        name: 'custom-tool',
+        execute: jest.fn().mockResolvedValue({ custom: true }),
+      });
+      
+      toolNode = new ToolNode(nodeDefinition, mockRegistry);
+      
+      await toolNode.execute(executionContext);
+      
+      expect(mockRegistry.getTool).toHaveBeenCalledWith('custom-tool');
+    });
+
+    it('should throw error when tool config is missing', async () => {
+      nodeDefinition.config = {};  // No tool specified
+      executionContext.config = nodeDefinition.config;
+      
+      toolNode = new ToolNode(nodeDefinition, mockRegistry);
+      
+      const result = await toolNode.execute(executionContext);
+      
+      expect(result.error).toBeDefined();
+      expect(result.error.message).toContain('Tool name is required');
+    });
+  });
+
+  describe('ToolRegistry interface', () => {
+    it('should check tool existence with hasTool', async () => {
+      mockRegistry.hasTool = jest.fn().mockReturnValue(true);
+      
+      toolNode = new ToolNode(nodeDefinition, mockRegistry);
+      
+      // This is tested implicitly - if hasTool returns false, 
+      // getTool should also return undefined
+      expect(mockRegistry.hasTool('test-tool')).toBe(true);
+    });
+  });
+});