@ai-setting/roy-agent-core 1.7.52 → 1.7.55

package/dist/env/workflow/engine/node-registry.d.ts

@@ -0,0 +1,159 @@
+/**
+ * @fileoverview NodeRegistry - Registry for creating Node instances
+ *
+ * NodeRegistry manages node creation from NodeDefinition instances.
+ * It provides:
+ * - Built-in node types: tool, skill, agent, workflow
+ * - Custom node type registration via factory functions
+ * - Node creation based on node type
+ */
+import type { Node, NodeDefinition } from '../types/index';
+import { EventBus } from './event-bus';
+import type { ToolRegistry } from '../nodes/tool-node';
+import type { SkillRegistry } from '../nodes/skill-node';
+import type { AgentRunner } from '../nodes/agent-node';
+import { AgentComponentAdapter } from '../nodes/agent-component-adapter';
+import type { WorkflowRunner } from '../nodes/workflow-node';
+import type { AgentComponent } from '../../agent/agent-component';
+import type { SessionComponent } from '../../session/session-component';
+/**
+ * NodeRegistry initialization options
+ */
+export interface NodeRegistryOptions {
+    /** Registry for looking up tools */
+    toolRegistry?: ToolRegistry;
+    /** Registry for looking up skills */
+    skillRegistry?: SkillRegistry;
+    /** AgentComponent for executing agent nodes (auto-creates adapter) */
+    agentComponent?: AgentComponent;
+    /** Explicit AgentRunner (takes precedence over agentComponent) */
+    agentRunner?: AgentRunner;
+    /** Runner for executing workflow nodes */
+    workflowRunner?: WorkflowRunner;
+    /** Session component for agent session management */
+    sessionComponent?: SessionComponent;
+    /** @deprecated Use agentRunner instead */
+    agentRunner2?: AgentRunner;
+}
+/**
+ * NodeContext for node creation
+ *
+ * Context information passed to node factories when creating nodes.
+ */
+export interface NodeContext {
+    /** Run ID for this workflow execution */
+    runId: string;
+    /** Workflow name */
+    workflowName: string;
+    /** Event bus for workflow events */
+    eventBus: EventBus;
+    /** Debug mode flag */
+    debug: boolean;
+}
+/**
+ * NodeFactory function type
+ *
+ * Factory function that creates a Node instance from a NodeDefinition.
+ */
+export type NodeFactory = (definition: NodeDefinition, context: NodeContext) => Node;
+/**
+ * NodeRegistry
+ *
+ * Registry for creating Node instances from NodeDefinition.
+ *
+ * Features:
+ * - Built-in node types: tool, skill, agent, workflow
+ * - Custom node type registration via factory functions
+ * - Node creation based on node type
+ *
+ * @example
+ * ```typescript
+ * const registry = new NodeRegistry(
+ *   toolRegistry,
+ *   skillRegistry,
+ *   agentRunner,
+ *   workflowRunner
+ * );
+ *
+ * // Register custom node type
+ * registry.register('custom', (definition, context) => {
+ *   return new CustomNode(definition);
+ * });
+ *
+ * // Create node from definition
+ * const node = registry.createNode(definition);
+ * ```
+ */
+export declare class NodeRegistry {
+    /** Map of registered node factories by type */
+    private factories;
+    /** Tool registry for looking up tools */
+    private toolRegistry?;
+    /** Skill registry for looking up skills */
+    private skillRegistry?;
+    /** Agent runner for executing agent nodes */
+    private agentRunner?;
+    /** Workflow runner for executing workflow nodes */
+    private workflowRunner?;
+    /** AgentComponent adapter (auto-created if agentComponent is provided) */
+    private agentComponentAdapter?;
+    /** Session component for agent session management */
+    private sessionComponent?;
+    /**
+     * Create a new NodeRegistry
+     *
+     * @param options - Registry options
+     * @param options.toolRegistry - Registry for looking up tools (optional)
+     * @param options.skillRegistry - Registry for looking up skills (optional)
+     * @param options.agentComponent - AgentComponent for executing agent nodes (optional, auto-creates adapter)
+     * @param options.agentRunner - Explicit AgentRunner (takes precedence over agentComponent)
+     * @param options.workflowRunner - Runner for executing workflow nodes (optional)
+     * @param options.sessionComponent - Session component for agent session management (optional)
+     */
+    constructor(options?: NodeRegistryOptions);
+    /**
+     * Get the AgentComponentAdapter if available
+     */
+    getAgentAdapter(): AgentComponentAdapter | undefined;
+    /**
+     * Get the AgentRunner
+     */
+    getAgentRunner(): AgentRunner | undefined;
+    /**
+     * Get the SessionComponent
+     */
+    getSessionComponent(): SessionComponent | undefined;
+    /**
+     * Register built-in node types
+     */
+    private registerBuiltInTypes;
+    /**
+     * Register a custom node factory
+     *
+     * @param type - Node type identifier
+     * @param factory - Factory function to create nodes of this type
+     */
+    register(type: string, factory: NodeFactory): void;
+    /**
+     * Check if a node type is registered
+     *
+     * @param type - Node type identifier
+     * @returns True if the type is registered
+     */
+    has(type: string): boolean;
+    /**
+     * List all registered node types
+     *
+     * @returns Array of registered type names
+     */
+    list(): string[];
+    /**
+     * Create a Node instance from a NodeDefinition
+     *
+     * @param definition - Node definition
+     * @param context - Node context (optional, for future use)
+     * @returns Node instance
+     * @throws Error if the node type is not registered
+     */
+    createNode(definition: NodeDefinition, context?: NodeContext): Node;
+}

package/dist/env/workflow/engine/scheduler.d.ts

@@ -0,0 +1,164 @@
+import { DAGManager } from './dag-manager';
+import type { EdgeDefinition, EdgeProcessingResult } from '../types/edge';
+import { TemplateResolver } from '../utils/template-resolver';
+/**
+ * Scheduler Options
+ */
+export interface SchedulerOptions {
+    /** Maximum number of nodes that can run in parallel. null = unlimited */
+    parallelLimit: number | null;
+}
+/**
+ * Scheduler State
+ */
+export interface SchedulerState {
+    /** Nodes that have not been started yet */
+    pending: string[];
+    /** Nodes that are ready to execute (dependencies met, not started) */
+    ready: string[];
+    /** Nodes that are currently running */
+    running: string[];
+    /** Nodes that have completed successfully */
+    completed: string[];
+    /** Nodes that have failed */
+    failed: string[];
+    /** Nodes that were skipped (not executed) */
+    skipped: string[];
+}
+/**
+ * Scheduler
+ *
+ * Determines which nodes are ready to execute based on:
+ * - DAG dependencies
+ * - Parallel execution limit
+ * - Node completion status
+ *
+ * The scheduler tracks the state of all nodes and manages the execution queue.
+ */
+export declare class Scheduler {
+    private dagManager;
+    private options;
+    private pending;
+    private ready;
+    private running;
+    private completed;
+    private failed;
+    private skipped;
+    /**
+     * Create a new Scheduler
+     * @param dagManager - The DAG manager for the workflow
+     * @param options - Scheduler options
+     */
+    constructor(dagManager: DAGManager, options?: Partial<SchedulerOptions>);
+    /**
+     * Get nodes that are ready to execute
+     * Ready nodes are those whose dependencies are met and are not already running/completed/failed
+     * @param completedNodes - Set of completed node IDs (external tracking)
+     */
+    getReadyNodes(completedNodes: Set<string>): string[];
+    /**
+     * Get the number of currently running nodes
+     */
+    getRunningCount(): number;
+    /**
+     * Check if more nodes can be started based on the parallel limit
+     */
+    canStartMore(): boolean;
+    /**
+     * Mark a node as started
+     * @param nodeId - The node ID
+     */
+    markStarted(nodeId: string): void;
+    /**
+     * Check if a node is currently running
+     * @param nodeId - The node ID
+     */
+    isRunning(nodeId: string): boolean;
+    /**
+     * Check if a node has completed
+     * @param nodeId - The node ID
+     */
+    isCompleted(nodeId: string): boolean;
+    /**
+     * Check if a node has failed
+     * @param nodeId - The node ID
+     */
+    isFailed(nodeId: string): boolean;
+    /**
+     * Check if a node is in pending state
+     * @param nodeId - The node ID
+     */
+    isPending(nodeId: string): boolean;
+    /**
+     * Check if a node is ready to execute
+     * @param nodeId - The node ID
+     */
+    isReady(nodeId: string): boolean;
+    /**
+     * Mark a node as completed successfully
+     * @param nodeId - The node ID (or '__end__' to mark workflow as completed)
+     */
+    markCompleted(nodeId: string): void;
+    /**
+     * Mark a node as failed
+     * @param nodeId - The node ID
+     */
+    markFailed(nodeId: string): void;
+    /**
+     * Mark a node as skipped (not executed)
+     * @param nodeId - The node ID
+     */
+    markSkipped(nodeId: string): void;
+    /**
+     * Clear skipped state so a node can be scheduled again
+     */
+    unmarkSkipped(nodeId: string): void;
+    /**
+     * Reset a node so it can be re-executed (loop / back-edge re-entry)
+     */
+    resetNodeForReEntry(nodeId: string): void;
+    /**
+     * Reset the scheduler state
+     * Clears all running, completed, failed, and skipped nodes
+     */
+    reset(): void;
+    /**
+     * Get the current state of the scheduler
+     */
+    getState(): SchedulerState;
+    /**
+     * Mark multiple nodes as completed from restored state
+     * Used during workflow resume to prevent re-executing completed nodes
+     * @param nodeIds - Array of node IDs that were completed
+     */
+    markCompletedFromRestore(nodeIds: string[]): void;
+    /**
+     * Update the ready set based on completed nodes
+     */
+    private updateReadyNodes;
+    /**
+     * Get the parallel limit
+     */
+    getParallelLimit(): number | null;
+    /**
+     * Update the parallel limit
+     * @param limit - New parallel limit (null for unlimited)
+     */
+    setParallelLimit(limit: number | null): void;
+    /**
+     * Get outgoing edges from a node
+     * @param nodeId - Source node ID
+     * @param edges - Array of edge definitions
+     * @returns Array of outgoing edges
+     */
+    getOutgoingEdges(nodeId: string, edges: EdgeDefinition[]): EdgeDefinition[];
+    /**
+     * Evaluate and process edges after a node completes
+     * @param completedNodeId - The node that just completed
+     * @param edges - Array of edge definitions
+     * @param templateResolver - Template resolver for condition evaluation
+     * @param loopEnabled - Whether to allow re-entry of completed nodes (for loop/cycle support)
+     * @returns Array of nodes that should be started
+     */
+    processEdgesAfterCompletion(completedNodeId: string, edges: EdgeDefinition[], templateResolver: TemplateResolver, loopEnabled?: boolean): EdgeProcessingResult;
+}

package/dist/env/workflow/extractor/workflow-converter.d.ts

@@ -0,0 +1,55 @@
+/**
+ * WorkflowConverter - 将装饰器类转换为 WorkflowDefinition
+ */
+import 'reflect-metadata';
+import type { WorkflowMetadata, NodeMetadata, EdgeMetadata, ValidationResult, ConvertedWorkflowDefinition, ConvertedNodeDefinition } from '../types/decorators-types';
+/**
+ * Workflow 转换器
+ *
+ * 负责将使用装饰器定义的类转换为标准的 WorkflowDefinition
+ */
+export declare class WorkflowConverter {
+    /**
+     * 从装饰器类提取 Workflow 元数据
+     */
+    static extractWorkflowMetadata(targetClass: Function): WorkflowMetadata | undefined;
+    /**
+     * 从装饰器类提取所有 Node 元数据
+     */
+    static extractNodeMetadatas(targetClass: Function): NodeMetadata[];
+    /**
+     * 从装饰器类提取所有 Edge 元数据
+     */
+    static extractEdgeMetadatas(targetClass: Function): EdgeMetadata[];
+    /**
+     * 将装饰器类转换为 WorkflowDefinition
+     */
+    static fromClass(targetClass: new (...args: any[]) => any, instance: any): ConvertedWorkflowDefinition;
+    /**
+     * 构建节点映射，并合并边依赖
+     */
+    private static buildNodeMap;
+    /**
+     * 验证装饰器类的有效性
+     */
+    static validateWorkflowClass(targetClass: Function): ValidationResult;
+    /**
+     * 检测是否存在循环依赖
+     *
+     * dependsOn 语义：A 依赖 B 表示 A.dependsOn = [B]
+     * 这意味着 B 执行完成后才能执行 A，所以边是 B → A
+     *
+     * 检测方法：构建反向邻接表（谁依赖我），然后 DFS 检测环
+     */
+    private static hasCycle;
+    /**
+     * 执行装饰器方法（用于 WorkflowEngine 调用）
+     */
+    static executeNode(nodeDef: ConvertedNodeDefinition, context: {
+        input: any;
+        previousOutputs: Map<string, any>;
+    }): Promise<{
+        output: any;
+        error?: Error;
+    }>;
+}