@polymorphism-tech/morph-spec 4.2.0 → 4.3.1

package/src/lib/threads/thread-coordinator.js

@@ -0,0 +1,238 @@
+/**
+ * Thread Coordinator — Dependency analysis and wait strategies
+ *
+ * Parses tasks.json dependency graphs and identifies:
+ * - Tasks that can run in parallel (no dependencies on each other)
+ * - Tasks that must run sequentially
+ * - Circular dependencies
+ *
+ * Returns an execution plan: phases of parallel groups.
+ *
+ * Example output:
+ *   Phase 1 (parallel): [T001, T002, T005]  ← no dependencies
+ *   Phase 2 (parallel): [T003, T004]         ← depend only on phase 1
+ *   Phase 3 (sequential): [T006]             ← depends on both T003, T004
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+// ============================================================================
+// Dependency Analysis
+// ============================================================================
+
+/**
+ * Build a dependency graph from an in-memory task array
+ * @param {Array} tasks - Array of { id, dependencies: [] } task objects
+ * @returns {Object} { nodes: Map<id, task>, edges: Map<id, Set<depId>>, tasks }
+ */
+export function buildGraph(tasks) {
+  const nodes = new Map();
+  const edges = new Map();
+
+  for (const task of tasks) {
+    nodes.set(task.id, task);
+    edges.set(task.id, new Set(task.dependencies || []));
+  }
+
+  return { nodes, edges, tasks };
+}
+
+/**
+ * Parse tasks.json and build a dependency graph
+ * @param {string} feature - Feature name
+ * @returns {Object} { nodes: Map<id, task>, edges: Map<id, Set<depId>> }
+ */
+export function analyzeDependencies(feature) {
+  const tasksPath = join(process.cwd(), `.morph/project/outputs/${feature}/tasks.json`);
+
+  if (!existsSync(tasksPath)) {
+    throw new Error(`tasks.json not found for feature: ${feature}`);
+  }
+
+  let tasksData;
+  try {
+    tasksData = JSON.parse(readFileSync(tasksPath, 'utf8'));
+  } catch (err) {
+    throw new Error(`Failed to parse tasks.json: ${err.message}`);
+  }
+
+  return buildGraph(tasksData.tasks || []);
+}
+
+/**
+ * Identify tasks that can run in parallel (no dependencies between them)
+ * @param {Object} graph - { nodes, edges } from buildGraph/analyzeDependencies
+ * @returns {Array} Groups of task IDs that can run in parallel
+ */
+export function identifyParallelizable(graph) {
+  const { nodes, edges } = graph;
+  const plan = planExecution(nodes, edges);
+  return plan.filter(group => group.length > 1);
+}
+
+/**
+ * Identify tasks that must run sequentially
+ * @param {Object} graph - { nodes, edges } from buildGraph/analyzeDependencies
+ * @returns {Array} Task IDs that must run sequentially
+ */
+export function identifySequential(graph) {
+  const { nodes, edges } = graph;
+  const plan = planExecution(nodes, edges);
+  return plan.filter(group => group.length === 1).flat();
+}
+
+/**
+ * Detect circular dependencies in the task graph
+ * @param {Map} nodes - Task nodes
+ * @param {Map} edges - Dependency edges
+ * @returns {Array} Array of circular dependency chains, or [] if none
+ */
+export function detectCircular(nodes, edges) {
+  const cycles = [];
+  const visited = new Set();
+  const recursionStack = new Set();
+
+  function dfs(nodeId, path) {
+    visited.add(nodeId);
+    recursionStack.add(nodeId);
+
+    for (const dep of (edges.get(nodeId) || [])) {
+      if (!nodes.has(dep)) continue;
+
+      if (!visited.has(dep)) {
+        dfs(dep, [...path, nodeId]);
+      } else if (recursionStack.has(dep)) {
+        // Found a cycle
+        const cycleStart = path.indexOf(dep);
+        const cycle = cycleStart >= 0
+          ? [...path.slice(cycleStart), nodeId, dep]
+          : [...path, nodeId, dep];
+        cycles.push(cycle);
+      }
+    }
+
+    recursionStack.delete(nodeId);
+  }
+
+  for (const nodeId of nodes.keys()) {
+    if (!visited.has(nodeId)) {
+      dfs(nodeId, []);
+    }
+  }
+
+  return cycles;
+}
+
+/**
+ * Plan execution: return phases of parallel task groups
+ * @param {Map} nodes - Task nodes
+ * @param {Map} edges - Dependency edges
+ * @returns {Array} Array of phases, each phase is an array of task IDs
+ *
+ * Algorithm: Kahn's topological sort, grouping by "wave"
+ */
+export function planExecution(nodes, edges) {
+  // Check for cycles first
+  const cycles = detectCircular(nodes, edges);
+  if (cycles.length > 0) {
+    throw new Error(
+      `Circular dependencies detected: ${cycles.map(c => c.join(' → ')).join('; ')}`
+    );
+  }
+
+  // Build reverse edges (dependents)
+  const inDegree = new Map();
+  const dependents = new Map(); // id → Set of task IDs that depend on it
+
+  for (const [id] of nodes) {
+    inDegree.set(id, 0);
+    dependents.set(id, new Set());
+  }
+
+  for (const [id, deps] of edges) {
+    for (const dep of deps) {
+      if (!inDegree.has(dep)) continue;
+      inDegree.set(id, (inDegree.get(id) || 0) + 1);
+      dependents.get(dep).add(id);
+    }
+  }
+
+  // Correct in-degree: count only deps that exist in nodes
+  for (const [id, deps] of edges) {
+    let count = 0;
+    for (const dep of deps) {
+      if (nodes.has(dep)) count++;
+    }
+    inDegree.set(id, count);
+  }
+
+  const phases = [];
+  const remaining = new Set(nodes.keys());
+
+  while (remaining.size > 0) {
+    // Find all nodes with no unsatisfied dependencies
+    const ready = [...remaining].filter(id => {
+      const deps = edges.get(id) || new Set();
+      return [...deps].every(dep => !remaining.has(dep));
+    });
+
+    if (ready.length === 0 && remaining.size > 0) {
+      // Shouldn't happen if no cycles, but safeguard
+      throw new Error(`Execution plan stalled with ${remaining.size} remaining tasks: ${[...remaining].join(', ')}`);
+    }
+
+    phases.push(ready);
+    for (const id of ready) {
+      remaining.delete(id);
+    }
+  }
+
+  return phases;
+}
+
+// ============================================================================
+// Full Analysis
+// ============================================================================
+
+/**
+ * Get full parallel execution plan for a feature
+ * @param {string} feature - Feature name
+ * @returns {Object} Execution plan with phases, parallelizable groups, and stats
+ */
+export function getExecutionPlan(feature) {
+  const { nodes, edges, tasks } = analyzeDependencies(feature);
+
+  const cycles = detectCircular(nodes, edges);
+  if (cycles.length > 0) {
+    return {
+      feature,
+      valid: false,
+      cycles,
+      error: `Circular dependencies found: ${cycles.map(c => c.join(' → ')).join('; ')}`
+    };
+  }
+
+  const phases = planExecution(nodes, edges);
+  const parallelPhases = phases.filter(p => p.length > 1);
+  const totalParallelizable = parallelPhases.reduce((sum, p) => sum + p.length, 0);
+
+  return {
+    feature,
+    valid: true,
+    totalTasks: tasks.length,
+    phases: phases.map((group, i) => ({
+      phase: i + 1,
+      tasks: group,
+      canRunParallel: group.length > 1,
+      count: group.length
+    })),
+    stats: {
+      totalPhases: phases.length,
+      parallelPhases: parallelPhases.length,
+      parallelizableTasks: totalParallelizable,
+      sequentialTasks: tasks.length - totalParallelizable,
+      parallelizationRatio: Math.round(totalParallelizable / Math.max(tasks.length, 1) * 100)
+    }
+  };
+}

package/src/lib/threads/thread-manager.js

@@ -0,0 +1,317 @@
+/**
+ * Thread Manager — Core thread lifecycle management
+ *
+ * Manages the full lifecycle of MORPH-SPEC threads:
+ * - Types: base, parallel, fusion, long-running, zero-touch
+ * - Status transitions: pending → running → completed | failed | killed
+ * - Persists thread state to state.json threads{} section
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+
+const STATE_PATH = join(process.cwd(), '.morph/state.json');
+
+// ============================================================================
+// Thread Types and Status
+// ============================================================================
+
+export const THREAD_TYPES = {
+  BASE: 'base',
+  PARALLEL: 'parallel',
+  FUSION: 'fusion',
+  LONG_RUNNING: 'long-running',
+  ZERO_TOUCH: 'zero-touch'
+};
+
+export const THREAD_STATUS = {
+  PENDING: 'pending',
+  RUNNING: 'running',
+  COMPLETED: 'completed',
+  FAILED: 'failed',
+  KILLED: 'killed'
+};
+
+// ============================================================================
+// State I/O
+// ============================================================================
+
+function loadState() {
+  if (!existsSync(STATE_PATH)) {
+    throw new Error(`State file not found: ${STATE_PATH}`);
+  }
+  return JSON.parse(readFileSync(STATE_PATH, 'utf8'));
+}
+
+function saveState(state) {
+  state.metadata = state.metadata || {};
+  state.metadata.lastUpdated = new Date().toISOString();
+  writeFileSync(STATE_PATH, JSON.stringify(state, null, 2), 'utf8');
+}
+
+function ensureThreadsSection(state) {
+  if (!state.threads) {
+    state.threads = {};
+  }
+  return state;
+}
+
+// ============================================================================
+// Thread CRUD
+// ============================================================================
+
+/**
+ * Create a new thread
+ * @param {Object} opts
+ * @param {string} opts.feature - Feature name this thread belongs to
+ * @param {string} opts.type - Thread type (base|parallel|fusion|long-running|zero-touch)
+ * @param {string} [opts.agent] - Agent assigned to this thread
+ * @param {string} [opts.mission] - Thread mission description
+ * @param {Object} [opts.meta] - Additional metadata
+ * @returns {Object} Created thread object
+ */
+export function createThread({ feature, type = THREAD_TYPES.BASE, agent = null, mission = '', meta = {} }) {
+  const state = ensureThreadsSection(loadState());
+  const id = randomUUID();
+  const now = new Date().toISOString();
+
+  const thread = {
+    id,
+    feature,
+    type,
+    agent,
+    mission,
+    status: THREAD_STATUS.PENDING,
+    createdAt: now,
+    startedAt: null,
+    completedAt: null,
+    duration: null,
+    events: [],
+    metrics: {
+      toolCalls: 0,
+      tokensUsed: 0,
+      checkpointsPassed: 0,
+      checkpointsFailed: 0
+    },
+    meta
+  };
+
+  state.threads[id] = thread;
+  saveState(state);
+  return thread;
+}
+
+/**
+ * Update thread fields
+ * @param {string} id - Thread ID
+ * @param {Object} updates - Fields to update
+ * @returns {Object} Updated thread
+ */
+export function updateThread(id, updates) {
+  const state = ensureThreadsSection(loadState());
+
+  if (!state.threads[id]) {
+    throw new Error(`Thread not found: ${id}`);
+  }
+
+  state.threads[id] = { ...state.threads[id], ...updates };
+  saveState(state);
+  return state.threads[id];
+}
+
+/**
+ * Get a thread by ID
+ * @param {string} id - Thread ID
+ * @returns {Object|null} Thread or null
+ */
+export function getThread(id) {
+  const state = ensureThreadsSection(loadState());
+  return state.threads[id] || null;
+}
+
+/**
+ * List threads, optionally filtered
+ * @param {Object} [filter]
+ * @param {string} [filter.feature] - Filter by feature name
+ * @param {string} [filter.status] - Filter by status
+ * @param {string} [filter.type] - Filter by type
+ * @returns {Array} Array of thread objects
+ */
+export function listThreads({ feature, status, type } = {}) {
+  const state = ensureThreadsSection(loadState());
+  let threads = Object.values(state.threads);
+
+  if (feature) threads = threads.filter(t => t.feature === feature);
+  if (status) threads = threads.filter(t => t.status === status);
+  if (type) threads = threads.filter(t => t.type === type);
+
+  return threads.sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt));
+}
+
+/**
+ * Start a thread (pending → running)
+ * @param {string} id - Thread ID
+ * @returns {Object} Updated thread
+ */
+export function startThread(id) {
+  const now = new Date().toISOString();
+  return updateThread(id, {
+    status: THREAD_STATUS.RUNNING,
+    startedAt: now
+  });
+}
+
+/**
+ * Complete a thread (running → completed)
+ * @param {string} id - Thread ID
+ * @param {Object} [result] - Optional result metadata
+ * @returns {Object} Updated thread
+ */
+export function completeThread(id, result = {}) {
+  const thread = getThread(id);
+  if (!thread) throw new Error(`Thread not found: ${id}`);
+
+  const now = new Date();
+  const startedAt = thread.startedAt ? new Date(thread.startedAt) : now;
+  const duration = Math.round((now - startedAt) / 1000); // seconds
+
+  return updateThread(id, {
+    status: THREAD_STATUS.COMPLETED,
+    completedAt: now.toISOString(),
+    duration,
+    result
+  });
+}
+
+/**
+ * Mark a thread as failed
+ * @param {string} id - Thread ID
+ * @param {string} reason - Failure reason
+ * @returns {Object} Updated thread
+ */
+export function failThread(id, reason = '') {
+  const thread = getThread(id);
+  if (!thread) throw new Error(`Thread not found: ${id}`);
+
+  const now = new Date();
+  const startedAt = thread.startedAt ? new Date(thread.startedAt) : now;
+  const duration = Math.round((now - startedAt) / 1000);
+
+  return updateThread(id, {
+    status: THREAD_STATUS.FAILED,
+    completedAt: now.toISOString(),
+    duration,
+    failureReason: reason
+  });
+}
+
+/**
+ * Kill (terminate) a running thread
+ * @param {string} id - Thread ID
+ * @returns {Object} Updated thread
+ */
+export function killThread(id) {
+  const thread = getThread(id);
+  if (!thread) throw new Error(`Thread not found: ${id}`);
+  if (thread.status === THREAD_STATUS.COMPLETED || thread.status === THREAD_STATUS.KILLED) {
+    throw new Error(`Cannot kill thread in status: ${thread.status}`);
+  }
+
+  const now = new Date();
+  const startedAt = thread.startedAt ? new Date(thread.startedAt) : now;
+  const duration = Math.round((now - startedAt) / 1000);
+
+  return updateThread(id, {
+    status: THREAD_STATUS.KILLED,
+    completedAt: now.toISOString(),
+    duration
+  });
+}
+
+/**
+ * Add an event to a thread's event log
+ * @param {string} id - Thread ID
+ * @param {string} type - Event type
+ * @param {Object} [data] - Event data
+ */
+export function addThreadEvent(id, type, data = {}) {
+  const state = ensureThreadsSection(loadState());
+  const thread = state.threads[id];
+  if (!thread) throw new Error(`Thread not found: ${id}`);
+
+  thread.events = thread.events || [];
+  thread.events.push({
+    type,
+    timestamp: new Date().toISOString(),
+    data
+  });
+
+  saveState(state);
+}
+
+/**
+ * Increment thread metrics counter
+ * @param {string} id - Thread ID
+ * @param {string} metric - Metric name (toolCalls|tokensUsed|checkpointsPassed|checkpointsFailed)
+ * @param {number} [amount=1] - Amount to increment
+ */
+export function incrementThreadMetric(id, metric, amount = 1) {
+  const state = ensureThreadsSection(loadState());
+  const thread = state.threads[id];
+  if (!thread) throw new Error(`Thread not found: ${id}`);
+
+  thread.metrics = thread.metrics || {};
+  thread.metrics[metric] = (thread.metrics[metric] || 0) + amount;
+  saveState(state);
+}
+
+// ============================================================================
+// Analytics
+// ============================================================================
+
+/**
+ * Get analytics for threads belonging to a feature
+ * @param {string} feature - Feature name
+ * @returns {Object} Analytics summary
+ */
+export function getThreadAnalytics(feature) {
+  const threads = listThreads({ feature });
+
+  const byStatus = threads.reduce((acc, t) => {
+    acc[t.status] = (acc[t.status] || 0) + 1;
+    return acc;
+  }, {});
+
+  const byType = threads.reduce((acc, t) => {
+    acc[t.type] = (acc[t.type] || 0) + 1;
+    return acc;
+  }, {});
+
+  const completed = threads.filter(t => t.status === THREAD_STATUS.COMPLETED);
+  const avgDuration = completed.length > 0
+    ? Math.round(completed.reduce((sum, t) => sum + (t.duration || 0), 0) / completed.length)
+    : 0;
+
+  const totalToolCalls = threads.reduce((sum, t) => sum + (t.metrics?.toolCalls || 0), 0);
+  const parallelThreads = threads.filter(t => t.type === THREAD_TYPES.PARALLEL);
+  const avgParallel = parallelThreads.length;
+
+  return {
+    feature,
+    total: threads.length,
+    byStatus,
+    byType,
+    avgDuration,
+    totalToolCalls,
+    parallelEfficiency: {
+      avgParallel,
+      maxParallel: Math.max(...threads.map(() => parallelThreads.length), 0)
+    },
+    checkpointPassRate: threads.reduce((sum, t) => {
+      const p = t.metrics?.checkpointsPassed || 0;
+      const f = t.metrics?.checkpointsFailed || 0;
+      return p + f > 0 ? sum + (p / (p + f)) : sum;
+    }, 0) / Math.max(threads.filter(t => (t.metrics?.checkpointsPassed || 0) + (t.metrics?.checkpointsFailed || 0) > 0).length, 1)
+  };
+}