@pixel-normal-edit/mcp 2.0.10 → 2.2.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,249 @@ 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
- * @returns {Object} Kết quả chuyển bước
+ * @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
+
+  // Auto-set flags based on completed request type
+  if (state.user_input_request.type === 'CANVAS_SIZE') {
+    state.step_completion_flags.canvas_initialized = true;
+  }
+  if (state.user_input_request.type === 'APPROVE_PLAN') {
+    state.step_completion_flags.plan_created = true;
+  }
+
+  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} 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. You MUST use workflow_create_input_request with type CANVAS_SIZE 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 = [
+    `📋 **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:**`
+  ];
 
-  const lines = ['📋 **Tiến trình vẽ:**\n'];
   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 +404,11 @@ module.exports = {
   advance,
   reset,
   getProgressReport,
+  setApprovalRequired,
+  createInputRequest,
+  completeInputRequest,
+  setLayerAndFrame,
+  setPhase,
+  setAnimationMeta,
+  setStepFlag
 };

package/tools/canvas-tools.js

@@ -16,8 +16,8 @@ function register(server) {
   registerTool(server, 'canvas_resize',
     'Resize canvas to new dimensions. mode=clear resets pixels, extend keeps them.',
     {
-      width: z.number().int().min(1).max(1024).describe('New width in pixels'),
-      height: z.number().int().min(1).max(1024).describe('New height in pixels'),
+      width: z.number().int().min(1).max(256).describe('New width in pixels (max 256)'),
+      height: z.number().int().min(1).max(256).describe('New height in pixels (max 256)'),
       mode: z.enum(['clear', 'extend', 'fit']).default('clear').describe('How to handle existing content'),
       dx: z.number().int().default(0).describe('X offset for content when extending'),
       dy: z.number().int().default(0).describe('Y offset for content when extending')

package/tools/drawing-tools.js

@@ -14,54 +14,65 @@ const hexColor = z.string().regex(/^#[0-9a-fA-F]{6}$/).describe('Hex color e.g.
 function register(server) {
   registerTool(server, 'draw_pixel',
     'Set a single pixel to a color',
-    { x: z.number().int().describe('X coordinate'), y: z.number().int().describe('Y coordinate'), color: hexColor },
+    { x: z.number().int().max(1024).describe('X coordinate'), y: z.number().int().max(1024).describe('Y coordinate'), color: hexColor },
     (p) => ({ action: 'drawPixel', ...p }));
 
   registerTool(server, 'draw_erase',
     'Erase a single pixel (make transparent)',
-    { x: z.number().int(), y: z.number().int() },
+    { x: z.number().int().max(1024), y: z.number().int().max(1024) },
     (p) => ({ action: 'erasePixel', ...p }));
 
+  registerTool(server, 'draw_pixels_bulk',
+    'Set multiple pixels at once (much faster than calling draw_pixel repeatedly)',
+    { 
+      pixels: z.array(z.object({ 
+        x: z.number().int().max(1024), 
+        y: z.number().int().max(1024), 
+        color: hexColor.optional() 
+      })).max(5000).describe('Array of pixels {x, y, color}. Omit color to erase.')
+    },
+    (p) => ({ action: 'drawPixelsBulk', pixels: p.pixels }));
+
   registerTool(server, 'draw_line',
     'Draw a straight line using Bresenham algorithm',
-    { x0: z.number().int(), y0: z.number().int(), x1: z.number().int(), y1: z.number().int(), color: hexColor },
+    { x0: z.number().int().max(1024), y0: z.number().int().max(1024), x1: z.number().int().max(1024), y1: z.number().int().max(1024), color: hexColor },
     (p) => ({ action: 'drawLine', ...p }));
 
   registerTool(server, 'draw_rect',
     'Draw a rectangle (outline or filled)',
     {
-      x: z.number().int().describe('Top-left X'), y: z.number().int().describe('Top-left Y'),
-      w: z.number().int().min(1).describe('Width'), h: z.number().int().min(1).describe('Height'),
+      x: z.number().int().max(1024).describe('Top-left X'), y: z.number().int().max(1024).describe('Top-left Y'),
+      w: z.number().int().min(1).max(256).describe('Width (max 256)'), h: z.number().int().min(1).max(256).describe('Height (max 256)'),
       color: hexColor, filled: z.boolean().default(false).describe('Fill interior?')
     },
     (p) => ({ action: 'drawRect', ...p }));
 
   registerTool(server, 'draw_circle',
     'Draw a circle (outline or filled)',
-    { cx: z.number().int().describe('Center X'), cy: z.number().int().describe('Center Y'),
-      r: z.number().int().min(1).describe('Radius'), color: hexColor, filled: z.boolean().default(false) },
+    { cx: z.number().int().max(1024).describe('Center X'), cy: z.number().int().max(1024).describe('Center Y'),
+      r: z.number().int().min(1).max(128).describe('Radius (max 128)'), color: hexColor, filled: z.boolean().default(false) },
     (p) => ({ action: 'drawCircle', ...p }));
 
   registerTool(server, 'draw_ellipse',
     'Draw an ellipse (outline or filled)',
-    { cx: z.number().int(), cy: z.number().int(), rx: z.number().int().min(1).describe('Horizontal radius'),
-      ry: z.number().int().min(1).describe('Vertical radius'), color: hexColor, filled: z.boolean().default(false) },
+    { cx: z.number().int().max(1024), cy: z.number().int().max(1024), rx: z.number().int().min(1).max(128).describe('Horizontal radius'),
+      ry: z.number().int().min(1).max(128).describe('Vertical radius'), color: hexColor, filled: z.boolean().default(false) },
     (p) => ({ action: 'drawEllipse', ...p }));
 
   registerTool(server, 'draw_polygon',
     'Draw a polygon from a list of points (outline or filled)',
-    { points: z.array(z.object({ x: z.number().int(), y: z.number().int() })).min(3).describe('Array of {x,y} vertices'),
+    { points: z.array(z.object({ x: z.number().int().max(1024), y: z.number().int().max(1024) })).min(3).describe('Array of {x,y} vertices'),
       color: hexColor, filled: z.boolean().default(false) },
     (p) => ({ action: 'drawPolygon', ...p }));
 
   registerTool(server, 'draw_fill',
     'Flood-fill starting from (x,y) with a color',
-    { x: z.number().int(), y: z.number().int(), color: hexColor },
+    { x: z.number().int().max(1024), y: z.number().int().max(1024), color: hexColor },
     (p) => ({ action: 'fill', ...p }));
 
   registerTool(server, 'draw_gradient_rect',
     'Draw a rectangle filled with a smooth gradient',
-    { x: z.number().int(), y: z.number().int(), w: z.number().int().min(1), h: z.number().int().min(1),
+    { x: z.number().int().max(1024), y: z.number().int().max(1024), w: z.number().int().min(1).max(256).describe('Width (max 256)'), h: z.number().int().min(1).max(256).describe('Height (max 256)'),
       colorFrom: hexColor.describe('Start color'), colorTo: hexColor.describe('End color'),
       direction: z.enum(['h', 'v']).default('h').describe('h=horizontal, v=vertical') },
     (p) => ({ action: 'drawGradientRect', ...p }));

package/tools/workspace-tools.js

@@ -19,21 +19,22 @@ function register(server) {
     {},
     () => ({ action: 'getActiveTabId' }));
 
-  server.tool('workspace_create_tab',
+  registerTool(server, 'workspace_create_tab',
     'Create a new blank canvas tab',
     {
       name: z.string().optional().describe('Tab name'),
-      width: z.number().int().optional().describe('Canvas width'),
-      height: z.number().int().optional().describe('Canvas height')
+      width: z.number().int().min(1).max(256).optional().describe('Canvas width (max 256)'),
+      height: z.number().int().min(1).max(256).optional().describe('Canvas height (max 256)')
     },
     async (p) => {
       if (p.width === undefined || p.height === undefined) {
         return {
+          action: 'noop',
           isError: true,
           content: [{ type: 'text', text: 'Please provide the width and height dimensions (resize) when creating a new canvas.' }]
         };
       }
-      return sendCommand({ action: 'createTab', ...p });
+      return { action: 'createTab', ...p };
     }
   );