@ai-setting/roy-agent-core 1.0.0

package/src/env/workflow/utils/recovery-validator.ts

@@ -0,0 +1,377 @@
+/**
+ * RecoveryValidator - 分层恢复验证框架
+ * 
+ * 遵循保守策略，严格验证状态完整性
+ */
+
+import { TracedAs } from '../../log-trace/decorator';
+import { WorkflowDefinition } from '../types';
+import { SessionMessage } from '../../session/types';
+import {
+  ValidationError,
+  ValidationResult,
+  RecoveryPlan,
+  ValidationErrorType,
+  SuggestedAction,
+} from './validation-rules';
+import { ExecutionStateBuilder } from './execution-state';
+import type { ExecutionState } from './validation-rules';
+
+/**
+ * RecoveryValidator - 分层恢复验证框架
+ * 
+ * 遵循保守策略，严格验证状态完整性
+ */
+export class RecoveryValidator {
+  private stateBuilder: ExecutionStateBuilder;
+  
+  constructor() {
+    this.stateBuilder = new ExecutionStateBuilder();
+  }
+  
+  @TracedAs("recovery.validator.validate", { recordParams: true, recordResult: true, log: true })
+  async validate(
+    messages: SessionMessage[],
+    definition: WorkflowDefinition
+  ): Promise<ValidationResult> {
+    // 构建执行状态
+    const state = this.stateBuilder.build(messages, definition);
+    
+    const errors: ValidationError[] = [];
+    const warnings: string[] = [];
+    
+    // 1. 状态完整性验证
+    errors.push(...this.validateStateIntegrity(state, definition));
+    
+    // 2. 并行分支验证
+    errors.push(...this.validateParallelBranches(state, definition));
+    
+    // 3. 条件分支验证
+    errors.push(...this.validateConditionBranches(state, definition));
+    
+    // 4. 循环状态验证
+    errors.push(...this.validateLoopState(state, definition));
+    
+    // 5. 嵌套 Workflow 验证
+    errors.push(...this.validateNestedWorkflows(state, definition));
+    
+    return {
+      isValid: errors.length === 0,
+      errors,
+      warnings,
+    };
+  }
+  
+  @TracedAs("recovery.generate.plan", { recordParams: true, recordResult: true, log: true })
+  async generatePlan(
+    messages: SessionMessage[],
+    definition: WorkflowDefinition
+  ): Promise<RecoveryPlan> {
+    const state = this.stateBuilder.build(messages, definition);
+    const validationResult = await this.validate(messages, definition);
+    
+    const pendingNodes = Array.from(state.pendingNodes);
+    const completedNodes = Array.from(state.completedNodes);
+    
+    // 确定恢复点
+    const resumePoint = this.determineResumePoint(state, definition);
+    
+    // 生成摘要
+    const summary = this.generateSummary(state, validationResult);
+    
+    return {
+      canResume: validationResult.isValid,
+      resumePoint,
+      completedNodes,
+      pendingNodes,
+      skippedNodes: [],
+      validationErrors: validationResult.errors,
+      summary,
+    };
+  }
+  
+  // === 私有验证方法 ===
+  
+  @TracedAs("recovery.validator.validateStateIntegrity", { recordParams: true, recordResult: true, log: true })
+  private validateStateIntegrity(
+    state: ExecutionState,
+    definition: WorkflowDefinition
+  ): ValidationError[] {
+    const errors: ValidationError[] = [];
+    
+    // 检查待执行节点的变量依赖
+    for (const nodeId of state.pendingNodes) {
+      const node = definition.nodes?.find(n => n.id === nodeId);
+      if (!node?.config) continue;
+      
+      // 解析输入中的变量引用 {{var}}
+      const variableRefs = this.extractVariableRefs(node.config);
+      
+      for (const varRef of variableRefs) {
+        if (!state.nodeOutputs.has(varRef) && !state.variables.has(varRef)) {
+          errors.push({
+            type: ValidationErrorType.MISSING_VARIABLE,
+            nodeId,
+            description: `变量 ${varRef} 不存在，需要重新运行`,
+            suggestedAction: SuggestedAction.RE_RUN,
+            context: { variable: varRef, nodeConfig: node.config },
+          });
+        }
+      }
+    }
+    
+    return errors;
+  }
+  
+  @TracedAs("recovery.validator.validateParallel", { recordParams: true, recordResult: true, log: true })
+  private validateParallelBranches(
+    state: ExecutionState,
+    definition: WorkflowDefinition
+  ): ValidationError[] {
+    const errors: ValidationError[] = [];
+    
+    // 识别并行分支（同一个 source，多个 target）
+    const parallelGroups = this.identifyParallelGroups(definition);
+    
+    for (const group of parallelGroups) {
+      const completedInGroup = group.filter(id => state.completedNodes.has(id));
+      const inProgressInGroup = group.filter(id => state.inProgressNodes.has(id));
+      
+      // 如果有节点正在执行或未完成
+      if (inProgressInGroup.length > 0 || completedInGroup.length < group.length) {
+        // 检查合并节点是否应该等待
+        const mergeNode = this.findMergeNodeForParallel(group, definition);
+        
+        if (mergeNode && !state.completedNodes.has(mergeNode)) {
+          const incomplete = group.filter(id => !state.completedNodes.has(id));
+          errors.push({
+            type: ValidationErrorType.INCOMPLETE_PARALLEL,
+            nodeId: mergeNode,
+            description: `并行分支 ${incomplete.join(', ')} 未完成`,
+            suggestedAction: SuggestedAction.RE_RUN,
+            context: { incompleteBranches: incomplete, mergeNode },
+          });
+        }
+      }
+    }
+    
+    return errors;
+  }
+  
+  @TracedAs("recovery.validator.validateCondition", { recordParams: true, recordResult: true, log: true })
+  private validateConditionBranches(
+    state: ExecutionState,
+    definition: WorkflowDefinition
+  ): ValidationError[] {
+    const errors: ValidationError[] = [];
+    
+    // 查找有条件边的节点
+    const edges = (definition as any).edges || (definition as any).connections || [];
+    const conditionalEdges = edges.filter((e: any) => e.condition);
+    
+    for (const edge of conditionalEdges) {
+      // 检查条件表达式中的变量是否存在
+      const conditionVars = this.extractVariableRefs(edge.condition);
+      
+      for (const varRef of conditionVars) {
+        if (!state.nodeOutputs.has(varRef) && !state.variables.has(varRef)) {
+          errors.push({
+            type: ValidationErrorType.AMBIGUOUS_BRANCH,
+            nodeId: edge.target || edge.to,
+            description: `条件分支无法确定：变量 ${varRef} 不存在`,
+            suggestedAction: SuggestedAction.CONFIRM,
+            context: { variable: varRef, condition: edge.condition },
+          });
+        }
+      }
+    }
+    
+    return errors;
+  }
+  
+  @TracedAs("recovery.validator.validateLoop", { recordParams: true, recordResult: true, log: true })
+  private validateLoopState(
+    state: ExecutionState,
+    definition: WorkflowDefinition
+  ): ValidationError[] {
+    const errors: ValidationError[] = [];
+    
+    // 识别循环结构（回边）
+    const loops = this.identifyLoops(definition);
+    
+    for (const loop of loops) {
+      // 检查循环计数器是否保持
+      const loopCounter = `loop_count_${loop.header}`;
+      
+      if (!state.nodeOutputs.has(loopCounter) && state.pendingNodes.has(loop.header)) {
+        errors.push({
+          type: ValidationErrorType.LOOP_STATE_LOST,
+          nodeId: loop.header,
+          description: `循环状态丢失，循环计数器 ${loopCounter} 不存在`,
+          suggestedAction: SuggestedAction.RE_RUN,
+          context: { loopHeader: loop.header },
+        });
+      }
+    }
+    
+    return errors;
+  }
+  
+  @TracedAs("recovery.validator.validateNested", { recordParams: true, recordResult: true, log: true })
+  private validateNestedWorkflows(
+    state: ExecutionState,
+    definition: WorkflowDefinition
+  ): ValidationError[] {
+    const errors: ValidationError[] = [];
+    
+    // 查找 workflow 节点
+    const workflowNodes = (definition.nodes || []).filter(n => n.type === 'workflow');
+    
+    for (const node of workflowNodes) {
+      const nodeOutput = state.nodeOutputs.get(node.id) as Record<string, unknown> | undefined;
+      const subSessionId = nodeOutput?.sessionId as string | undefined;
+      
+      if (subSessionId && state.pendingNodes.has(node.id)) {
+        // TODO: 检查子 session 状态 - 需要集成 SessionComponent
+        // This requires integration with SessionComponent to check sub-session status
+      }
+    }
+    
+    return errors;
+  }
+  
+  // === 辅助方法 ===
+  
+  private extractVariableRefs(obj: unknown): string[] {
+    const refs: string[] = [];
+    if (!obj) return refs;
+    
+    const str = JSON.stringify(obj);
+    const regex = /\{\{([^}]+)\}\}/g;
+    let match;
+    while ((match = regex.exec(str)) !== null) {
+      refs.push(match[1].trim());
+    }
+    return refs;
+  }
+  
+  private identifyParallelGroups(definition: WorkflowDefinition): string[][] {
+    // 识别并行分支
+    const groups: string[][] = [];
+    const sources = new Map<string, string[]>();
+    
+    const edges = (definition as any).edges || (definition as any).connections || [];
+    
+    for (const edge of edges) {
+      const source = edge.source || edge.from;
+      const target = edge.target || edge.to;
+      const targets = sources.get(source) || [];
+      targets.push(target);
+      sources.set(source, targets);
+    }
+    
+    for (const [_source, targets] of sources) {
+      if (targets.length > 1) {
+        groups.push(targets);
+      }
+    }
+    
+    return groups;
+  }
+  
+  private findMergeNodeForParallel(parallelIds: string[], definition: WorkflowDefinition): string | null {
+    // 找到汇聚节点
+    const edges = (definition as any).edges || (definition as any).connections || [];
+    
+    for (const edge of edges) {
+      const target = edge.target || edge.to;
+      const source = edge.source || edge.from;
+      const allSourcesFromParallel = parallelIds.includes(source);
+      const hasIncomingFromParallel = parallelIds.some(id => 
+        edges.some((e: any) => (e.source || e.from) === id && (e.target || e.to) === target)
+      );
+      
+      if (allSourcesFromParallel && hasIncomingFromParallel) {
+        return target;
+      }
+    }
+    
+    return null;
+  }
+  
+  private identifyLoops(definition: WorkflowDefinition): { header: string; body: string[] }[] {
+    // 简化实现：查找回边
+    const loops: { header: string; body: string[] }[] = [];
+    const visited = new Set<string>();
+    const recStack = new Set<string>();
+    
+    const edges = (definition as any).edges || (definition as any).connections || [];
+    
+    const getChildren = (nodeId: string): string[] => {
+      return edges
+        .filter((e: any) => (e.source || e.from) === nodeId)
+        .map((e: any) => e.target || e.to);
+    };
+    
+    const dfs = (nodeId: string, path: string[]): void => {
+      visited.add(nodeId);
+      recStack.add(nodeId);
+      
+      const outgoing = getChildren(nodeId);
+      for (const childId of outgoing) {
+        if (!visited.has(childId)) {
+          dfs(childId, [...path, childId]);
+        } else if (recStack.has(childId)) {
+          // 发现回边
+          const loopStart = path.indexOf(childId);
+          if (loopStart !== -1) {
+            loops.push({
+              header: childId,
+              body: path.slice(loopStart),
+            });
+          }
+        }
+      }
+      
+      recStack.delete(nodeId);
+    };
+    
+    for (const node of definition.nodes || []) {
+      if (!visited.has(node.id)) {
+        dfs(node.id, [node.id]);
+      }
+    }
+    
+    return loops;
+  }
+  
+  private determineResumePoint(state: ExecutionState, definition: WorkflowDefinition): string {
+    // 优先从中断节点恢复
+    const inProgress = Array.from(state.inProgressNodes);
+    if (inProgress.length > 0) {
+      return inProgress[0];
+    }
+    
+    // 否则从第一个待执行节点恢复
+    const pending = Array.from(state.pendingNodes);
+    if (pending.length > 0) {
+      return pending[0];
+    }
+    
+    // 返回 entry
+    const entry = definition.entry;
+    if (Array.isArray(entry)) {
+      return entry[0] || '';
+    }
+    return entry || '';
+  }
+  
+  private generateSummary(state: ExecutionState, result: ValidationResult): string {
+    if (result.isValid) {
+      return `恢复验证通过。已完成 ${state.completedNodes.size} 个节点，待执行 ${state.pendingNodes.size} 个节点。`;
+    }
+    
+    const errorTypes = result.errors.map(e => e.type).join(', ');
+    return `恢复验证失败：${errorTypes}。${result.errors.length} 个错误需要处理。`;
+  }
+}

package/src/env/workflow/utils/session-parser.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from 'bun:test';
+import {
+  findLastInterruptMessage,
+  parseNodeOutputs,
+  getNextPendingNode,
+  getAgentSessionIdFromInterrupt,
+  isWaitingForUser,
+} from './session-parser';
+import type { SessionMessage } from '../../session/types';
+
+describe('session-parser', () => {
+  const createMessage = (metadata: any, content = '{}'): SessionMessage => ({
+    id: `msg_${Math.random()}`,
+    sessionID: 'workflow_test',
+    role: 'user' as any,
+    content,
+    timestamp: Date.now(),
+    metadata,
+  });
+  
+  describe('findLastInterruptMessage', () => {
+    it('should return last interrupt message', () => {
+      const messages: SessionMessage[] = [
+        createMessage({ type: 'workflow.node.call', workflowNodeId: 'n1' }),
+        createMessage({ type: 'workflow.node.result', workflowNodeId: 'n1' }),
+        createMessage({ type: 'workflow.node.call', workflowNodeId: 'n2' }),
+        createMessage({ type: 'workflow.node.interrupt', workflowNodeId: 'n2', query: 'Q1' }),
+        createMessage({ type: 'workflow.node.call', workflowNodeId: 'n3' }),
+        createMessage({ type: 'workflow.node.interrupt', workflowNodeId: 'n3', query: 'Q2' }),
+      ];
+      
+      const result = findLastInterruptMessage(messages);
+      expect(result?.metadata?.workflowNodeId).toBe('n3');
+    });
+    
+    it('should return null if no interrupt', () => {
+      const messages: SessionMessage[] = [
+        createMessage({ type: 'workflow.node.call', workflowNodeId: 'n1' }),
+        createMessage({ type: 'workflow.node.result', workflowNodeId: 'n1' }),
+      ];
+      
+      expect(findLastInterruptMessage(messages)).toBeNull();
+    });
+  });
+  
+  describe('parseNodeOutputs', () => {
+    it('should parse all node outputs', () => {
+      const messages: SessionMessage[] = [
+        createMessage({ type: 'workflow.node.call', workflowNodeId: 'n1' }),
+        createMessage({ type: 'workflow.node.result', workflowNodeId: 'n1' }, '{"result":"output1"}'),
+        createMessage({ type: 'workflow.node.call', workflowNodeId: 'n2' }),
+        createMessage({ type: 'workflow.node.result', workflowNodeId: 'n2' }, '{"result":"output2"}'),
+      ];
+      
+      const outputs = parseNodeOutputs(messages);
+      expect(outputs.get('n1')).toEqual({ result: 'output1' });
+      expect(outputs.get('n2')).toEqual({ result: 'output2' });
+    });
+  });
+  
+  describe('getNextPendingNode', () => {
+    it('should return last incomplete node', () => {
+      const messages: SessionMessage[] = [
+        createMessage({ type: 'workflow.node.call', workflowNodeId: 'n1' }),
+        createMessage({ type: 'workflow.node.result', workflowNodeId: 'n1' }, '{"o":"1"}'),
+        createMessage({ type: 'workflow.node.call', workflowNodeId: 'n2' }),
+        // n2 没有 result，所以是 pending
+      ];
+      
+      expect(getNextPendingNode(messages)).toBe('n2');
+    });
+  });
+  
+  describe('getAgentSessionIdFromInterrupt', () => {
+    it('should return agentSessionId from interrupt', () => {
+      const msg = createMessage({
+        type: 'workflow.node.interrupt',
+        workflowNodeId: 'n1',
+        agentSessionId: 'agent_123',
+      });
+      
+      expect(getAgentSessionIdFromInterrupt(msg)).toBe('agent_123');
+    });
+    
+    it('should return undefined if not interrupt', () => {
+      const msg = createMessage({ type: 'workflow.node.call' });
+      expect(getAgentSessionIdFromInterrupt(msg)).toBeUndefined();
+    });
+  });
+  
+  describe('isWaitingForUser', () => {
+    it('should return true if interrupt without resume', () => {
+      const messages: SessionMessage[] = [
+        createMessage({ type: 'workflow.node.call', workflowNodeId: 'n1' }),
+        createMessage({ type: 'workflow.node.interrupt', workflowNodeId: 'n1' }),
+      ];
+      
+      expect(isWaitingForUser(messages)).toBe(true);
+    });
+    
+    it('should return false if resume exists', () => {
+      const messages: SessionMessage[] = [
+        createMessage({ type: 'workflow.node.call', workflowNodeId: 'n1' }),
+        createMessage({ type: 'workflow.node.interrupt', workflowNodeId: 'n1' }),
+        createMessage({ type: 'workflow.node.resume' }),
+      ];
+      
+      expect(isWaitingForUser(messages)).toBe(false);
+    });
+  });
+});

package/src/env/workflow/utils/session-parser.ts

@@ -0,0 +1,94 @@
+import type { SessionMessage } from '../../session/types';
+import type { 
+  WorkflowNodeCallMetadata, 
+  WorkflowNodeInterruptMetadata,
+} from '../types/workflow-message';
+
+/**
+ * 查找最后一个 workflow.node.interrupt 消息
+ */
+export function findLastInterruptMessage(
+  messages: SessionMessage[]
+): SessionMessage | null {
+  const interrupts = messages.filter(
+    m => (m.metadata as any)?.type === 'workflow.node.interrupt'
+  );
+  return interrupts[interrupts.length - 1] || null;
+}
+
+/**
+ * 解析节点输出
+ */
+export function parseNodeOutputs(
+  messages: SessionMessage[]
+): Map<string, unknown> {
+  const outputs = new Map<string, unknown>();
+  let lastCallNodeId: string | null = null;
+  
+  for (const msg of messages) {
+    if ((msg.metadata as any)?.type === 'workflow.node.call') {
+      const metadata = msg.metadata as unknown as WorkflowNodeCallMetadata;
+      lastCallNodeId = metadata.workflowNodeId;
+    } else if ((msg.metadata as any)?.type === 'workflow.node.result') {
+      if (lastCallNodeId) {
+        try {
+          outputs.set(lastCallNodeId, JSON.parse(msg.content));
+        } catch {
+          outputs.set(lastCallNodeId, msg.content);
+        }
+      }
+      lastCallNodeId = null;
+    }
+  }
+  
+  return outputs;
+}
+
+/**
+ * 获取下一个待执行的节点
+ */
+export function getNextPendingNode(
+  messages: SessionMessage[]
+): string | null {
+  const outputs = parseNodeOutputs(messages);
+  const completedNodes = new Set(outputs.keys());
+  
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if ((msg.metadata as any)?.type === 'workflow.node.call') {
+      const metadata = msg.metadata as unknown as WorkflowNodeCallMetadata;
+      const nodeId = metadata.workflowNodeId;
+      if (!completedNodes.has(nodeId)) {
+        return nodeId;
+      }
+    }
+  }
+  
+  return null;
+}
+
+/**
+ * 从 interrupt 消息获取 agentSessionId
+ */
+export function getAgentSessionIdFromInterrupt(
+  interruptMessage: SessionMessage
+): string | undefined {
+  if ((interruptMessage.metadata as any)?.type === 'workflow.node.interrupt') {
+    const metadata = interruptMessage.metadata as unknown as WorkflowNodeInterruptMetadata;
+    return metadata.agentSessionId;
+  }
+  return undefined;
+}
+
+/**
+ * 检查 session 是否在等待用户
+ */
+export function isWaitingForUser(messages: SessionMessage[]): boolean {
+  const lastInterrupt = findLastInterruptMessage(messages);
+  if (!lastInterrupt) return false;
+  
+  const interruptIndex = messages.indexOf(lastInterrupt);
+  const afterInterrupt = messages.slice(interruptIndex + 1);
+  
+  return !afterInterrupt.some(m => (m.metadata as any)?.type === 'workflow.node.resume');
+}