@holoscript/framework 6.0.3

package/src/protocol/micro-phase-decomposer.ts

@@ -0,0 +1,299 @@
+/**
+ * MicroPhaseDecomposer — LLM-powered parallel task decomposition (FW-0.2)
+ *
+ * Takes a complex task description, uses an LLM to break it into independent
+ * micro-phases with dependency edges, then builds a wave-based execution plan
+ * where each wave runs in parallel.
+ *
+ * Two modes:
+ * 1. LLM-powered: `decompose()` calls the LLM to analyze task complexity
+ * 2. Manual: `decomposeManual()` accepts pre-defined phases (for testing / deterministic use)
+ *
+ * Wired into Team: when a task's estimated complexity exceeds a threshold,
+ * the team decomposes it before distributing sub-phases to agents.
+ */
+
+import type { ModelConfig } from '../types';
+import { callLLM } from '../llm/llm-adapter';
+import type { LLMMessage } from '../llm/llm-adapter';
+
+// ── Public Types ──
+
+export interface TaskDescription {
+  id: string;
+  title: string;
+  description: string;
+  requiredCapabilities?: string[];
+  maxParallelism?: number;
+  complexityThreshold?: number;
+}
+
+export interface MicroPhase {
+  id: string;
+  description: string;
+  dependencies: string[];
+  estimatedDuration: number;
+  requiredCapabilities: string[];
+}
+
+export interface WaveExecutionPlan {
+  waves: MicroPhase[][];
+  totalEstimatedDuration: number;
+  parallelizationRatio: number;
+  phaseCount: number;
+}
+
+export interface DecompositionResult {
+  taskId: string;
+  phases: MicroPhase[];
+  plan: WaveExecutionPlan;
+  wasDecomposed: boolean;
+}
+
+// ── Complexity Threshold ──
+
+/** Tasks with fewer than this many estimated sub-steps skip decomposition. */
+const DEFAULT_COMPLEXITY_THRESHOLD = 2;
+
+// ── LLM Adapter Interface (injectable for testing) ──
+
+export interface LLMAdapter {
+  call(messages: LLMMessage[], options?: { maxTokens?: number; temperature?: number }): Promise<string>;
+}
+
+/** Create an LLMAdapter from a ModelConfig */
+export function createLLMAdapter(config: ModelConfig): LLMAdapter {
+  return {
+    async call(messages, options) {
+      const response = await callLLM(config, messages, options);
+      return response.content;
+    },
+  };
+}
+
+// ── Decomposer ──
+
+export class SmartMicroPhaseDecomposer {
+  constructor(private llm: LLMAdapter) {}
+
+  /**
+   * Decompose a complex task into parallel micro-phases using LLM analysis.
+   * Returns phases with dependency edges and a wave-based execution plan.
+   */
+  async decompose(task: TaskDescription): Promise<DecompositionResult> {
+    const threshold = task.complexityThreshold ?? DEFAULT_COMPLEXITY_THRESHOLD;
+
+    const messages: LLMMessage[] = [
+      {
+        role: 'system',
+        content: `You are a task decomposition engine. Break complex tasks into independent micro-phases.
+
+Output ONLY valid JSON matching this schema:
+{
+  "phases": [
+    {
+      "id": "phase_1",
+      "description": "what this phase does",
+      "dependencies": [],
+      "estimatedDuration": 5000,
+      "requiredCapabilities": ["coding"]
+    }
+  ]
+}
+
+Rules:
+- Each phase must have a unique id (phase_1, phase_2, etc.)
+- dependencies is an array of phase ids this phase depends on
+- estimatedDuration is in milliseconds
+- requiredCapabilities: one or more of ["coding", "research", "review", "testing", "architecture"]
+- Maximize parallelism: only add dependencies when truly required
+- If the task is simple (1-2 steps), return a single phase
+- Keep phases focused — each should be independently executable`,
+      },
+      {
+        role: 'user',
+        content: `Decompose this task:\n\nTitle: ${task.title}\nDescription: ${task.description}\nCapabilities available: ${(task.requiredCapabilities ?? ['coding']).join(', ')}`,
+      },
+    ];
+
+    const raw = await this.llm.call(messages, { maxTokens: 2048, temperature: 0.3 });
+    const phases = this.parseLLMResponse(raw, task.id);
+
+    if (phases.length < threshold) {
+      return {
+        taskId: task.id,
+        phases,
+        plan: this.buildExecutionPlan(phases),
+        wasDecomposed: false,
+      };
+    }
+
+    // Enforce maxParallelism if set
+    if (task.maxParallelism) {
+      this.enforceParallelismLimit(phases, task.maxParallelism);
+    }
+
+    const plan = this.buildExecutionPlan(phases);
+    return { taskId: task.id, phases, plan, wasDecomposed: true };
+  }
+
+  /**
+   * Manual decomposition — accepts pre-defined phases. Useful for testing
+   * and deterministic pipelines where LLM analysis isn't needed.
+   */
+  decomposeManual(taskId: string, phases: MicroPhase[]): DecompositionResult {
+    this.validatePhases(phases);
+    const plan = this.buildExecutionPlan(phases);
+    return { taskId, phases, plan, wasDecomposed: phases.length > 1 };
+  }
+
+  /**
+   * Build an execution plan from phases — topological sort into parallel waves.
+   * Each wave contains phases that can run simultaneously.
+   */
+  buildExecutionPlan(phases: MicroPhase[]): WaveExecutionPlan {
+    if (phases.length === 0) {
+      return { waves: [], totalEstimatedDuration: 0, parallelizationRatio: 0, phaseCount: 0 };
+    }
+
+    this.validatePhases(phases);
+
+    const sorted = this.topologicalSort(phases);
+    const phaseMap = new Map(phases.map(p => [p.id, p]));
+    const waveAssignment = new Map<string, number>();
+    const waves: MicroPhase[][] = [];
+
+    for (const phaseId of sorted) {
+      const phase = phaseMap.get(phaseId)!;
+      let waveIdx = 0;
+
+      for (const depId of phase.dependencies) {
+        waveIdx = Math.max(waveIdx, (waveAssignment.get(depId) ?? 0) + 1);
+      }
+
+      while (waves.length <= waveIdx) {
+        waves.push([]);
+      }
+      waves[waveIdx].push(phase);
+      waveAssignment.set(phaseId, waveIdx);
+    }
+
+    // Calculate timing
+    const sequentialTime = phases.reduce((sum, p) => sum + p.estimatedDuration, 0);
+    const parallelTime = waves.reduce((sum, wave) => {
+      return sum + Math.max(...wave.map(p => p.estimatedDuration));
+    }, 0);
+
+    return {
+      waves,
+      totalEstimatedDuration: parallelTime,
+      parallelizationRatio: sequentialTime > 0
+        ? Math.round(((sequentialTime - parallelTime) / sequentialTime) * 100)
+        : 0,
+      phaseCount: phases.length,
+    };
+  }
+
+  // ── Internal ──
+
+  private parseLLMResponse(raw: string, taskId: string): MicroPhase[] {
+    try {
+      // Extract JSON from potential markdown code blocks
+      const jsonMatch = raw.match(/```(?:json)?\s*([\s\S]*?)```/) || [null, raw];
+      const cleaned = (jsonMatch[1] ?? raw).trim();
+      const parsed = JSON.parse(cleaned) as { phases?: unknown[] };
+
+      if (!parsed.phases || !Array.isArray(parsed.phases)) {
+        return this.fallbackSinglePhase(taskId);
+      }
+
+      return (parsed.phases as Record<string, unknown>[]).map((p, i) => ({
+        id: String(p.id ?? `phase_${i + 1}`),
+        description: String(p.description ?? 'Unknown phase'),
+        dependencies: Array.isArray(p.dependencies) ? p.dependencies.map(String) : [],
+        estimatedDuration: typeof p.estimatedDuration === 'number' ? p.estimatedDuration : 5000,
+        requiredCapabilities: Array.isArray(p.requiredCapabilities) ? p.requiredCapabilities.map(String) : ['coding'],
+      }));
+    } catch {
+      return this.fallbackSinglePhase(taskId);
+    }
+  }
+
+  private fallbackSinglePhase(taskId: string): MicroPhase[] {
+    return [{
+      id: `${taskId}_single`,
+      description: 'Execute task as single unit',
+      dependencies: [],
+      estimatedDuration: 10000,
+      requiredCapabilities: ['coding'],
+    }];
+  }
+
+  private validatePhases(phases: MicroPhase[]): void {
+    const ids = new Set(phases.map(p => p.id));
+
+    for (const phase of phases) {
+      for (const dep of phase.dependencies) {
+        if (!ids.has(dep)) {
+          throw new Error(`Phase "${phase.id}" depends on unknown phase "${dep}"`);
+        }
+      }
+    }
+
+    // Check for cycles
+    this.topologicalSort(phases); // throws on cycle
+  }
+
+  private topologicalSort(phases: MicroPhase[]): string[] {
+    const phaseMap = new Map(phases.map(p => [p.id, p]));
+    const visited = new Set<string>();
+    const inStack = new Set<string>();
+    const result: string[] = [];
+
+    const dfs = (id: string) => {
+      if (inStack.has(id)) {
+        throw new Error(`Circular dependency detected involving phase "${id}"`);
+      }
+      if (visited.has(id)) return;
+
+      inStack.add(id);
+      const phase = phaseMap.get(id)!;
+      for (const dep of phase.dependencies) {
+        dfs(dep);
+      }
+      inStack.delete(id);
+      visited.add(id);
+      result.push(id);
+    };
+
+    for (const id of phaseMap.keys()) {
+      if (!visited.has(id)) dfs(id);
+    }
+
+    return result;
+  }
+
+  /**
+   * If maxParallelism is set, add synthetic dependencies to limit
+   * the number of phases running concurrently in any wave.
+   */
+  private enforceParallelismLimit(phases: MicroPhase[], maxParallelism: number): void {
+    // Build initial plan to see wave sizes
+    const plan = this.buildExecutionPlan(phases);
+    const phaseMap = new Map(phases.map(p => [p.id, p]));
+
+    for (const wave of plan.waves) {
+      if (wave.length <= maxParallelism) continue;
+
+      // Split oversized wave: phases beyond the limit depend on earlier ones
+      const overflow = wave.slice(maxParallelism);
+      for (let i = 0; i < overflow.length; i++) {
+        const target = phaseMap.get(overflow[i].id)!;
+        const anchor = wave[i % maxParallelism];
+        if (!target.dependencies.includes(anchor.id)) {
+          target.dependencies.push(anchor.id);
+        }
+      }
+    }
+  }
+}

package/src/protocol/micro-step-decomposer.test.ts

@@ -0,0 +1,306 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  SmartMicroPhaseDecomposer,
+  type LLMAdapter,
+  type MicroPhase,
+  type TaskDescription,
+} from './micro-phase-decomposer';
+
+// ── Test Helpers ──
+
+function mockLLM(response: string): LLMAdapter {
+  return { call: vi.fn().mockResolvedValue(response) };
+}
+
+function phase(id: string, deps: string[] = [], duration = 5000, caps: string[] = ['coding']): MicroPhase {
+  return { id, description: `Phase ${id}`, dependencies: deps, estimatedDuration: duration, requiredCapabilities: caps };
+}
+
+const simpleTask: TaskDescription = {
+  id: 'task_1',
+  title: 'Build login page',
+  description: 'Create a login form with email and password fields',
+};
+
+// ── Tests ──
+
+describe('SmartMicroPhaseDecomposer', () => {
+  describe('buildExecutionPlan', () => {
+    it('groups independent phases into the same wave', () => {
+      const llm = mockLLM('');
+      const decomposer = new SmartMicroPhaseDecomposer(llm);
+
+      const phases: MicroPhase[] = [
+        phase('a'),
+        phase('b'),
+        phase('c'),
+      ];
+
+      const plan = decomposer.buildExecutionPlan(phases);
+
+      expect(plan.waves).toHaveLength(1);
+      expect(plan.waves[0]).toHaveLength(3);
+      expect(plan.phaseCount).toBe(3);
+      expect(plan.totalEstimatedDuration).toBe(5000);
+      expect(plan.parallelizationRatio).toBe(67); // (15000-5000)/15000 * 100
+    });
+
+    it('creates sequential waves for dependent phases', () => {
+      const llm = mockLLM('');
+      const decomposer = new SmartMicroPhaseDecomposer(llm);
+
+      const phases: MicroPhase[] = [
+        phase('a'),
+        phase('b', ['a']),
+        phase('c', ['b']),
+      ];
+
+      const plan = decomposer.buildExecutionPlan(phases);
+
+      expect(plan.waves).toHaveLength(3);
+      expect(plan.waves[0].map(p => p.id)).toEqual(['a']);
+      expect(plan.waves[1].map(p => p.id)).toEqual(['b']);
+      expect(plan.waves[2].map(p => p.id)).toEqual(['c']);
+      expect(plan.totalEstimatedDuration).toBe(15000);
+      expect(plan.parallelizationRatio).toBe(0);
+    });
+
+    it('handles diamond dependencies correctly', () => {
+      const llm = mockLLM('');
+      const decomposer = new SmartMicroPhaseDecomposer(llm);
+
+      //   a
+      //  / \
+      // b   c
+      //  \ /
+      //   d
+      const phases: MicroPhase[] = [
+        phase('a'),
+        phase('b', ['a']),
+        phase('c', ['a']),
+        phase('d', ['b', 'c']),
+      ];
+
+      const plan = decomposer.buildExecutionPlan(phases);
+
+      expect(plan.waves).toHaveLength(3);
+      expect(plan.waves[0].map(p => p.id)).toEqual(['a']);
+      expect(plan.waves[1].map(p => p.id).sort()).toEqual(['b', 'c']);
+      expect(plan.waves[2].map(p => p.id)).toEqual(['d']);
+    });
+
+    it('returns empty plan for no phases', () => {
+      const llm = mockLLM('');
+      const decomposer = new SmartMicroPhaseDecomposer(llm);
+      const plan = decomposer.buildExecutionPlan([]);
+
+      expect(plan.waves).toHaveLength(0);
+      expect(plan.totalEstimatedDuration).toBe(0);
+      expect(plan.phaseCount).toBe(0);
+    });
+
+    it('throws on unknown dependency', () => {
+      const llm = mockLLM('');
+      const decomposer = new SmartMicroPhaseDecomposer(llm);
+
+      expect(() => {
+        decomposer.buildExecutionPlan([phase('a', ['nonexistent'])]);
+      }).toThrow('depends on unknown phase');
+    });
+
+    it('throws on circular dependency', () => {
+      const llm = mockLLM('');
+      const decomposer = new SmartMicroPhaseDecomposer(llm);
+
+      const phases: MicroPhase[] = [
+        phase('a', ['b']),
+        phase('b', ['a']),
+      ];
+
+      expect(() => decomposer.buildExecutionPlan(phases)).toThrow('Circular dependency');
+    });
+  });
+
+  describe('decomposeManual', () => {
+    it('creates a plan from manually specified phases', () => {
+      const llm = mockLLM('');
+      const decomposer = new SmartMicroPhaseDecomposer(llm);
+
+      const phases = [phase('setup'), phase('build', ['setup']), phase('test', ['build'])];
+      const result = decomposer.decomposeManual('task_manual', phases);
+
+      expect(result.taskId).toBe('task_manual');
+      expect(result.wasDecomposed).toBe(true);
+      expect(result.plan.waves).toHaveLength(3);
+      expect(result.phases).toHaveLength(3);
+    });
+
+    it('marks single-phase tasks as not decomposed', () => {
+      const llm = mockLLM('');
+      const decomposer = new SmartMicroPhaseDecomposer(llm);
+
+      const result = decomposer.decomposeManual('task_simple', [phase('only')]);
+
+      expect(result.wasDecomposed).toBe(false);
+      expect(result.plan.waves).toHaveLength(1);
+    });
+  });
+
+  describe('decompose (LLM-powered)', () => {
+    it('parses well-formed LLM JSON response', async () => {
+      const llmResponse = JSON.stringify({
+        phases: [
+          { id: 'phase_1', description: 'Setup project', dependencies: [], estimatedDuration: 3000, requiredCapabilities: ['coding'] },
+          { id: 'phase_2', description: 'Write components', dependencies: ['phase_1'], estimatedDuration: 8000, requiredCapabilities: ['coding'] },
+          { id: 'phase_3', description: 'Write tests', dependencies: ['phase_1'], estimatedDuration: 5000, requiredCapabilities: ['testing'] },
+          { id: 'phase_4', description: 'Integration test', dependencies: ['phase_2', 'phase_3'], estimatedDuration: 4000, requiredCapabilities: ['testing'] },
+        ],
+      });
+
+      const llm = mockLLM(llmResponse);
+      const decomposer = new SmartMicroPhaseDecomposer(llm);
+      const result = await decomposer.decompose(simpleTask);
+
+      expect(result.wasDecomposed).toBe(true);
+      expect(result.phases).toHaveLength(4);
+      expect(result.plan.waves).toHaveLength(3);
+      // Wave 0: phase_1, Wave 1: phase_2 + phase_3, Wave 2: phase_4
+      expect(result.plan.waves[1]).toHaveLength(2);
+    });
+
+    it('extracts JSON from markdown code blocks', async () => {
+      const llmResponse = '```json\n{"phases": [{"id": "p1", "description": "Do it", "dependencies": [], "estimatedDuration": 5000, "requiredCapabilities": ["coding"]}]}\n```';
+
+      const llm = mockLLM(llmResponse);
+      const decomposer = new SmartMicroPhaseDecomposer(llm);
+      const result = await decomposer.decompose({ ...simpleTask, complexityThreshold: 1 });
+
+      expect(result.phases).toHaveLength(1);
+      expect(result.phases[0].id).toBe('p1');
+    });
+
+    it('falls back to single phase on unparseable LLM output', async () => {
+      const llm = mockLLM('I cannot decompose this task because reasons.');
+      const decomposer = new SmartMicroPhaseDecomposer(llm);
+      const result = await decomposer.decompose(simpleTask);
+
+      expect(result.phases).toHaveLength(1);
+      expect(result.wasDecomposed).toBe(false);
+      expect(result.phases[0].id).toContain('task_1');
+    });
+
+    it('falls back on missing phases array', async () => {
+      const llm = mockLLM(JSON.stringify({ steps: ['a', 'b'] }));
+      const decomposer = new SmartMicroPhaseDecomposer(llm);
+      const result = await decomposer.decompose(simpleTask);
+
+      expect(result.phases).toHaveLength(1);
+      expect(result.wasDecomposed).toBe(false);
+    });
+
+    it('does not mark as decomposed when below complexity threshold', async () => {
+      const llmResponse = JSON.stringify({
+        phases: [{ id: 'only', description: 'Just do it', dependencies: [], estimatedDuration: 3000, requiredCapabilities: ['coding'] }],
+      });
+
+      const llm = mockLLM(llmResponse);
+      const decomposer = new SmartMicroPhaseDecomposer(llm);
+      // Default threshold = 2, single phase returned
+      const result = await decomposer.decompose(simpleTask);
+
+      expect(result.wasDecomposed).toBe(false);
+    });
+
+    it('respects custom complexity threshold', async () => {
+      const llmResponse = JSON.stringify({
+        phases: [
+          { id: 'a', description: 'Step A', dependencies: [], estimatedDuration: 3000, requiredCapabilities: ['coding'] },
+          { id: 'b', description: 'Step B', dependencies: [], estimatedDuration: 3000, requiredCapabilities: ['coding'] },
+        ],
+      });
+
+      const llm = mockLLM(llmResponse);
+      const decomposer = new SmartMicroPhaseDecomposer(llm);
+      const result = await decomposer.decompose({ ...simpleTask, complexityThreshold: 3 });
+
+      expect(result.wasDecomposed).toBe(false);
+    });
+
+    it('enforces maxParallelism by adding synthetic dependencies', async () => {
+      const llmResponse = JSON.stringify({
+        phases: [
+          { id: 'a', description: 'A', dependencies: [], estimatedDuration: 3000, requiredCapabilities: ['coding'] },
+          { id: 'b', description: 'B', dependencies: [], estimatedDuration: 3000, requiredCapabilities: ['coding'] },
+          { id: 'c', description: 'C', dependencies: [], estimatedDuration: 3000, requiredCapabilities: ['coding'] },
+          { id: 'd', description: 'D', dependencies: [], estimatedDuration: 3000, requiredCapabilities: ['coding'] },
+        ],
+      });
+
+      const llm = mockLLM(llmResponse);
+      const decomposer = new SmartMicroPhaseDecomposer(llm);
+      const result = await decomposer.decompose({ ...simpleTask, maxParallelism: 2 });
+
+      // With maxParallelism=2, no wave should have more than 2 phases
+      for (const wave of result.plan.waves) {
+        expect(wave.length).toBeLessThanOrEqual(2);
+      }
+      expect(result.wasDecomposed).toBe(true);
+    });
+
+    it('sends correct prompt to LLM', async () => {
+      const llm = mockLLM(JSON.stringify({ phases: [] }));
+      const decomposer = new SmartMicroPhaseDecomposer(llm);
+
+      await decomposer.decompose({
+        ...simpleTask,
+        requiredCapabilities: ['coding', 'testing'],
+      });
+
+      expect(llm.call).toHaveBeenCalledTimes(1);
+      const [messages, options] = (llm.call as ReturnType<typeof vi.fn>).mock.calls[0];
+      expect(messages).toHaveLength(2);
+      expect(messages[0].role).toBe('system');
+      expect(messages[1].content).toContain('Build login page');
+      expect(messages[1].content).toContain('coding, testing');
+      expect(options?.temperature).toBe(0.3);
+    });
+  });
+
+  describe('parallelization ratio', () => {
+    it('calculates correct ratio for mixed parallel/serial', () => {
+      const llm = mockLLM('');
+      const decomposer = new SmartMicroPhaseDecomposer(llm);
+
+      // a(5s) and b(5s) in parallel, c(5s) depends on both
+      const phases = [
+        phase('a', [], 5000),
+        phase('b', [], 5000),
+        phase('c', ['a', 'b'], 5000),
+      ];
+      const plan = decomposer.buildExecutionPlan(phases);
+
+      // Sequential: 15000ms, Parallel: 5000 + 5000 = 10000ms
+      // Ratio: (15000-10000)/15000 = 33%
+      expect(plan.totalEstimatedDuration).toBe(10000);
+      expect(plan.parallelizationRatio).toBe(33);
+    });
+
+    it('gives 100% ratio when all phases run in parallel (impossible with int rounding but approaches)', () => {
+      const llm = mockLLM('');
+      const decomposer = new SmartMicroPhaseDecomposer(llm);
+
+      // All independent, same duration
+      const phases = [
+        phase('a', [], 1000),
+        phase('b', [], 1000),
+        phase('c', [], 1000),
+        phase('d', [], 1000),
+      ];
+      const plan = decomposer.buildExecutionPlan(phases);
+
+      // Sequential: 4000, Parallel: 1000
+      expect(plan.totalEstimatedDuration).toBe(1000);
+      expect(plan.parallelizationRatio).toBe(75);
+    });
+  });
+});