@ai-setting/roy-agent-cli 1.3.15 → 1.3.17

package/dist/core/src/env/workflow/engine/engine.d.ts

@@ -0,0 +1,218 @@
+/**
+ * @fileoverview WorkflowEngine - Session-based workflow execution engine
+ *
+ * 基于 Session 实现 run/resume 机制：
+ * - Session 直接作为 workflow run 的实例
+ * - 使用 workflow.node.* 消息记录节点执行状态
+ * - resume 时从 Session 消息恢复状态
+ *
+ * @version v2.0
+ */
+import { EventEmitter } from 'events';
+import type { WorkflowDefinition, Workflow, RunOptions, RunResult, RunStatus } from '../types/index';
+import { NodeRegistry } from './node-registry';
+import type { SessionComponent } from '../../session/session-component';
+/**
+ * Agent Session Recovery Info
+ */
+export interface AgentSessionRecoveryInfo {
+    nodeId: string;
+    agentSessionId: string;
+}
+/**
+ * Options for creating WorkflowEngine via static factory
+ */
+export interface WorkflowEngineCreateOptions {
+    env?: {
+        getComponent<T>(name: string): T | undefined;
+    };
+    toolRegistry?: any;
+    skillRegistry?: any;
+    workflowRunner?: any;
+    sessionComponent?: SessionComponent;
+    /** Repository for loading workflow definitions during resume */
+    workflowRepository?: WorkflowRepository;
+}
+/**
+ * Workflow Repository interface (abstraction)
+ */
+export interface WorkflowRepository {
+    getById(id: string): Workflow | null;
+    getByName(name: string): Workflow | null;
+}
+/**
+ * WorkflowEngine Configuration
+ */
+export interface WorkflowEngineConfig {
+    parallelLimit: number | null;
+    timeout: number | null;
+    debug: boolean;
+}
+/**
+ * WorkflowEngine
+ *
+ * Session-based workflow execution engine.
+ * Uses Session to manage workflow run state and node execution history.
+ */
+export declare class WorkflowEngine extends EventEmitter {
+    /** 活跃的 session 状态，key 为 sessionId */
+    private activeSessions;
+    /** Session ID 计数器 */
+    private sessionIdCounter;
+    /** Session component */
+    private sessionComponent?;
+    /** Node registry */
+    private nodeRegistry;
+    /** Workflow repository for loading definitions during resume */
+    private workflowRepository?;
+    /**
+     * Create a new WorkflowEngine
+     */
+    constructor(nodeRegistry: NodeRegistry, sessionComponent?: SessionComponent, workflowRepository?: WorkflowRepository);
+    /**
+     * Create a WorkflowEngine with automatic AgentComponent integration
+     */
+    static create(options: WorkflowEngineCreateOptions): Promise<WorkflowEngine>;
+    /**
+     * Generate a unique run ID
+     */
+    private generateRunId;
+    /**
+     * Extract runId from sessionId
+     * sessionId format: workflow_{runId}
+     */
+    private getRunIdFromSessionId;
+    /**
+     * Get session ID for a run
+     */
+    getSessionId(runId: string): string;
+    /**
+     * Create a new workflow session
+     *
+     * @param workflow - Workflow definition or entity
+     * @param options - Optional configuration
+     * @returns Promise resolving to sessionId (format: workflow_{runId})
+     */
+    createSession(workflow: Workflow | WorkflowDefinition, options?: RunOptions): Promise<string>;
+    /**
+     * Run a workflow by sessionId (unified entry point)
+     *
+     * This method supports both:
+     * 1. First run: session doesn't exist → create session, start from entry node
+     * 2. Resume: session exists with messages → infer next node from messages
+     *
+     * @param sessionId - Session ID (format: workflow_{runId} or any string)
+     * @param options - Optional configuration
+     * @returns Promise resolving to RunResult
+     */
+    run(sessionId: string, options?: RunOptions & {
+        workflowId?: string;
+    }): Promise<RunResult>;
+    /**
+     * Initialize session state
+     */
+    private initializeSessionState;
+    /**
+     * Run with resume point
+     */
+    private runWithResume;
+    /**
+     * Convenience method to run a workflow directly
+     */
+    runWorkflow(workflow: Workflow | WorkflowDefinition, options?: RunOptions): Promise<RunResult>;
+    /**
+     * Pause a running workflow
+     */
+    pause(sessionId: string): Promise<void>;
+    /**
+     * Resume a paused workflow
+     */
+    resume(sessionId: string, options?: {
+        response?: string;
+    }): Promise<RunResult>;
+    /**
+     * Resume from database when CLI restarts
+     */
+    private resumeFromDatabase;
+    /**
+     * Restore runtime state from Session messages
+     */
+    private restoreRuntimeState;
+    /**
+     * Write node resume message
+     */
+    private writeNodeResume;
+    /**
+     * Stop a running or paused workflow
+     */
+    stop(sessionId: string, reason?: string): Promise<void>;
+    /**
+     * Get session status
+     */
+    getSessionStatus(sessionId: string): RunStatus | null;
+    /**
+     * Check if session is active
+     */
+    isSessionActive(sessionId: string): boolean;
+    /**
+     * Setup event handlers for a run
+     */
+    private setupEventHandlers;
+    /**
+     * Write node interrupt message
+     */
+    private writeNodeInterrupt;
+    /**
+     * Main scheduling loop
+     */
+    private scheduleAndExecute;
+    /**
+     * Wait for next node event
+     */
+    private waitForNextNodeEvent;
+    /**
+     * Start execution of a single node
+     */
+    private startNode;
+    /**
+     * Write node call message
+     */
+    private writeNodeCall;
+    /**
+     * Resume execution of a paused node
+     */
+    private resumeNode;
+    /**
+     * Create execution context for a node
+     */
+    private createExecutionContext;
+    /**
+     * Check if workflow is complete and finalize
+     */
+    private checkAndFinalize;
+    /**
+     * Complete a workflow successfully
+     */
+    private completeWorkflow;
+    /**
+     * Fail a workflow
+     */
+    private failWorkflow;
+    /**
+     * Cleanup session resources
+     */
+    private cleanupSession;
+    /**
+     * Wait for a run to complete
+     */
+    private waitForCompletion;
+    /**
+     * Get session metadata
+     */
+    private getSessionMetadata;
+    /**
+     * Find workflow definition from repository
+     */
+    private findDefinitionForWorkflow;
+}
+//# sourceMappingURL=engine.d.ts.map