@ai-setting/roy-agent-core 1.0.0

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

@@ -0,0 +1,334 @@
+import { describe, it, expect } from 'vitest';
+import { 
+  inferNextNode,
+  findLastInterruptMessage,
+  findLastCallMessage,
+  parseNodeOutputs,
+  type ResumePoint,
+} from './session-recovery';
+
+// Mock SessionMessage type
+interface MockMessage {
+  role: string;
+  content: string;
+  metadata: Record<string, unknown>;
+}
+
+function createMessage(role: string, content: string, metadata: Record<string, unknown>): MockMessage {
+  return { role, content, metadata };
+}
+
+describe('inferNextNode', () => {
+  describe('when no messages', () => {
+    it('should return entry node from definition', () => {
+      const messages: MockMessage[] = [];
+      const definition = {
+        entryNode: 'node_A',
+        nodes: { node_A: { id: 'node_A' } },
+      };
+      
+      const result = inferNextNode(messages as any, definition);
+      
+      expect(result.type).toBe('entry_node');
+      expect(result.nodeId).toBe('node_A');
+    });
+    
+    it('should handle missing entryNode', () => {
+      const messages: MockMessage[] = [];
+      const definition = {};
+      
+      const result = inferNextNode(messages as any, definition);
+      
+      expect(result.type).toBe('entry_node');
+      expect(result.nodeId).toBeUndefined();
+    });
+  });
+  
+  describe('when last message is workflow.node.call', () => {
+    it('should return resume_node type with nodeId', () => {
+      const messages = [
+        createMessage('workflow.node.call', '{}', {
+          type: 'workflow.node.call',
+          workflowNodeId: 'node_A',
+          workflowNodeType: 'tool',
+        }),
+      ];
+      
+      const result = inferNextNode(messages as any, {});
+      
+      expect(result.type).toBe('resume_node');
+      expect(result.nodeId).toBe('node_A');
+    });
+    
+    it('should include agentSessionId if present', () => {
+      const messages = [
+        createMessage('workflow.node.call', '{}', {
+          type: 'workflow.node.call',
+          workflowNodeId: 'agent_1',
+          workflowNodeType: 'agent',
+          agentSessionId: 'agent_agent_1_123',
+        }),
+      ];
+      
+      const result = inferNextNode(messages as any, {});
+      
+      expect(result.type).toBe('resume_node');
+      expect(result.nodeId).toBe('agent_1');
+      expect(result.agentSessionId).toBe('agent_agent_1_123');
+    });
+  });
+  
+  describe('when last message is workflow.node.interrupt', () => {
+    it('should return ask_user type with nodeId', () => {
+      const messages = [
+        createMessage('workflow.node.interrupt', 'Continue?', {
+          type: 'workflow.node.interrupt',
+          workflowNodeId: 'ask_user_1',
+          workflowNodeType: 'ask_user',
+          query: 'Continue?',
+        }),
+      ];
+      
+      const result = inferNextNode(messages as any, {});
+      
+      expect(result.type).toBe('ask_user');
+      expect(result.nodeId).toBe('ask_user_1');
+    });
+    
+    it('should include agentSessionId if present', () => {
+      const messages = [
+        createMessage('workflow.node.interrupt', 'Confirm?', {
+          type: 'workflow.node.interrupt',
+          workflowNodeId: 'agent_1',
+          workflowNodeType: 'agent',
+          query: 'Confirm?',
+          agentSessionId: 'agent_agent_1_456',
+        }),
+      ];
+      
+      const result = inferNextNode(messages as any, {});
+      
+      expect(result.type).toBe('ask_user');
+      expect(result.nodeId).toBe('agent_1');
+      expect(result.agentSessionId).toBe('agent_agent_1_456');
+    });
+  });
+  
+  describe('when last message is workflow.node.result', () => {
+    it('should return next_nodes from DAG edges', () => {
+      const messages = [
+        createMessage('workflow.node.call', '{}', {
+          type: 'workflow.node.call',
+          workflowNodeId: 'node_A',
+        }),
+        createMessage('workflow.node.result', '{"output":"done"}', {
+          type: 'workflow.node.result',
+          workflowNodeId: 'node_A',
+          workflowNodeType: 'tool',
+          success: true,
+        }),
+      ];
+      
+      const definition = {
+        edges: [
+          { from: 'node_A', to: 'node_B' },
+          { from: 'node_A', to: 'node_C' },
+        ],
+      };
+      
+      const result = inferNextNode(messages as any, definition);
+      
+      expect(result.type).toBe('next_nodes');
+      expect(result.nodeIds).toEqual(['node_B', 'node_C']);
+    });
+    
+    it('should return empty array if no edges from node', () => {
+      const messages = [
+        createMessage('workflow.node.result', '{"output":"done"}', {
+          type: 'workflow.node.result',
+          workflowNodeId: 'node_A',
+          success: true,
+        }),
+      ];
+      
+      const definition = {
+        edges: [
+          { from: 'node_B', to: 'node_C' },
+        ],
+      };
+      
+      const result = inferNextNode(messages as any, definition);
+      
+      expect(result.type).toBe('next_nodes');
+      expect(result.nodeIds).toEqual([]);
+    });
+    
+    it('should return empty array if no edges defined', () => {
+      const messages = [
+        createMessage('workflow.node.result', '{"output":"done"}', {
+          type: 'workflow.node.result',
+          workflowNodeId: 'node_A',
+          success: true,
+        }),
+      ];
+      
+      const result = inferNextNode(messages as any, {});
+      
+      expect(result.type).toBe('next_nodes');
+      expect(result.nodeIds).toEqual([]);
+    });
+  });
+  
+  describe('when last message has unknown type', () => {
+    it('should find last call message and resume', () => {
+      const messages = [
+        createMessage('user', 'hello', {}),
+        createMessage('workflow.node.call', '{}', {
+          type: 'workflow.node.call',
+          workflowNodeId: 'node_A',
+        }),
+        createMessage('system', 'some status', {
+          type: 'unknown',
+        }),
+      ];
+      
+      const result = inferNextNode(messages as any, {});
+      
+      expect(result.type).toBe('resume_node');
+      expect(result.nodeId).toBe('node_A');
+    });
+    
+    it('should fallback to entry node if no call found', () => {
+      const messages = [
+        createMessage('user', 'hello', {}),
+      ];
+      
+      const definition = { entryNode: 'start' };
+      
+      const result = inferNextNode(messages as any, definition);
+      
+      expect(result.type).toBe('entry_node');
+      expect(result.nodeId).toBe('start');
+    });
+  });
+});
+
+describe('findLastInterruptMessage', () => {
+  it('should return last interrupt message', () => {
+    const messages = [
+      createMessage('workflow.node.call', '{}', { type: 'workflow.node.call' }),
+      createMessage('workflow.node.result', '{}', { type: 'workflow.node.result' }),
+      createMessage('workflow.node.interrupt', 'Continue?', { 
+        type: 'workflow.node.interrupt',
+        workflowNodeId: 'ask_1',
+      }),
+    ];
+    
+    const result = findLastInterruptMessage(messages as any);
+    
+    expect(result).not.toBeNull();
+    expect(result!.metadata.workflowNodeId).toBe('ask_1');
+  });
+  
+  it('should return null if no interrupt message', () => {
+    const messages = [
+      createMessage('workflow.node.call', '{}', { type: 'workflow.node.call' }),
+      createMessage('workflow.node.result', '{}', { type: 'workflow.node.result' }),
+    ];
+    
+    const result = findLastInterruptMessage(messages as any);
+    
+    expect(result).toBeNull();
+  });
+  
+  it('should return null for empty array', () => {
+    const result = findLastInterruptMessage([]);
+    expect(result).toBeNull();
+  });
+});
+
+describe('findLastCallMessage', () => {
+  it('should return last call message', () => {
+    const messages = [
+      createMessage('workflow.node.call', '{}', { 
+        type: 'workflow.node.call',
+        workflowNodeId: 'node_A',
+      }),
+      createMessage('workflow.node.call', '{}', { 
+        type: 'workflow.node.call',
+        workflowNodeId: 'node_B',
+      }),
+    ];
+    
+    const result = findLastCallMessage(messages as any);
+    
+    expect(result).not.toBeNull();
+    expect(result!.metadata.workflowNodeId).toBe('node_B');
+  });
+  
+  it('should return null if no call message', () => {
+    const messages = [
+      createMessage('user', 'hello', {}),
+      createMessage('workflow.node.result', '{}', { type: 'workflow.node.result' }),
+    ];
+    
+    const result = findLastCallMessage(messages as any);
+    
+    expect(result).toBeNull();
+  });
+});
+
+describe('parseNodeOutputs', () => {
+  it('should parse outputs from call-result pairs', () => {
+    const messages = [
+      createMessage('workflow.node.call', '{}', { 
+        type: 'workflow.node.call',
+        workflowNodeId: 'node_A',
+      }),
+      createMessage('workflow.node.result', '{"output":"result_A"}', { 
+        type: 'workflow.node.result',
+        workflowNodeId: 'node_A',
+      }),
+      createMessage('workflow.node.call', '{}', { 
+        type: 'workflow.node.call',
+        workflowNodeId: 'node_B',
+      }),
+      createMessage('workflow.node.result', '{"output":"result_B"}', { 
+        type: 'workflow.node.result',
+        workflowNodeId: 'node_B',
+      }),
+    ];
+    
+    const result = parseNodeOutputs(messages as any);
+    
+    expect(result.get('node_A')).toEqual({ output: 'result_A' });
+    expect(result.get('node_B')).toEqual({ output: 'result_B' });
+  });
+  
+  it('should handle JSON parse error gracefully', () => {
+    const messages = [
+      createMessage('workflow.node.call', '{}', { 
+        type: 'workflow.node.call',
+        workflowNodeId: 'node_A',
+      }),
+      createMessage('workflow.node.result', 'not json', { 
+        type: 'workflow.node.result',
+        workflowNodeId: 'node_A',
+      }),
+    ];
+    
+    const result = parseNodeOutputs(messages as any);
+    
+    expect(result.get('node_A')).toBe('not json');
+  });
+  
+  it('should return empty map for no outputs', () => {
+    const messages = [
+      createMessage('user', 'hello', {}),
+    ];
+    
+    const result = parseNodeOutputs(messages as any);
+    
+    expect(result.size).toBe(0);
+  });
+});

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

@@ -0,0 +1,188 @@
+/**
+ * Session Recovery Utilities
+ * 
+ * Utilities for inferring the next execution point from session messages.
+ * This is the core of the unified run/resume mechanism.
+ */
+
+import type { SessionMessage } from '../../session/types';
+
+/**
+ * Represents a resume point - where to continue execution from
+ */
+export interface ResumePoint {
+  /** Type of resume point */
+  type: 'entry_node' | 'resume_node' | 'ask_user' | 'next_nodes';
+  /** Node ID (for single node resume) */
+  nodeId?: string;
+  /** Node IDs (for multiple next nodes) */
+  nodeIds?: string[];
+  /** Agent sub-session ID (for agent node resume) */
+  agentSessionId?: string;
+  /** Input for the node */
+  input?: unknown;
+}
+
+/**
+ * Infer the next node to execute based on session messages
+ * 
+ * Decision logic:
+ * - No messages → execute entry node
+ * - Last = workflow.node.call → resume this node (incomplete)
+ * - Last = workflow.node.interrupt → resume this node (ask_user)
+ * - Last = workflow.node.result → execute next nodes from DAG
+ * - Unknown → find last call, resume it, or fallback to entry
+ */
+export function inferNextNode(
+  messages: SessionMessage[],
+  definition: {
+    entryNode?: string;
+    edges?: Array<{ from: string; to: string }>;
+  }
+): ResumePoint {
+  if (messages.length === 0) {
+    // First run - execute entry node
+    return { type: 'entry_node', nodeId: definition.entryNode };
+  }
+  
+  const lastMessage = messages[messages.length - 1];
+  const metadata = lastMessage.metadata as Record<string, unknown>;
+  
+  switch (metadata?.type) {
+    case 'workflow.node.call':
+      // Node was interrupted (not completed)
+      return {
+        type: 'resume_node',
+        nodeId: metadata.workflowNodeId as string,
+        agentSessionId: metadata.agentSessionId as string | undefined,
+      };
+    
+    case 'workflow.node.interrupt':
+      // Ask_user or ESC interrupted
+      return {
+        type: 'ask_user',
+        nodeId: metadata.workflowNodeId as string,
+        agentSessionId: metadata.agentSessionId as string | undefined,
+      };
+    
+    case 'workflow.node.result':
+      // Node completed, get next from DAG
+      return getNextNodes(metadata.workflowNodeId as string, definition);
+    
+    default:
+      // Unknown message type, try to find last call
+      const lastCall = findLastCallMessage(messages);
+      if (lastCall) {
+        const callMetadata = lastCall.metadata as Record<string, unknown>;
+        return {
+          type: 'resume_node',
+          nodeId: callMetadata.workflowNodeId as string,
+          agentSessionId: callMetadata.agentSessionId as string | undefined,
+        };
+      }
+      // No call found, fallback to entry
+      return { type: 'entry_node', nodeId: definition.entryNode };
+  }
+}
+
+/**
+ * Get next nodes from DAG edges
+ */
+function getNextNodes(
+  completedNodeId: string,
+  definition: { edges?: Array<{ from: string; to: string }> }
+): ResumePoint {
+  if (!definition.edges) {
+    return { type: 'next_nodes', nodeIds: [] };
+  }
+  
+  const nextNodeIds = definition.edges
+    .filter(edge => edge.from === completedNodeId)
+    .map(edge => edge.to);
+  
+  return { type: 'next_nodes', nodeIds: nextNodeIds };
+}
+
+/**
+ * Find the last interrupt message in the session
+ */
+export function findLastInterruptMessage(
+  messages: SessionMessage[]
+): SessionMessage | null {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if ((msg.metadata as Record<string, unknown>)?.type === 'workflow.node.interrupt') {
+      return msg;
+    }
+  }
+  return null;
+}
+
+/**
+ * Find the last call message in the session
+ */
+export function findLastCallMessage(
+  messages: SessionMessage[]
+): SessionMessage | null {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if ((msg.metadata as Record<string, unknown>)?.type === 'workflow.node.call') {
+      return msg;
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse node outputs from session messages
+ * 
+ * Extracts outputs by matching workflow.node.call with workflow.node.result pairs
+ */
+export function parseNodeOutputs(
+  messages: SessionMessage[]
+): Map<string, unknown> {
+  const outputs = new Map<string, unknown>();
+  let lastCallNodeId: string | null = null;
+  
+  for (const msg of messages) {
+    const metadata = msg.metadata as Record<string, unknown>;
+    
+    if (metadata?.type === 'workflow.node.call') {
+      lastCallNodeId = metadata.workflowNodeId as string;
+    } else if (metadata?.type === 'workflow.node.result' && lastCallNodeId) {
+      try {
+        outputs.set(lastCallNodeId, JSON.parse(msg.content as string));
+      } catch {
+        outputs.set(lastCallNodeId, msg.content);
+      }
+      lastCallNodeId = null;
+    }
+  }
+  
+  return outputs;
+}
+
+/**
+ * Check if session has pending ask_user interrupt
+ */
+export function hasPendingAskUser(messages: SessionMessage[]): boolean {
+  if (messages.length === 0) return false;
+  
+  const lastMessage = messages[messages.length - 1];
+  const metadata = lastMessage.metadata as Record<string, unknown>;
+  
+  return metadata?.type === 'workflow.node.interrupt';
+}
+
+/**
+ * Get agent session ID from last interrupt message
+ */
+export function getAgentSessionIdFromInterrupt(
+  messages: SessionMessage[]
+): string | null {
+  const lastInterrupt = findLastInterruptMessage(messages);
+  if (!lastInterrupt) return null;
+  
+  const metadata = lastInterrupt.metadata as Record<string, unknown>;
+  return (metadata?.agentSessionId as string) || null;
+}