@pixel-normal-edit/mcp 2.0.10 → 2.1.0

package/rules/workflow.js

@@ -1,45 +1,79 @@
 #!/usr/bin/env node
 /**
- * workflow.js — Workflow Engine (Bắt buộc tuân thủ thứ tự)
- *
- * Engine này quản lý trạng thái workflow của agent.
- * Mỗi lần agent gọi 1 tool, workflow engine sẽ kiểm tra:
- *   - Agent đang ở bước nào?
- *   - Bước tiếp theo phải là gì?
- *   - Nếu sai thứ tự → từ chối và yêu cầu làm đúng bước
- *
- * Cách dùng:
- *   const workflow = require('./rules/workflow');
- *   workflow.start('my_project');        // Bắt đầu workflow mới
- *   workflow.getCurrentStep();           // Xem đang ở bước nào
- *   workflow.advance();                  // Chuyển sang bước tiếp theo
- *   workflow.validateStep('draw');       // Kiểm tra có được phép vẽ chưa
+ * workflow.js — Workflow Engine (Strict step ordering with modes, phases, layers)
  */
 
-const { WORKFLOW_STEPS } = require('./rules');
+const { WORKFLOW_STEPS, MODES, STATUSES, DRAWING_PHASES } = require('./rules');
+const fs = require('fs');
+const path = require('path');
+
+const STATE_FILE = path.join(__dirname, '..', 'workflow_state.json');
+let sessions = new Map();
+
+// --- PERSISTENCE ---
+function saveState() {
+  const data = {};
+  for (const [key, val] of sessions.entries()) {
+    data[key] = val;
+  }
+  try {
+    fs.writeFileSync(STATE_FILE, JSON.stringify(data, null, 2), 'utf-8');
+  } catch (e) {
+    console.error('Failed to save workflow state:', e);
+  }
+}
+
+function loadState() {
+  if (fs.existsSync(STATE_FILE)) {
+    try {
+      const content = fs.readFileSync(STATE_FILE, 'utf-8');
+      const data = JSON.parse(content);
+      sessions = new Map(Object.entries(data));
+    } catch (e) {
+      console.error('Failed to load workflow state:', e);
+    }
+  }
+}
+
+// Load state on startup
+loadState();
 
-// ── In-memory workflow state ────────────────────────────────────────────────
-// Key: sessionId, Value: { currentStepIndex, steps, completedSteps, startedAt }
-const sessions = new Map();
 
 /**
- * Bắt đầu một workflow mới cho session
- * @param {string} sessionId - Mã session (thường là MCP_SESSION)
- * @returns {Object} Trạng thái workflow ban đầu
+ * Start a new workflow for a session
+ * @param {string} sessionId - Session ID (usually MCP_SESSION)
+ * @param {string} mode - The mode to start in (CREATE_IMAGE, EDIT_IMAGE, CREATE_ANIMATION)
+ * @returns {Object} Initial workflow state
  */
-function start(sessionId) {
+function start(sessionId, mode = MODES.CREATE_IMAGE) {
+  if (!WORKFLOW_STEPS[mode]) {
+    throw new Error(`Invalid mode: ${mode}`);
+  }
+
   const state = {
+    current_mode: mode,
     currentStepIndex: 0,
-    steps: WORKFLOW_STEPS.map(s => ({ ...s, status: 'pending' })),
+    steps: WORKFLOW_STEPS[mode].map(s => ({ ...s, status: STATUSES.PENDING })),
+    current_layer: 0,
+    current_frame: mode === MODES.CREATE_ANIMATION ? 0 : null,
+    current_phase: null,
+    animation_meta: { fps: null, total_frames: null, loop: true },
+    step_status: STATUSES.IN_PROGRESS,
+    user_approval_required: false,
+    user_input_request: null, // { id, type, fields, status, created_at, response }
+    step_completion_flags: {}, // track internal flags for steps
     completedSteps: [],
+    history: [],
     startedAt: Date.now(),
   };
+  
   sessions.set(sessionId, state);
+  saveState();
   return getState(sessionId);
 }
 
 /**
- * Lấy trạng thái workflow hiện tại
+ * Get current workflow state
  * @param {string} sessionId
  * @returns {Object|null}
  */
@@ -48,9 +82,9 @@ function getState(sessionId) {
 }
 
 /**
- * Lấy bước hiện tại
+ * Get current step
  * @param {string} sessionId
- * @returns {{ id: string, label: string, description: string, status: string }|null}
+ * @returns {Object|null}
  */
 function getCurrentStep(sessionId) {
   const state = sessions.get(sessionId);
@@ -59,9 +93,9 @@ function getCurrentStep(sessionId) {
 }
 
 /**
- * Kiểm tra xem agent có được phép thực hiện hành động này không
+ * Check if the agent is allowed to perform this action
  * @param {string} sessionId
- * @param {string} stepId - ID của bước muốn thực hiện
+ * @param {string} stepId - ID of the step to perform
  * @returns {{ allowed: boolean, message?: string, currentStep?: Object }}
  */
 function validateStep(sessionId, stepId) {
@@ -69,7 +103,15 @@ function validateStep(sessionId, stepId) {
   if (!state) {
     return {
       allowed: false,
-      message: '⚠️ Chưa bắt đầu workflow. Hãy gọi workflow_start trước!',
+      message: '⚠️ Workflow has not started. Call workflow_start first!',
+    };
+  }
+
+  if (state.user_approval_required) {
+    return {
+      allowed: false,
+      message: '⛔ Workflow is waiting for user approval. Ask the user for confirmation.',
+      currentStep: state.steps[state.currentStepIndex]
     };
   }
 
@@ -77,29 +119,26 @@ function validateStep(sessionId, stepId) {
   if (!current) {
     return {
       allowed: false,
-      message: '✅ Workflow đã hoàn tất! Không còn bước nào cần làm.',
+      message: '✅ Workflow is complete! No remaining steps.',
     };
   }
 
-  // Tìm index của stepId trong workflow
   const targetIndex = state.steps.findIndex(s => s.id === stepId);
   if (targetIndex === -1) {
     return {
       allowed: false,
-      message: `❌ Không tìm thấy bước "${stepId}" trong workflow.`,
+      message: `❌ Step "${stepId}" not found in current mode workflow.`,
     };
   }
 
-  // Nếu stepId nằm trước bước hiện tại (đã hoàn thành) → cho phép (có thể cần quay lại)
   if (targetIndex < state.currentStepIndex) {
     return {
       allowed: true,
-      message: `⚠️ Bước "${stepId}" đã hoàn thành trước đó. Bạn có chắc muốn làm lại?`,
+      message: `⚠️ Step "${stepId}" was already completed. Are you sure you want to redo it?`,
       currentStep: current,
     };
   }
 
-  // Nếu stepId đúng là bước hiện tại → cho phép
   if (targetIndex === state.currentStepIndex) {
     return {
       allowed: true,
@@ -107,81 +146,241 @@ function validateStep(sessionId, stepId) {
     };
   }
 
-  // Nếu stepId nằm ở tương lai → CHẶN
   return {
     allowed: false,
-    message: `⛔ Bạn chưa thể thực hiện "${stepId}". Trước hết hãy hoàn thành: "${current.label}" (${current.description})`,
+    message: `⛔ You cannot perform "${stepId}" yet. First complete: "${current.label}" (${current.description})`,
     currentStep: current,
   };
 }
 
 /**
- * Đánh dấu bước hiện tại là hoàn thành và chuyển sang bước tiếp theo
+ * Set user approval requirement
+ * @param {string} sessionId
+ * @param {boolean} required
+ */
+function setApprovalRequired(sessionId, required) {
+  const state = sessions.get(sessionId);
+  if (!state) return false;
+  state.user_approval_required = required;
+  if (required) {
+    state.step_status = STATUSES.WAITING_FOR_USER;
+  } else {
+    if (state.user_input_request && state.user_input_request.status === 'WAITING_FOR_USER') {
+      return false; // Cannot unpause if waiting for explicit input request
+    }
+    state.step_status = STATUSES.IN_PROGRESS;
+  }
+  saveState();
+  return true;
+}
+
+/**
+ * Create a user input request
+ * @param {string} sessionId
+ * @param {string} type - e.g. CANVAS_SIZE, APPROVE_PLAN, SELECT_EDIT_REGION
+ * @param {Object} fields - fields required
+ */
+function createInputRequest(sessionId, type, fields = {}) {
+  const state = sessions.get(sessionId);
+  if (!state) return false;
+
+  state.user_input_request = {
+    id: `req_${Date.now()}_${Math.floor(Math.random()*1000)}`,
+    type,
+    fields,
+    status: 'WAITING_FOR_USER',
+    created_at: Date.now()
+  };
+  state.step_status = STATUSES.WAITING_FOR_USER;
+  state.history.push({ event: 'input_request_created', type, time: Date.now() });
+  saveState();
+  return state.user_input_request.id;
+}
+
+/**
+ * Complete a user input request
+ * @param {string} sessionId
+ * @param {string} reqId
+ * @param {string} response
+ */
+function completeInputRequest(sessionId, reqId, response) {
+  const state = sessions.get(sessionId);
+  if (!state || !state.user_input_request || state.user_input_request.id !== reqId) return false;
+
+  state.user_input_request.status = 'COMPLETED';
+  state.user_input_request.response = response;
+  state.step_status = STATUSES.IN_PROGRESS; // Unpause workflow
+  
+  state.history.push({ event: 'input_request_completed', reqId, time: Date.now() });
+  saveState();
+  return true;
+}
+
+/**
+ * Update layer/frame
+ */
+function setLayerAndFrame(sessionId, layer, frame = null) {
+  const state = sessions.get(sessionId);
+  if (!state) return false;
+  
+  if (layer !== undefined && layer !== null) {
+    state.current_layer = layer;
+  }
+  if (frame !== undefined && frame !== null) {
+    state.current_frame = frame;
+  }
+  state.history.push({ 
+    event: 'layer_frame_change', 
+    layer: state.current_layer, 
+    frame: state.current_frame, 
+    time: Date.now() 
+  });
+  saveState();
+  return true;
+}
+
+/**
+ * Update phase
+ */
+function setPhase(sessionId, phase) {
+  const state = sessions.get(sessionId);
+  if (!state) return false;
+  
+  state.current_phase = phase;
+  state.history.push({ 
+    event: 'phase_change', 
+    phase: phase, 
+    time: Date.now() 
+  });
+  saveState();
+  return true;
+}
+
+/**
+ * Set animation meta
+ */
+function setAnimationMeta(sessionId, fps, total_frames, loop) {
+  const state = sessions.get(sessionId);
+  if (!state) return false;
+  
+  if (fps !== undefined) state.animation_meta.fps = fps;
+  if (total_frames !== undefined) state.animation_meta.total_frames = total_frames;
+  if (loop !== undefined) state.animation_meta.loop = loop;
+  
+  saveState();
+  return true;
+}
+
+/**
+ * Set step completion flag (internal validation)
+ */
+function setStepFlag(sessionId, flagName, value) {
+  const state = sessions.get(sessionId);
+  if (!state) return false;
+  state.step_completion_flags[flagName] = value;
+  saveState();
+  return true;
+}
+
+/**
+ * Mark current step as completed and advance to the next step
  * @param {string} sessionId
- * @returns {Object} Kết quả chuyển bước
+ * @returns {Object} Step transition result
  */
 function advance(sessionId) {
   const state = sessions.get(sessionId);
   if (!state) {
-    return { success: false, message: 'Chưa bắt đầu workflow' };
+    return { success: false, message: 'Workflow has not started' };
+  }
+  
+  if (state.user_approval_required) {
+    return { success: false, message: 'Cannot advance: Waiting for user approval.' };
+  }
+
+  if (state.step_status === STATUSES.WAITING_FOR_USER) {
+    return { success: false, message: 'Cannot advance: Waiting for user approval or input.' };
   }
 
   const current = state.steps[state.currentStepIndex];
   if (!current) {
-    return { success: false, message: 'Workflow đã hoàn tất' };
+    return { success: false, message: 'Workflow is complete' };
   }
 
-  // Đánh dấu bước hiện tại là completed
-  current.status = 'completed';
+  // Pre-condition validation block
+  if (current.id === 'INITIALIZE_CANVAS' && !state.step_completion_flags.canvas_initialized) {
+    return { success: false, message: 'Cannot advance: Canvas has not been initialized. Create a canvas first.' };
+  }
+  if (current.id === 'PLAN_DRAWING' && !state.step_completion_flags.plan_created) {
+    return { success: false, message: 'Cannot advance: Drawing plan has not been finalized.' };
+  }
+
+  current.status = STATUSES.COMPLETED;
   state.completedSteps.push(current.id);
+  state.history.push({ event: 'step_completed', step: current.id, layer: state.current_layer, frame: state.current_frame, time: Date.now() });
 
-  // Chuyển sang bước tiếp theo
   state.currentStepIndex++;
 
   const next = state.steps[state.currentStepIndex] || null;
   if (next) {
-    next.status = 'in_progress';
+    next.status = STATUSES.IN_PROGRESS;
+    state.step_status = STATUSES.IN_PROGRESS;
+    saveState();
     return {
       success: true,
       completedStep: current,
       nextStep: next,
-      message: `✅ Hoàn thành: "${current.label}". Bước tiếp theo: "${next.label}" — ${next.description}`,
+      message: `✅ Completed: "${current.label}". Next step: "${next.label}" — ${next.description}`,
     };
   }
 
+  state.step_status = STATUSES.COMPLETED;
+  saveState();
   return {
     success: true,
     completedStep: current,
     nextStep: null,
-    message: `🎉 Hoàn tất tất cả các bước! Tác phẩm đã sẵn sàng.`,
+    message: `🎉 All steps completed! The task is ready.`,
   };
 }
 
 /**
- * Reset workflow về đầu
+ * Reset workflow to the beginning
  * @param {string} sessionId
  */
 function reset(sessionId) {
+  const state = sessions.get(sessionId);
+  const mode = state ? state.current_mode : MODES.CREATE_IMAGE;
   sessions.delete(sessionId);
-  return start(sessionId);
+  saveState();
+  return start(sessionId, mode);
 }
 
 /**
- * Lấy toàn bộ tiến trình dạng text để trả về cho agent
+ * Get text-based progress report for the agent
  * @param {string} sessionId
  * @returns {string}
  */
 function getProgressReport(sessionId) {
   const state = sessions.get(sessionId);
-  if (!state) return 'Chưa bắt đầu workflow.';
+  if (!state) return 'Workflow has not started.';
 
-  const lines = ['📋 **Tiến trình vẽ:**\n'];
+  const lines = [
+    `📋 **Workflow Progress: [Mode: ${state.current_mode}]**`,
+    `Layer: ${state.current_layer} | Frame: ${state.current_frame !== null ? state.current_frame : 'N/A'}`,
+    `Phase: ${state.current_phase !== null ? state.current_phase : 'N/A'}`,
+    `Animation Meta: FPS=${state.animation_meta.fps || 'N/A'}, Frames=${state.animation_meta.total_frames || 'N/A'}, Loop=${state.animation_meta.loop}`,
+    `Status: ${state.step_status}`,
+    `User Approval Required: ${state.user_approval_required ? 'YES' : 'NO'}`,
+    state.user_input_request && state.user_input_request.status === 'WAITING_FOR_USER' ? `⚠️ PENDING REQUEST: ${state.user_input_request.type}` : '',
+    `\n**Steps:**`
+  ];
+  
   state.steps.forEach((step, i) => {
-    const icon = step.status === 'completed' ? '✅' :
-                 step.status === 'in_progress' ? '🔄' : '⬜';
-    const marker = i === state.currentStepIndex ? ' ← **ĐANG LÀM**' : '';
+    const icon = step.status === STATUSES.COMPLETED ? '✅' :
+                 step.status === STATUSES.IN_PROGRESS ? '🔄' : '⬜';
+    const marker = i === state.currentStepIndex ? ' ← **IN PROGRESS**' : '';
     lines.push(`${icon} **${step.label}**${marker}`);
-    if (step.status === 'in_progress' || i === state.currentStepIndex) {
+    if (step.status === STATUSES.IN_PROGRESS || i === state.currentStepIndex) {
       lines.push(`   → ${step.description}`);
     }
   });
@@ -197,4 +396,11 @@ module.exports = {
   advance,
   reset,
   getProgressReport,
+  setApprovalRequired,
+  createInputRequest,
+  completeInputRequest,
+  setLayerAndFrame,
+  setPhase,
+  setAnimationMeta,
+  setStepFlag
 };