@polymorphism-tech/morph-spec 4.8.18 → 4.9.0

package/src/lib/execution/fusion-executor.js

@@ -1,304 +0,0 @@
-/**
- * Fusion Executor — F-Thread best-of-N aggregation
- *
- * Runs N parallel agents on the same prompt, collects results,
- * then aggregates using one of three strategies:
- *   - best-of-n: score each result, pick highest (automated)
- *   - consensus: merge common elements from all results
- *   - manual-select: present all N to user for selection
- *
- * Returns: { winner, allResults, scores }
- */
-
-import { createThread, startThread, completeThread, failThread, THREAD_TYPES } from '../threads/thread-manager.js';
-import { recordEvent, generateAsciiChart } from '../analytics/analytics-engine.js';
-
-// ============================================================================
-// Scoring
-// ============================================================================
-
-/**
- * Score a fusion result based on completeness, compliance, and quality
- * @param {Object} result - Agent result object
- * @param {Object} [rubric] - Scoring rubric
- * @returns {number} Score 0-100
- */
-export function scoreResult(result, rubric = {}) {
-  let score = 0;
-  const weights = {
-    completeness: rubric.completenessWeight || 40,
-    checkpointCompliance: rubric.complianceWeight || 30,
-    codeQuality: rubric.qualityWeight || 30
-  };
-
-  // Completeness: does it have all required deliverables?
-  if (result.deliverables) {
-    const required = rubric.requiredDeliverables?.length || 1;
-    const provided = Object.keys(result.deliverables).length;
-    score += weights.completeness * Math.min(provided / required, 1.0);
-  } else if (result.content) {
-    // Estimate completeness from content length
-    const targetLength = rubric.targetLength || 1000;
-    score += weights.completeness * Math.min(result.content.length / targetLength, 1.0);
-  } else {
-    score += weights.completeness * 0.5; // Partial credit
-  }
-
-  // Checkpoint compliance: did it follow patterns?
-  if (result.checkpointsPassed !== undefined) {
-    const total = (result.checkpointsPassed || 0) + (result.checkpointsFailed || 0);
-    const passRate = total > 0 ? result.checkpointsPassed / total : 0.8; // Assume 80% if unknown
-    score += weights.checkpointCompliance * passRate;
-  } else {
-    score += weights.checkpointCompliance * 0.8; // Default: assume compliant
-  }
-
-  // Code quality: based on error count and warnings
-  const errors = result.errors || 0;
-  const warnings = result.warnings || 0;
-  const qualityScore = Math.max(0, 1.0 - (errors * 0.2) - (warnings * 0.05));
-  score += weights.codeQuality * qualityScore;
-
-  return Math.round(score);
-}
-
-// ============================================================================
-// Aggregation Strategies
-// ============================================================================
-
-/**
- * Best-of-N aggregation: score each result, return highest scorer
- * @param {Array} results - Array of agent results
- * @param {Object} rubric - Scoring rubric
- * @returns {Object} { winner, scores }
- */
-export function aggregateBestOfN(results, rubric = {}) {
-  const scored = results.map((result, idx) => ({
-    index: idx,
-    agentId: result.agentId || `agent-${idx}`,
-    result,
-    score: scoreResult(result, rubric)
-  }));
-
-  scored.sort((a, b) => b.score - a.score);
-  const winner = scored[0];
-
-  return {
-    winner: winner.result,
-    winnerId: winner.agentId,
-    winnerScore: winner.score,
-    scores: scored.map(s => ({
-      agentId: s.agentId,
-      score: s.score,
-      rank: scored.indexOf(s) + 1
-    }))
-  };
-}
-
-/**
- * Consensus aggregation: merge common elements from all results
- * @param {Array} results - Array of agent results
- * @returns {Object} { merged, commonElements }
- */
-export function aggregateConsensus(results) {
-  if (results.length === 0) return { merged: {}, commonElements: [] };
-  if (results.length === 1) return { merged: results[0], commonElements: [] };
-
-  // Find common keys across all results
-  const allKeys = results.map(r => Object.keys(r));
-  const commonKeys = allKeys[0].filter(key =>
-    allKeys.every(keys => keys.includes(key))
-  );
-
-  const merged = {};
-  const commonElements = [];
-
-  for (const key of commonKeys) {
-    const values = results.map(r => r[key]);
-
-    // For strings: use longest (most complete) version
-    if (values.every(v => typeof v === 'string')) {
-      merged[key] = values.reduce((longest, v) =>
-        v.length > longest.length ? v : longest, ''
-      );
-      commonElements.push(key);
-    }
-    // For arrays: union of all arrays
-    else if (values.every(v => Array.isArray(v))) {
-      merged[key] = [...new Set(values.flat())];
-      commonElements.push(key);
-    }
-    // For objects: merge recursively (simple one level)
-    else if (values.every(v => v && typeof v === 'object')) {
-      merged[key] = Object.assign({}, ...values);
-      commonElements.push(key);
-    }
-    // For primitives: use majority value
-    else {
-      const valueCounts = values.reduce((acc, v) => {
-        const key2 = String(v);
-        acc[key2] = (acc[key2] || 0) + 1;
-        return acc;
-      }, {});
-      const [majority] = Object.entries(valueCounts).sort(([, a], [, b]) => b - a);
-      merged[key] = majority ? JSON.parse(majority[0]) : values[0];
-      commonElements.push(key);
-    }
-  }
-
-  return { merged, commonElements };
-}
-
-// ============================================================================
-// Main Fusion Runner
-// ============================================================================
-
-/**
- * Run fusion execution: spawn N agents in parallel, collect and aggregate results
- * @param {Object} opts
- * @param {string} opts.feature - Feature name
- * @param {string} opts.prompt - Prompt/mission for all agents
- * @param {number} [opts.count=3] - Number of agents to run
- * @param {string} [opts.strategy='best-of-n'] - Aggregation strategy
- * @param {string[]} [opts.agents] - Agent IDs to use (will use thread types if not specified)
- * @param {Object} [opts.rubric] - Scoring rubric for best-of-n
- * @returns {Promise<Object>} { winner, allResults, scores, strategy, threads }
- */
-export async function runFusion(prompt, {
-  feature,
-  count = 3,
-  strategy = 'best-of-n',
-  agents = null,
-  rubric = {}
-} = {}) {
-  const { randomUUID } = await import('crypto');
-  const sessionId = randomUUID();
-  const agentList = agents || Array.from({ length: count }, (_, i) => `fusion-agent-${i + 1}`);
-  const threads = [];
-  const results = [];
-
-  recordEvent({
-    type: 'fusion_started',
-    feature,
-    data: { count, strategy, agents: agentList }
-  });
-
-  // Create and start all fusion threads simultaneously
-  for (let i = 0; i < agentList.length; i++) {
-    const thread = createThread({
-      feature,
-      type: THREAD_TYPES.FUSION,
-      agent: agentList[i],
-      mission: prompt,
-      meta: { fusionIndex: i, strategy }
-    });
-    startThread(thread.id);
-    threads.push(thread);
-  }
-
-  console.log(`  [fusion] ${threads.length} agents spawned. Collecting results...`);
-
-  // In a real system, results would come from actual sub-agent execution.
-  // Here we return thread configs for the calling code to use with Task tool.
-  // The aggregation is designed to be called after results are collected.
-
-  return {
-    id: sessionId,
-    threads,
-    strategy,
-    feature,
-    prompt,
-    agentConfigs: agentList.map((agentId, i) => ({
-      agentId,
-      threadId: threads[i].id,
-      mission: prompt
-    })),
-    aggregate: (collectedResults) => aggregateResults(collectedResults, strategy, rubric)
-  };
-}
-
-/**
- * Aggregate collected results from N agents
- * @param {Array} results - Array of result objects from agents
- * @param {string} strategy - Aggregation strategy
- * @param {Object} [rubric] - Scoring rubric for best-of-n
- * @returns {Object} Aggregated result
- */
-export function aggregateResults(results, strategy = 'best-of-n', rubric = {}) {
-  if (!results || results.length === 0) {
-    throw new Error('No results to aggregate');
-  }
-
-  let aggregated;
-
-  switch (strategy) {
-    case 'best-of-n':
-      aggregated = aggregateBestOfN(results, rubric);
-      break;
-
-    case 'consensus':
-      const { merged, commonElements } = aggregateConsensus(results);
-      aggregated = {
-        winner: merged,
-        winnerId: 'consensus',
-        scores: results.map((_, i) => ({
-          agentId: `agent-${i}`,
-          score: 0,
-          rank: i + 1
-        })),
-        commonElements
-      };
-      break;
-
-    case 'manual-select':
-      aggregated = {
-        winner: null,
-        winnerId: null,
-        allResults: results,
-        requiresUserSelection: true,
-        scores: results.map((r, i) => ({
-          agentId: r.agentId || `agent-${i}`,
-          score: scoreResult(r, rubric),
-          rank: i + 1
-        }))
-      };
-      break;
-
-    default:
-      throw new Error(`Unknown aggregation strategy: ${strategy}`);
-  }
-
-  return {
-    ...aggregated,
-    strategy,
-    totalAgents: results.length,
-    allResults: results
-  };
-}
-
-/**
- * Display fusion results summary
- * @param {Object} fusionResult - Result from aggregateResults
- */
-export function displayFusionSummary(fusionResult) {
-  const { strategy, totalAgents, scores, winner, requiresUserSelection } = fusionResult;
-
-  console.log(`\n  Fusion Results — ${strategy} (${totalAgents} agents)\n`);
-  console.log('  ' + '─'.repeat(50));
-
-  if (scores) {
-    const scoreData = {};
-    scores.forEach(s => { scoreData[s.agentId] = s.score; });
-    console.log(generateAsciiChart(scoreData, { title: 'Agent Scores' }));
-  }
-
-  if (requiresUserSelection) {
-    console.log('\n  Manual selection required — review results above');
-  } else if (winner) {
-    console.log(`\n  Winner: ${fusionResult.winnerId || 'consensus'}`);
-    if (fusionResult.winnerScore !== undefined) {
-      console.log(`  Score: ${fusionResult.winnerScore}/100`);
-    }
-  }
-  console.log('');
-}

package/src/lib/execution/parallel-executor.js

@@ -1,270 +0,0 @@
-/**
- * Parallel Executor — P-Thread concurrent agent spawning
- *
- * Manages concurrent thread execution for parallel feature development.
- * Configurable max-concurrent (1-5, default 3).
- *
- * Thread types supported:
- *   P-Thread — Parallel execution (multiple agents simultaneously)
- *   Managed via thread-manager.js + analytics-engine.js
- */
-
-import { createThread, startThread, completeThread, failThread, listThreads, THREAD_TYPES, THREAD_STATUS } from '../threads/thread-manager.js';
-import { recordEvent } from '../analytics/analytics-engine.js';
-
-const DEFAULT_MAX_CONCURRENT = 3;
-const MAX_CONCURRENT_LIMIT = 5;
-
-// ============================================================================
-// Parallel Execution
-// ============================================================================
-
-/**
- * Spawn N threads in parallel for the same feature
- * @param {Object} opts
- * @param {string} opts.feature - Feature name
- * @param {Array} opts.threadConfigs - Array of { agent, mission, meta } configs
- * @param {number} [opts.maxConcurrent=3] - Maximum concurrent threads
- * @returns {Promise<Array>} Array of created thread objects
- */
-export async function spawnParallel({ feature, threadConfigs, maxConcurrent = DEFAULT_MAX_CONCURRENT }) {
-  const limit = Math.min(maxConcurrent, MAX_CONCURRENT_LIMIT);
-
-  if (!threadConfigs || threadConfigs.length === 0) {
-    throw new Error('threadConfigs is required and must be non-empty');
-  }
-
-  const threads = [];
-  const batches = chunkArray(threadConfigs, limit);
-
-  recordEvent({
-    type: 'parallel_spawn_started',
-    feature,
-    data: {
-      totalThreads: threadConfigs.length,
-      maxConcurrent: limit,
-      batches: batches.length
-    }
-  });
-
-  for (const batch of batches) {
-    const batchThreads = batch.map(config =>
-      createThread({
-        feature,
-        type: THREAD_TYPES.PARALLEL,
-        agent: config.agent,
-        mission: config.mission,
-        meta: { ...config.meta, maxConcurrent: limit }
-      })
-    );
-
-    threads.push(...batchThreads);
-
-    // Mark all batch threads as running simultaneously
-    for (const t of batchThreads) {
-      startThread(t.id);
-    }
-
-    recordEvent({
-      type: 'parallel_batch_started',
-      feature,
-      data: {
-        batchSize: batch.length,
-        threadIds: batchThreads.map(t => t.id),
-        concurrency: batch.length
-      }
-    });
-  }
-
-  return threads;
-}
-
-/**
- * Coordinate parallel thread lifecycle — wait for all to complete
- * @param {string} feature - Feature name
- * @param {string[]} threadIds - Thread IDs to track
- * @param {Object} [opts]
- * @param {number} [opts.pollIntervalMs=5000] - Poll interval
- * @param {number} [opts.timeoutMs=3600000] - Max wait (1 hour default)
- * @returns {Promise<Object>} { completed, failed, duration }
- */
-export async function coordinateParallel(feature, threadIds, {
-  pollIntervalMs = 5000,
-  timeoutMs = 3600000
-} = {}) {
-  const start = Date.now();
-  const completed = [];
-  const failed = [];
-  const remaining = new Set(threadIds);
-
-  while (remaining.size > 0 && Date.now() - start < timeoutMs) {
-    for (const id of [...remaining]) {
-      const threads = listThreads({ feature });
-      const thread = threads.find(t => t.id === id);
-
-      if (!thread) {
-        remaining.delete(id);
-        continue;
-      }
-
-      if (thread.status === THREAD_STATUS.COMPLETED) {
-        completed.push(id);
-        remaining.delete(id);
-      } else if (thread.status === THREAD_STATUS.FAILED || thread.status === THREAD_STATUS.KILLED) {
-        failed.push(id);
-        remaining.delete(id);
-      }
-    }
-
-    if (remaining.size > 0) {
-      await sleep(pollIntervalMs);
-    }
-  }
-
-  const duration = Math.round((Date.now() - start) / 1000);
-
-  if (remaining.size > 0) {
-    recordEvent({
-      type: 'parallel_timeout',
-      feature,
-      data: { timedOut: [...remaining], duration }
-    });
-  }
-
-  recordEvent({
-    type: 'parallel_coordination_complete',
-    feature,
-    data: { completed: completed.length, failed: failed.length, duration }
-  });
-
-  return { completed, failed, timedOut: [...remaining], duration };
-}
-
-/**
- * Wait until all specified threads complete
- * @param {string} feature - Feature name
- * @param {string[]} threadIds - Thread IDs to wait for
- * @param {number} [timeoutMs=3600000] - Max wait time
- * @returns {Promise<Object>} Coordination result
- */
-export async function waitAll(feature, threadIds, timeoutMs = 3600000) {
-  return coordinateParallel(feature, threadIds, { timeoutMs });
-}
-
-/**
- * Wait until any thread completes, then return it
- * @param {string} feature - Feature name
- * @param {string[]} threadIds - Thread IDs to watch
- * @param {number} [timeoutMs=3600000] - Max wait time
- * @returns {Promise<Object|null>} First completed/failed thread or null on timeout
- */
-export async function waitAny(feature, threadIds, timeoutMs = 3600000) {
-  const start = Date.now();
-  const idSet = new Set(threadIds);
-
-  while (Date.now() - start < timeoutMs) {
-    const threads = listThreads({ feature });
-    for (const thread of threads) {
-      if (idSet.has(thread.id)) {
-        if (thread.status === THREAD_STATUS.COMPLETED || thread.status === THREAD_STATUS.FAILED) {
-          return thread;
-        }
-      }
-    }
-    await sleep(3000);
-  }
-
-  return null;
-}
-
-// ============================================================================
-// Efficiency Metrics
-// ============================================================================
-
-/**
- * Plan parallel execution batches without spawning threads
- * @param {Object} opts
- * @param {Array} opts.threadConfigs - Array of { agent, mission } configs
- * @param {number} [opts.maxConcurrent=3] - Max concurrent threads
- * @returns {Object} { batches, totalThreads, maxConcurrent, batchCount }
- */
-export function planParallelBatches({ threadConfigs, maxConcurrent = DEFAULT_MAX_CONCURRENT }) {
-  const limit = Math.min(maxConcurrent, MAX_CONCURRENT_LIMIT);
-  const batches = chunkArray(threadConfigs, limit);
-  return {
-    batches,
-    totalThreads: threadConfigs.length,
-    maxConcurrent: limit,
-    batchCount: batches.length
-  };
-}
-
-/**
- * Calculate parallel execution efficiency
- * @param {string|Object} featureOrOpts - Feature name, or { totalTasks, waves, maxConcurrent }
- * @returns {Object} Efficiency metrics (efficiency is 0-1 when given opts, 0-100 for real threads)
- */
-export function getParallelEfficiency(featureOrOpts) {
-  // Accept stats object for testing/preview
-  if (featureOrOpts && typeof featureOrOpts === 'object' && 'totalTasks' in featureOrOpts) {
-    const { totalTasks, waves, maxConcurrent = DEFAULT_MAX_CONCURRENT } = featureOrOpts;
-    const serialSteps = Math.ceil(totalTasks / Math.max(maxConcurrent, 1));
-    const efficiency = waves > 0 ? Math.min(1, serialSteps / waves) : 0;
-    return { totalTasks, waves, maxConcurrent, efficiency: Math.round(efficiency * 100) / 100 };
-  }
-
-  const feature = featureOrOpts;
-  const threads = listThreads({ feature, type: THREAD_TYPES.PARALLEL });
-
-  if (threads.length === 0) {
-    return {
-      feature,
-      parallelThreads: 0,
-      avgParallel: 0,
-      maxParallel: 0,
-      efficiency: 0
-    };
-  }
-
-  // Group by time windows to estimate concurrent execution
-  const completed = threads.filter(t => t.completedAt && t.startedAt);
-  let maxParallel = 0;
-
-  if (completed.length > 1) {
-    // Find the time when most threads were running simultaneously
-    for (const t1 of completed) {
-      const concurrent = completed.filter(t2 =>
-        t2.startedAt <= t1.completedAt && t2.completedAt >= t1.startedAt
-      ).length;
-      if (concurrent > maxParallel) maxParallel = concurrent;
-    }
-  } else {
-    maxParallel = threads.length;
-  }
-
-  const avgParallel = threads.length / Math.max(1, Math.ceil(threads.length / maxParallel));
-
-  return {
-    feature,
-    parallelThreads: threads.length,
-    avgParallel: Math.round(avgParallel * 10) / 10,
-    maxParallel,
-    efficiency: Math.round(avgParallel / Math.max(maxParallel, 1) * 100)
-  };
-}
-
-// ============================================================================
-// Helpers
-// ============================================================================
-
-function chunkArray(arr, size) {
-  const chunks = [];
-  for (let i = 0; i < arr.length; i += size) {
-    chunks.push(arr.slice(i, i + size));
-  }
-  return chunks;
-}
-
-function sleep(ms) {
-  return new Promise(resolve => setTimeout(resolve, ms));
-}